Sostituire un gestionale in un colpo solo è raro. Per mesi (o anni) conviveno un database “vecchio” — spesso SQL Server, Access cresciuto, o un AS/400 con viste — e un ERP o un CRM nuovo. Se la sincronizzazione è un CSV notturno “e poi si vede”, avete due verità e nessuno sa quale è quella di ieri.
Il problema non è “fare un’API”. È chi è master su quale entità, cosa succede quando una riga fallisce, e come riparti senza duplicare.
Prima il contratto di dato, poi il cavo
Elencate oggetti: clienti, articoli, ordini, pagamenti. Per ciascuno: sistema master, campi obbligatori, frequenza (evento vs batch), cosa fate in conflitto (timestamp, priorità, review umana).
Senza questa tabella ogni middleware diventa un cimitero di if.
Pattern, dal più semplice al più robusto
Batch idempotente. Job notturno o orario: legge un watermark (updated_at o un outbox), upsert sul target con chiave stabile (P. IVA, SKU, id legacy mappato). Se gira due volte, il risultato è lo stesso. Va bene per anagrafiche che non devono essere real-time.
Outbox + coda. Il legacy (o un trigger/CDC) scrive eventi in una tabella outbox; un worker pubblica su coda; il consumer aggiorna l’ERP. Serve se l’ordine deve comparire in pochi minuti e volete retry senza perdere messaggi.
API sincrone solo sul bordo. L’operatore crea l’ordine nel nuovo portale; il servizio chiama l’ERP e, se fallisce, non finge il successo. Non usate HTTP sincrono per scaricare 40.000 articoli: timeout e doppi insert.
CDC (change data capture). Se il vendor lo consente (log SQL, Debezium, tool del gestionale). Costa in ops. Utile quando non potete toccare il codice del legacy.
Anti-corruption layer. Un servizio vostro parla il linguaggio del nuovo ERP (aggregati, id UUID) e traduce il modello del vecchio (tabelle denormalizzate, codici a 6 caratteri). L’ERP non deve “capire” Access.
Chiavi e identità
Il peccato originale è usare il nome del cliente come chiave. Servono: id nel legacy, id nel nuovo, e una tabella di mapping persistente. P. IVA e SKU aiutano ma non sono uniche al 100% (filiali, articoli duplicati). Deduplica è un progetto, non una riga di SQL.
Errori che vedete il lunedì mattina
- Job che “cancella e reimporta”: un id cambia, lo storico si spezza.
- Nessun dead-letter: l’ordine 4817 fallisce in silenzio per un campo IVA.
- Fusi orari e datetime naive.
- Sync bidirezionale senza master: due operatori modificano lo stesso cliente, vince l’ultimo job.
- File Excel come “integrazione ufficiale”: non c’è versione, non c’è audit.
Una sequenza realistica
- Read-only: il nuovo sistema legge il legacy, non scrive.
- Anagrafiche in batch idempotente.
- Documenti (ordini) in outbox, un verso.
- Spegnere il vecchio pezzo per pezzo quando i report coincidono per N giorni.
DPH collega CRM, gestionali e software esistenti con API, non con export manuali. Per un disegno sul vostro caso, prenotate una sessione tecnica: motori DB, volumi, chi è master, quanto può essere “ieri sera” vs “subito”.