Passa al contenuto principale
In questa pagina

Utilizza una chiave idempotente quando un errore di rete o un timeout del client rendono incerto il risultato di una richiesta che modifica lo stato. DEUNA associa la chiave all'operazione e al corpo della richiesta, quindi riproduce la risposta memorizzata invece di elaborare nuovamente la stessa operazione.

Flusso di riprova#

01 · merchant
Memorizza una sola chiave
Genera un UUID v4 e memorizzalo con l'operazione commerciale prima di inviare la richiesta.
02 · DEUNA
Elabora o riproduce
DEUNA elabora la prima richiesta o riproduce il risultato memorizzato quando la stessa chiave e il corpo arrivano nuovamente.
03 · merchant
Riconcilia il risultato
Utilizza la risposta e lo stato corrente dell'ordine per decidere se l'operazione è stata completata o può essere riprovata in modo sicuro.

Il merchant possiede la generazione, la persistenza e la tempistica del retry. DEUNA possiede l'associazione tra la chiave, l'operazione, il corpo della richiesta e la risposta memorizzata entro la finestra di conservazione documentata.

Operazioni sostenute#

Invia X-Idempotency-Key con queste operazioni pubbliche:

OperazioniMetodo e percorsoRiferimento
Crea un ordine · Flusso opzionalePOST /merchants/ordersCrea un ordine
Crea un pagamento · Acquisto V2POST /v2/merchants/orders/purchaseCreare un pagamento
Acquisire un pagamento autorizzatoPOST /v2/merchants/orders/{order_token}/captureCattura un pagamento
Annullare un'autorizzazionePOST /merchants/orders/{order_token}/voidAnnullare un'autorizzazione
Rimborsare un pagamentoPOST /v2/merchants/orders/{order_token}/refundRimborsare un pagamento

Non presumere che ogni POST endpoint supporti l'idempotenza. Utilizza l'elenco delle operazioni sopra o verifica se il riferimento all'endpoint include X-Idempotency-Key header.

Genera e memorizza la chiave#

Genera un UUID v4 nel tuo backend merchant per ogni operazione commerciale distinta. Memorizzalo insieme al tuo record dell'operazione prima di chiamare DEUNA.

Genera una chiave in Node.jsJavaScript
const idempotencyKey = crypto.randomUUID();

Segui queste regole:

  • Riutilizza la stessa chiave solo quando riprovi la stessa operazione.
  • Invia esattamente lo stesso corpo della richiesta in ogni riprova. DEUNA confronta l'hash del corpo, quindi anche un corpo semanticamente equivalente serializzato in modo diverso può essere rifiutato.
  • Genera una nuova chiave per un nuovo tentativo di cattura, annullamento, rimborso o creazione dell'ordine.
  • Genera una nuova chiave quando correggi i dati della richiesta dopo un errore di validazione o commerciale.
  • Non derivare le chiavi da una sequenza breve che può collidere in diversi sistemi o ambienti.

La chiave è valida per il merchant e l'operazione, ma la tua integrazione dovrebbe comunque trattarla come univoca e non riutilizzarla deliberatamente per un'altra azione.

Invia la richiesta#

Aggiungi la chiave alla richiesta originale e a ogni riprova di quella richiesta. Questo esempio di Acquisto V2 utilizza un token dell'ordine che l'integrazione ha già creato:

curl --request POST \
  --url https://api.sandbox.deuna.io/v2/merchants/orders/purchase \
  --header "X-Api-Key: YOUR_PRIVATE_API_KEY" \
  --header "X-Idempotency-Key: 9f510c4a-0f7d-4c31-94c5-590b85e4d231" \
  --header "Content-Type: application/json" \
  --data '{
    "order_token": "ORDER_TOKEN",
    "payer_info": {
      "email": "buyer@example.com",
      "external_user_id": "customer_1042"
    },
    "payment_source": {
      "method_type": "credit_card",
      "payment_method": "PAYMENT_METHOD_TOKEN"
    }
  }'

Se la risposta ha X-Idempotency-Replay: true, DEUNA ha restituito il risultato memorizzato per una richiesta precedente con la stessa chiave e corpo. Gestisci il suo codice di stato e il payload esattamente come per la risposta originale.

