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 non personali per uso proprio. Non includere dati personali né dati di categorie particolari. Max 4 KB.

Tieni i dati personali fuori da metadata

Non inviare dati personali non necessari e non inviare mai dati di categorie particolari (articolo 9 del GDPR — ad esempio dati su salute, origine etnica, religione o opinioni politiche) nel campo metadata. Selgeo non tratta intenzionalmente dati di categorie particolari e non è in grado di rilevarli in modo affidabile nei campi a testo libero, pertanto escluderli è una tua responsabilità in quanto titolare del trattamento. Nota che prospect_email è un dato personale: lo fornisci esclusivamente per il rilevamento delle frodi da auto-segnalazione e viene trattato sotto la tua responsabilità di titolare del trattamento.

Esempio di richiesta

curl -X POST https://app.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

Test

1. Configura un programma di test e un partner. Crea il programma nella dashboard del merchant e invita un partner di test, poi accedi al portale partner come quel partner e crea un link di referral (nella sezione Link).
2. Visita il tuo sito tramite il link di tracciamento per registrare un clic.
3. Leggi il click_id dalla console del browser:

   __selgeo.getClickId()

4. Invia una conversione di test dal tuo terminale:

   curl -X POST https://app.selgeo.com/api/v1/conversions \
     -H "Authorization: Bearer sk_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "click_id": "INCOLLA_QUI_IL_CLICK_ID",
       "external_transaction_id": "test_001",
       "event_type": "signup",
       "amount_cents": 0
     }'

5. Controlla la risposta — attributed dovrebbe essere true e attribution_source dovrebbe essere "link".
6. Verifica nella dashboard — la conversione dovrebbe apparire in Analytics, attribuita al partner di test.

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