Timeout nelle integrazioni ecommerce: evitare un doppio ordine quando si riprova

Parliamo del tuo progetto →

Dopo un timeout, il problema non è solo riprovare o no: è capire se il sistema stia ritentando la stessa operazione oppure stia creando un secondo ordine. È qui che entra in gioco l’idempotenza. Stripe documenta le chiavi di idempotenza per riconoscere richieste ripetute e restituire lo stesso esito alla stessa operazione, con regole e limiti specifici. La guida è utile per le integrazioni ecommerce, ma non va generalizzata a tutti gli API provider. (Stripe)

Perché il problema conta nell’ecommerce

Nei flussi transazionali, un timeout può significare tre cose diverse: la richiesta non è partita, la richiesta è arrivata ma la risposta si è persa, oppure l’operazione è stata eseguita ma il client non lo sa ancora. Se il backend ripete in modo cieco la creazione dell’ordine, rischia un duplicato. Se invece interrompe tutto troppo presto, può perdere un ordine valido. Il punto pratico è distinguere stato incerto e nuova intenzione d’acquisto.

Stripe indica che le richieste POST possono usare una chiave di idempotenza; per la stessa chiave il sistema conserva il risultato della prima richiesta, anche se la risposta era un errore, e usa il confronto dei parametri per evitare che la stessa chiave venga riutilizzata con dati diversi. Le chiavi possono essere rimosse dopo almeno 24 ore; oltre quella finestra, una chiave riusata può essere trattata come nuova richiesta. (Stripe)

Scenario simulato: ordine perso dopo il primo invio

Scenario didattico simulato. Un connettore ecommerce invia un ordine a un servizio esterno. La connessione si interrompe prima della risposta. Il sistema locale non sa se l’ordine sia stato creato oppure no.

Prerequisiti

  • Un identificativo univoco per l’intenzione di acquisto, generato lato client o orchestratore.
  • Un archivio interno che colleghi chiave, payload, stato e riferimento esterno.
  • Una regola per distinguere il retry della stessa operazione da una nuova operazione applicativa.
  • Un contratto dell’API destinataria che specifichi retention, confronto dei parametri e modalità di recupero dello stato.

Procedura proposta

  1. Assegna una chiave stabile all’intenzione, non alla persona. La chiave deve rappresentare quel tentativo d’ordine e non contenere dati sensibili. Stripe raccomanda chiavi ad alta entropia, per esempio UUID v4 o stringhe casuali. (Stripe)
  2. Salva il legame tra chiave e payload. Se il retry arriva con gli stessi parametri, trattalo come ripetizione della stessa operazione. Se cambiano i dati, non è più lo stesso tentativo.
  3. Classifica lo stato come noto o incerto. Un timeout non equivale automaticamente a un fallimento. La richiesta potrebbe aver creato l’ordine, anche se il client non ha ricevuto la risposta.
  4. Definisci una riconciliazione. Prima di riprovare, verifica se il fornitore espone un riferimento, uno stato consultabile o un altro meccanismo di recupero.
  5. Conserva i log minimi necessari. Registra identificativo dell’operazione, tentativi ed esito, ma non segreti o dati personali inutili.

Input concreto

order_intent_id = "ord_20260921_1842"
customer = "anonimo"
payload = {"cart_id":"C9821","amount":149.90,"currency":"EUR"}
idempotency_key = "2f6a1f0e-5e1a-4f4b-9d19-0d5d45e1b7f4"

Output esemplificativo atteso

Prima richiesta: ordine inviato, risposta non ricevuta
Secondo invio con la stessa chiave: esito già noto, nessun nuovo ordine creato
Terzo invio con chiave diversa: nuova operazione applicativa, da autorizzare solo se l’ordine precedente è stato escluso

Controlli di accettazione

  • Chi controlla: team backend. Quando: in sviluppo e pre-rilascio. Cosa verificare: stessa chiave + stesso payload = nessun doppio ordine.
  • Chi controlla: QA o platform engineer. Quando: in test di integrazione. Cosa verificare: stessa chiave + payload diverso = errore o blocco, non duplicazione silenziosa.
  • Chi controlla: team operativo. Quando: prima del go-live e dopo incidenti di rete. Cosa verificare: processo di riconciliazione per gli ordini con esito incerto.
  • Chi controlla: sicurezza applicativa o backend lead. Quando: periodicamente. Cosa verificare: nessuna chiave riusata oltre la finestra di retention senza una decisione esplicita.

Limiti da dichiarare chiaramente

L’idempotenza non sostituisce il disegno del sistema. Stripe specifica che non tutte le richieste generano subito una registrazione idempotente: per esempio, se la validazione fallisce o c’è un conflitto con un’altra esecuzione concorrente, il risultato non viene salvato nello stesso modo. Inoltre, la pagina descrive il comportamento della sua API, non di tutti i provider. (Stripe)

Per questo, in un ecommerce serio, il retry va trattato come un processo controllato: prima si decide se la richiesta è davvero la stessa, poi si verifica se l’operazione è già stata applicata, infine si autorizza il nuovo invio solo quando serve davvero.

Se stai progettando un’integrazione tra shop, ERP o OMS, il punto di partenza non è aumentare i retry, ma mappare dove si può perdere la risposta e come riconoscere un ordine già creato. È il modo più semplice per evitare duplicati, ticket inutili e riconciliazioni manuali più costose del problema iniziale.

Fonte consultata: pagina Stripe “Idempotent requests”, consultata il 2026-09-21. (Stripe)

Fonti