Le quattro strade, in ordine di robustezza
1. API (il sistema espone funzioni documentate)
È la strada migliore quando c'è. Il sistema di destinazione dichiara cosa accetta, risponde con un esito esplicito e di solito impone limiti chiari (autenticazione, numero massimo di chiamate). Il vantaggio non è la velocità: è che gli errori sono dichiarati. Sapete se un ordine è stato accettato o rifiutato, e perché.
2. Webhook (il sistema vi avvisa quando succede qualcosa)
Ottimo per la tempestività: l'e-commerce vi chiama appena arriva un ordine, invece di farvi controllare ogni cinque minuti. Attenzione a tre dettagli che quasi sempre vengono trascurati: il messaggio può arrivare due volte, può arrivare fuori ordine, e se il vostro sistema è spento in quel momento può non arrivare più. Un webhook senza un recupero periodico è una promessa a metà.
3. File programmati (CSV, XML, tracciati)
Il metodo più vecchio e ancora il più usato con i gestionali storici e con la grande distribuzione. Funziona, se si rispettano le regole: nome file con data e progressivo, file scritto in una cartella temporanea e poi rinominato (altrimenti si legge un file a metà), archiviazione dei file elaborati, e una regola esplicita su cosa fare con un file uguale a uno già visto. La latenza è quella del programma orario: se il file esce alle 6 del mattino, i dati sono di ieri sera.
4. RPA, cioè un robot che usa l'interfaccia al posto vostro
Ultima scelta, ma a volte l'unica: quando il software non ha né API né esportazioni e il fornitore non ha intenzione di aggiungerle. Va detto chiaramente: l'RPA è fragile per costruzione. Dipende dalla posizione dei campi sullo schermo: un aggiornamento del gestionale può romperla di notte senza avvisare. Se la si usa, va usata con un controllo a valle che verifichi il risultato — mai «a fiducia».
| Strada | Quando conviene | Rischio principale |
|---|---|---|
| API | Il sistema le espone e sono documentate | Limiti di chiamate, versioni che cambiano |
| Webhook | Serve reagire subito a un evento | Duplicati, messaggi persi se si è offline |
| File | Gestionali storici, grandi volumi, orari fissi | File letti a metà, doppie elaborazioni |
| RPA | Nessun'altra strada disponibile | Si rompe a ogni aggiornamento dell'interfaccia |
Le tre garanzie che contano più della tecnica
Idempotenza: la stessa cosa due volte non fa danno
Ogni messaggio deve portare una chiave stabile — il numero d'ordine, il numero documento, un identificativo del mittente — e il sistema ricevente deve rifiutare educatamente ciò che ha già elaborato. Senza questa regola, il primo problema di rete produce ordini doppi, e i doppioni si scoprono in magazzino o in fattura, cioè tardi.
Ritentativi con attesa crescente
Le reti cadono e i server si riavviano. Un'integrazione seria riprova dopo pochi secondi, poi dopo un minuto, poi dopo dieci, e dopo un numero massimo di tentativi mette il messaggio in un'area di scarto visibile. La parte importante è l'ultima: gli scarti invisibili sono il modo più comune di perdere ordini senza accorgersene.
Riconciliazione periodica
Ogni notte, o ogni ora, si contano le due parti: quanti ordini ci sono di là, quanti di qua, quali mancano. È il controllo che salva la giornata, perché non si fida del meccanismo ma del risultato. Nella nostra esperienza è anche la funzione che i clienti imparano ad amare di più, perché è l'unica che risponde alla domanda «siamo allineati?» senza aprire due schermi.
Un flusso concreto: dall'e-commerce al gestionale
- Arriva il webhook «nuovo ordine». Il messaggio viene salvato così com'è, prima di ogni elaborazione: se qualcosa va storto, l'originale resta.
- Si verifica la chiave: ordine già visto? Allora si risponde «ok» e non si fa nulla.
- Si controllano i dati minimi: codici articolo esistenti, quantità positive, partita IVA nel formato corretto per le fatture aziendali, indirizzo compilato.
- Si scrive nel gestionale, ricevendo un identificativo di ritorno che viene registrato accanto all'ordine originale. Da quel momento esiste una tracciabilità in entrambi i sensi.
- Ciò che non passa i controlli finisce in una lista di scarti con il motivo scritto in italiano, non un codice. Qualcuno la guarda ogni mattina: fa parte del processo, non è un'eccezione.
- Ogni notte un confronto conta gli ordini delle ultime 48 ore da entrambe le parti e segnala le differenze.
Cosa vuol dire davvero «monitorato»
Un'integrazione monitorata non è una che ha i log. È una che vi avvisa prima che sia il cliente a farlo. Tre allarmi bastano quasi sempre:
- Silenzio anomalo: nessun messaggio ricevuto da più tempo del normale per quella fascia oraria. È l'allarme più prezioso, perché l'assenza di errori non è mai una buona notizia di per sé.
- Scarti sopra soglia: più del 2% dei messaggi in errore in un'ora.
- Riconciliazione fallita: i conteggi delle due parti non coincidono.
I costi nascosti da mettere a preventivo
- I cambi di versione delle API dei fornitori, che arrivano con preavviso e vanno seguiti.
- I limiti di chiamata: molti servizi impongono un tetto, e superarlo significa riprogettare i tempi.
- Le credenziali: vanno custodite fuori dal codice, ruotate quando cambia il personale, e devono avere i permessi minimi necessari.
- Lo storico: quasi sempre il primo caricamento dei dati passati costa più dell'integrazione corrente, perché lo storico è più sporco.
Nessuna di queste voci è imprevedibile: sono note da anni. Se non compaiono nel preventivo, compariranno nel consuntivo.