Progettare integrazioni con API SMM che sopravvivono ai guasti

La prima versione di ogni integrazione API presume il percorso felice: invii una richiesta, ottieni una risposta, l'ordine è piazzato. La produzione ti insegna il contrario. Le reti cadono, gli endpoint vanno in timeout, e il guasto più pericoloso è quello ambiguo, la richiesta che potrebbe essere andata a buon fine o no prima che la connessione morisse. Progettare per quell'ambiguità è tutto il lavoro.

L'idempotenza è la difesa centrale. Allega una chiave univoca a ogni richiesta d'ordine e fai in modo che il server tratti una ripetizione di quella chiave come la stessa operazione, non come una nuova. Ora un retry dopo un timeout è sicuro: se l'originale era andato a buon fine, ottieni di ritorno l'ordine esistente invece di un addebito duplicato. Senza questo, ogni retry è una scommessa con il tuo saldo.

Stratifica i retry con il backoff. Gli errori transitori (un rate limit 429, un 503, un reset di rete) andrebbero ripetuti con ritardi crescenti e un tetto massimo, non martellati all'istante. Gli errori permanenti (un 400 bad request, una risposta di saldo insufficiente) dovrebbero fallire rapidamente ed emergere a un essere umano, perché riprovarli spreca solo tempo e nasconde il vero problema.

Infine, riconcilia. Registra ogni richiesta e risposta con la sua chiave di idempotenza e l'ID ordine, ed esegui un processo periodico che confronti i tuoi registri con gli stati degli ordini del pannello. La riconciliazione è ciò che intercetta l'ordine andato a buon fine sul pannello ma non registrato dalla tua parte. L'API di SocialGO restituisce ID e stati degli ordini coerenti proprio perché questo ciclo sia semplice da costruire, la differenza tra un'automazione di cui ti fidi e una che devi sorvegliare.