Ripetizioni sicure
Quando una connessione cade, non puoi sapere se il tuo ordine è andato a buon fine. Quindi invialo di nuovo: per 7 giorni la stessa chiave di idempotenza indica lo stesso ordine, e viene addebitato una sola volta.
Come funziona
POST /orders richiede un’intestazione Idempotency-Key: fino a 200 caratteri ASCII senza spazi, che crei tu e conservi con il tuo record dell’ordine. Un UUID va bene. Usa una nuova chiave di idempotenza per un nuovo ordine.
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'Cosa ricevi
201 e il nuovo ordine.200, lo stesso ordine e Idempotent-Replay: true. Non viene addebitato altro, anche se nel frattempo il prezzo è cambiato.order_status_unknown o rate_limited.409 idempotency_conflict. Non viene effettuato alcun ordine.insufficient_balance409 price_changed, e una nuova chiave di idempotenza effettua l’ordine al nuovo prezzo.Quando non lo sai
Qualsiasi risposta persa, order_status_unknown e una risposta non JSON, come un 502 o un 504 di un gateway, significano tutte la stessa cosa: ripeti la richiesta con la stessa chiave di idempotenza per conoscere lo stato reale. Non addebita mai due volte. Non creare mai una nuova chiave di idempotenza perché una richiesta è andata in timeout o non è riuscita: quello è un nuovo ordine, e viene addebitato.
Attendi un minuto tra una ripetizione e l’altra. Se dopo qualche minuto la risposta è ancora order_status_unknown, fermati e contatta l’assistenza indicando il request_id. Non creare una nuova chiave di idempotenza.
Quanto dura una chiave di idempotenza
Una chiave di idempotenza viene ricordata per 7 giorni dal primo invio. Dopo di che la stessa chiave effettua un nuovo ordine, quindi ripeti entro pochi giorni e usa una nuova chiave di idempotenza per ogni nuovo ordine.