API · INTEGRAZIONI · AFFIDABILITÀ · 11 MIN DI LETTURA
L'integrazione affidabile non è uno script che gira su dati demo, ma un flusso di produzione che sa riconoscere, registrare e recuperare da un errore.
Prima definisci la titolarità dei dati
Dovrebbe esserci un sistema autorevole per ciascuna entità. Un sistema può essere proprietario dell'ospite, un altro della prenotazione, il terzo del documento finanziario. Se entrambe le estremità cambiano liberamente lo stesso campo, la sincronizzazione diventa una competizione in cui vince l'ultimo record senza motivo commerciale.
Definisci la direzione del flusso, gli identificatori e le regole di mappatura prima di scrivere il codice. Documenta soprattutto i valori che non esistono in entrambi i sistemi e il trattamento degli stati sconosciuti.
Ogni operazione importante dovrebbe essere idempotente
La rete potrebbe interrompere la risposta dopo che l'altra parte ha già elaborato la richiesta. Il mittente quindi non sa se l'operazione è andata a buon fine e deve riprovare. Se il nuovo invio crea una nuova prenotazione o addebito, l'integrazione non è sicura.
La chiave di idempotenza, l'identificatore esterno e il registro degli eventi elaborati consentono il riconoscimento della stessa richiesta e restituiscono un risultato esistente. Ciò è essenziale per prenotazioni, pagamenti, fatture e modifiche dell'inventario.
Il nuovo tentativo senza idempotenza non è un meccanismo di affidabilità; è la possibilità di duplicare un evento aziendale.
Non tutto deve essere sincrono
L’utente non deve aspettare che cinque servizi esterni confermino un dato interno. Spesso è meglio salvare la transazione principale, pubblicare un evento ed elaborare i passaggi collegati in background. La coda di messaggi conserva il lavoro da elaborare mentre il sistema esterno non è disponibile.
Usa una chiamata sincrona quando la risposta è necessaria per la decisione successiva dell’utente, ad esempio la conferma finale della disponibilità. Per notifiche, sincronizzazione CRM o analisi, un flusso asincrono riduce l’accoppiamento tra i sistemi.
I tentativi dovrebbero avere dei limiti
In caso di errori temporanei, i tentativi vanno ripetuti con intervalli progressivamente più lunghi. Un errore di validazione, un’unità sconosciuta o un’autorizzazione negata non si risolvono con dieci tentativi identici. L’integrazione deve distinguere gli errori transitori da quelli permanenti.
Dopo un certo numero di tentativi, il messaggio passa a una coda di elaborazione degli errori controllata. Dovrebbe esserci un contesto sufficiente affinché la persona possa comprendere il problema e riavviare l'elaborazione dopo la correzione.
Il registro non è sufficiente senza il contesto aziendale
Un messaggio tecnico come «HTTP 400» raramente aiuta il team operativo. Occorre collegare l’errore alla prenotazione, alla struttura, al canale e al passaggio specifico. La dashboard deve mostrare messaggi riusciti e non riusciti, ritardi della coda e cause ricorrenti.
Un identificatore di correlazione condiviso tra i servizi riduce i tempi di diagnosi. I log non devono contenere dati sensibili o credenziali.
Il contratto API sta cambiando
Il sistema esterno può aggiungere stato, modificare il limite o eliminare la versione dell'endpoint. L'integrazione dovrebbe tollerare campi aggiuntivi sconosciuti, ma reagire chiaramente quando mancano dati obbligatori. I test contrattuali e un ambiente di test aiutano a rilevare le modifiche prima della produzione.
Le versioni, le scadenze e il proprietario dell'integrazione devono essere documentati. "Una volta connesso" non significa completato in modo permanente; L'integrazione API è la relazione tra due prodotti che si sviluppano a ritmi diversi.
Lista di controllo essenziale prima del rilascio in produzione
Prima del rilascio, verifica autenticazione e rotazione dei segreti, timeout, regole per i nuovi tentativi, idempotenza, limiti alle richieste, mappatura degli identificatori, audit, allarmi e ripristino manuale. Testa duplicati, messaggi fuori sequenza e servizi esterni non disponibili, oltre al flusso ideale.
L'integrazione ha esito positivo quando il team non riscrive più i dati e le eccezioni sono meno frequenti e più visibili. Se il lavoro quotidiano richiede una nuova tabella “per tenere traccia di ciò che non è stato trasferito”, il sistema non è ancora completo.