I tuoi gestionali italiani non parlano tra loro. Ecco come farli comunicare senza perdere dati.

L'errore che vedi spesso è il connettore sviluppato in una settimana, messo in produzione e poi dimenticato. Poi arriva il primo timeout, il primo errore di rete, e il connettore crasha silenziosamente. La differenza tra un prototipo e un connettore enterprise sta nella gestione degli errori: devi implementare una retry logic esponenziale con jitter (ovvero, aggiungi un po' di casualità ai tempi di retry per non sommergere il server di richieste simultanee). La logica base è: primo tentativo subito, secondo dopo 2 secondi, terzo dopo 4, quarto dopo 8, fino a un massimo che decidi tu (per esempio 60 secondi). Se il timeout è transitorio—cioè il server era sovraccarico ma adesso è ok—il retry lo risolve; se l'errore è permanente (autenticazione scaduta, dato non trovato), il retry non serve e devi catturarlo diversamente. Usa un error handler stratificato: transient errors (timeout, 5xx server, connection reset) meritano retry; permanent errors (401 unauthorized, 404 not found, 400 bad request) vanno loggati e fermati subito, altrimenti brutti tutti i retry. Per evitare operazioni duplicate (magari il messaggio di successo si è perso in rete e il client ritenta), aggiungi una idempotency key: un identificativo univoco che il server controlla prima di applicare l'operazione. Se arriva due volte la stessa idempotency key, la seconda volta il server risponde "già fatto" senza duplicare niente.

Il logging strutturato è il tuo amico in produzione. Non scrivere log testo libero tipo "Errore di integrazione"; scrivi log JSON con correlation ID, timestamp ISO 8601, severity level (INFO, WARN, ERROR), messaggio, stack trace e contesto (quale record stavi elaborando, quale sistema sorgente, quale sistema destinazione). Ogni richiesta che attraversa il tuo connettore deve portarsi dietro un correlation ID: è una stringa UUID che traccia la richiesta dalla API esterna, attraverso il tuo connettore, fino al gestionale. Se qualcosa va male, il customer support apre la dashboard di monitoraggio, cerca il correlation ID, e ricostruisce esattamente cosa è successo. Monitora due metriche critiche: failure rate (quante integrazioni falliscono percentualmente ogni ora) e latency (quanto tempo ci mette una integrazione a completare). Se il failure rate supera il 5%, scatta un alert a Slack. Se la latency media supera 30 secondi, scatta un warning. Con questi dati, scopri se il problema è il tuo codice (regression), il server del gestionale (overload), o la rete (firewall che sta bloccando).

Le incompatibilità nei modelli dati sono il vero grattacapo. Un esempio concreto: importi da un e-commerce che ha due decimali per l'importo (1234,56), il gestionale Zucchetti ne richiede quattro per il calcolo delle ritenute (1234,5600). Oppure: il cliente nel CRM ha codice cliente "ACME-001", il gestionale lo vuole con una codifica diversa "AC0001". I codici IVA italiani sono l'incubo: il CRM esterno magari memorizza "IVA 22%", il gestionale vuole il codice esatto Natura reverse charge come definito dall'Agenzia delle Entrate. Le valute e i formati data sono un classico: se il sorgente è un sistema americano, la data è MM/DD/YYYY e la valuta è USD, ma il gestionale italiano la vuole DD/MM/YYYY e EUR. Devi creare una mapping layer che traduce ogni campo, valida i dati in ingresso (se manca un campo obbligatorio, non puoi procedere), e normalizza tutto in un formato intermedio. Usa un file di configurazione esterno (YAML o JSON) per i mapping: così il cliente può adattare il connettore senza toccare il codice. Prima del go-live, fai un test end-to-end con dati reali sanitizzati: chiedi al cliente un dump anonimizzato della sua base clienti o dei suoi documenti, incrocialo con il gestionale, verifica che ogni record arrivi correttamente, che i calcoli siano giusti, che i rapporti uno-a-molti (una fattura, più righe) siano mantenuti. Questo test ti risparmia crisi di produzione.

Italy Soft ha sviluppato connettori per le principali combinazioni di gestionali italiani—Zucchetti con Salesforce, TeamSystem con SAP SuccessFactors, AS400 con piattaforme cloud moderne—consolidando pattern di integrazione che funzionano in ambienti con migliaia di documenti al giorno. La lezione è semplice: un connettore strutturato non è più complicato di uno fragile, è solo che richiede attenzione ai dettagli e una visione architecturale dall'inizio. Investire oggi in error handling, monitoring e testing sanitizzato ti risparmia mesi di debugging in produzione domani.