API di conversione

L'API di conversione ti permette di segnalare conversioni non-Stripe a Selgeo — registrazioni, invii di moduli, prove gratuite, aggiornamenti o qualsiasi evento personalizzato. La chiami dal tuo server dopo che avviene una conversione, e Selgeo la attribuisce al partner referente basandosi su un click_id o un promo_code.

Versione API: v1

Endpoint: POST /api/v1/conversions

Autenticazione

Authorization: Bearer sk_test_YOUR_KEY

Non esporre mai le chiavi segrete nel codice frontend

Le chiavi segrete (sk_*) devono essere usate solo nel codice lato server.

Corpo della richiesta

Campo	Tipo	Richiesto	Descrizione
click_id	string (UUID)	Condizionale	L'ID clic dallo snippet di tracciamento. Richiesto se promo_code non è fornito.
promo_code	string	Condizionale	Un codice promo per l'attribuzione. Richiesto se click_id non è fornito.
external_transaction_id	string	Sì	Il tuo identificatore univoco per questa conversione. Usato per la deduplicazione. Max 255 caratteri.
event_type	string	Sì	Il tipo di evento di conversione (es. signup, purchase, upgrade). Max 100 caratteri.
amount_cents	integer	No	Il valore della conversione in centesimi. Predefinito: 0.
currency	string	Condizionale	Codice valuta ISO 4217 a 3 lettere. Richiesto quando amount_cents > 0.
occurred_at	string (ISO 8601)	No	Quando è avvenuta la conversione. Predefinito all'ora corrente.
prospect_email	string (email)	No	L'indirizzo email dell'utente che effettua la conversione. Usato per il rilevamento di frodi di auto-referral.
metadata	object	No	Coppie chiave-valore arbitrarie per uso proprio. Max 4 KB.

Esempio di richiesta

curl -X POST https://api.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "external_transaction_id": "signup_12345",
    "event_type": "signup",
    "amount_cents": 0
  }'

Risposta

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source": "conversion_api",
  "event_type": "signup",
  "attributed": true,
  "attribution": {
    "attribution_source": "link",
    "participant_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "explanation": "Attributed to partner via tracking link click"
  }
}

Priorità di attribuzione

Quando vengono forniti sia click_id che promo_code, il codice promo ha la priorità.

Codici di stato HTTP

Stato	Significato
201	Conversione creata con successo
400	Errore di validazione
401	Chiave API non valida o mancante
409	external_transaction_id duplicato
422	Nessun segnale di attribuzione o mismatch modalità
429	Limite di velocità superato

Passaggi successivi

• Webhooks — ricevere notifiche quando le conversioni vengono attribuite
• Modalità test — guida dettagliata per testare la tua integrazione
• Risoluzione dei problemi — problemi comuni e soluzioni