Comprendi la finestra di conservazione#

L'associazione chiave-corpo inizia quando DEUNA riceve per la prima volta la chiave. La finestra di riproduzione della risposta inizia quando DEUNA memorizza il risultato completato e il suo comportamento dipende da quel risultato:

Risultato originaleComportamento di riproduzione
Risposta di successoDEUNA memorizza la risposta per 24 ore su 24 per impostazione predefinita dopo che l'operazione è stata completata. Un riprova con la stessa chiave e corpo durante quella finestra restituisce il codice di stato, gli header e il payload memorizzati.
4xx o 5xx rispostaDEUNA memorizza la risposta di errore per circa 2 secondi per assorbire duplicati immediati. L'associazione tra la chiave e il corpo della richiesta originale rimane per l'intera durata di 24 ore.
Richiesta in corsoUna richiesta concorrente attende brevemente il primo risultato. Se la prima richiesta è ancora in esecuzione, DEUNA può restituire un codice HTTP 409 con IS-4409.

Dopo la scadenza del periodo di conservazione della risposta di successo, la stessa chiave può essere trattata come una nuova operazione. Non fare affidamento su questo comportamento: creare una nuova chiave per ogni nuova operazione commerciale, anche quando una chiave precedente è scaduta.

Per una risposta di errore, non riutilizzare la chiave con i dati della richiesta corretti. Poiché l'associazione del corpo originale rimane attiva, il corpo modificato viene IS-4401 ritenuto fino alla scadenza del periodo di conservazione. Correggere la richiesta e inviarla come una nuova operazione con una nuova chiave.

Gestire i tentativi e i conflitti#

SituazioneCosa restituisce DEUNACosa dovrebbe fare l'integrazione
Stessa chiave e stesso corpo dopo una richiesta di successo completataLa risposta memorizzata con X-Idempotency-Replay: trueaccettare la risposta e riconciliare lo stato dell'ordine corrente quando non è definitivo.
Stessa chiave con un corpo diversoHTTP 400, codice IS-4401Non riprovare questa combinazione. Utilizzare una nuova chiave solo quando il corpo modificato rappresenta un'operazione corretta o nuova.
Arriva un duplicato mentre la prima richiesta è ancora in esecuzioneHTTP 409, codice IS-4409, quando termina l'attesa in corsoRallentare, quindi riprovare la richiesta esatta con la stessa chiave. Riconciliare l'ordine originale prima di avviare un nuovo tentativo.
È stato superato il limite di richiesteHTTP 429, che può includere codice IS-4429Rispettare Retry-After quando presente, quindi riprovare con lo stesso corpo e chiave.
Timeout o perdita di connessione del clientIl client potrebbe non ricevere risposta, anche se l'elaborazione continuaConservare la chiave e il corpo, risolvere l'ordine e riprovare solo seguendo la procedura di timeout documentata.
Validazione o errore di business non riproducibileA 4xx rispostaCorreggere la richiesta e utilizzare una nuova chiave. Non riprovare un corpo modificato con la vecchia chiave.

Utilizzare un backoff esponenziale limitato con jitter. Non inviare più tentativi concorrenti per la stessa operazione di business.

Vedi Errori API per il modello di codice di risposta e timeout dei client per la procedura di riconciliazione.

Verificare il comportamento nell'ambiente sandbox#

  1. Inviare una richiesta supportata valida a https://api.sandbox.deuna.io con una nuova chiave UUID v4.
  2. Salvare il codice di stato, gli header di risposta e il payload.
  3. Inviare esattamente la stessa richiesta di nuovo con la stessa chiave e corpo.
  4. Verificare che la seconda risposta abbia lo stesso risultato e includa X-Idempotency-Replay: true.
  5. Durante un test negativo separato, modificare il corpo ma mantenere la chiave e verificare che DEUNA restituisca un codice HTTP 400 con IS-4401.

Non riutilizzare né la chiave di test per un'altra operazione nell'ambiente sandbox.

Procedere con l'integrazione#