Integrare gestionale, e-commerce e fatturazione con le API: architettura che regge nel tempo

Collegare un e-commerce a un gestionale è facile da mostrare in una demo: arriva un ordine, compare dall'altra parte. Il lavoro vero comincia quando l'API del gestionale risponde in trenta secondi, il webhook arriva due volte, un prodotto viene rinominato, la fatturazione elettronica scarta un documento e nessuno se ne accorge per una settimana. Un'integrazione affidabile è progettata per questi casi, non per quello felice.

La prima decisione: chi è la fonte di verità

Per ogni dato serve un solo sistema autorevole. Le giacenze nascono nel gestionale o nell'e-commerce? I prezzi? L'anagrafica clienti? Le sincronizzazioni bidirezionali sullo stesso campo sono la fonte principale di conflitti: due sistemi che si correggono a vicenda finché uno dei due vince a caso. La regola che seguo: ogni campo ha un proprietario, e gli altri sistemi lo leggono.

Eventi, non sondaggi

Interrogare un'API ogni cinque minuti per vedere se è cambiato qualcosa (polling) è semplice ma lento, costoso e fragile con i limiti di frequenza. Dove i sistemi lo permettono, uso gli eventi: il servizio di pagamento, l'e-commerce o il gestionale inviano un webhook quando succede qualcosa.

I webhook vanno trattati con cura:

• verifica della firma, per accettare solo chiamate autentiche;
• risposta immediata e lavoro spostato in una coda, perché chi invia ha tempi di attesa brevi e riprova se non riceve risposta;
• deduplicazione, perché lo stesso evento può arrivare più volte;
• ordine non garantito: un aggiornamento può arrivare prima della creazione, e il codice deve saperlo gestire.

Code, tentativi e idempotenza

Tra i sistemi metto una coda. Ogni messaggio viene elaborato, e se il sistema di destinazione non risponde viene riprovato con attese crescenti. Dopo un numero di tentativi finisce in una coda di errori, visibile e recuperabile, con un avviso a una persona.

Ogni operazione di scrittura è idempotente: ha un identificativo univoco, e rieseguirla non crea un secondo ordine, una seconda fattura o un secondo movimento di magazzino. È la proprietà che permette di riprovare senza paura.

I collegamenti più comuni

• E-commerce e gestionale: ordini verso il gestionale, giacenze e prezzi verso il negozio. Attenzione a varianti, kit e prodotti composti, dove i modelli dei due sistemi raramente coincidono.
• Fatturazione elettronica: generazione del documento corretto (fattura, corrispettivo, nota di credito) e gestione delle ricevute e degli scarti del Sistema di Interscambio, che vanno riportati nel sistema di origine.
• Pagamenti: lo stato dell'ordine si aggiorna dal webhook del provider, non dal ritorno del browser alla pagina di conferma, che può non avvenire mai.
• Corrieri: creazione delle spedizioni, etichette, codici di tracciamento e stati di consegna.
• CRM e newsletter: con attenzione ai consensi, che seguono regole proprie.

Mappatura e trasformazioni

Ogni sistema ha il suo modello: codici IVA, unità di misura, varianti, indirizzi, stati dell'ordine. La mappatura tra i due va scritta, documentata e testata con casi reali, compresi quelli scomodi: prodotti cancellati, clienti senza partita IVA, indirizzi esteri, resi parziali.

Riconciliazione e monitoraggio

Anche l'integrazione migliore prima o poi perde un messaggio. Per questo aggiungo sempre una riconciliazione periodica: un processo che confronta ordini, giacenze e documenti tra i sistemi e segnala le differenze. E un pannello o un rapporto con l'esito delle sincronizzazioni, perché il primo a scoprire un problema non sia un cliente.

Sicurezza

Credenziali dedicate per ogni integrazione, con permessi minimi, conservate fuori dal codice e ruotabili. Comunicazione cifrata, webhook firmati, registri senza dati personali in chiaro dove non servono.

Un esempio: il percorso di un ordine

1. Il cliente paga. Il provider di pagamento invia un webhook firmato: il sistema lo verifica, lo registra con il suo identificativo e risponde subito.
2. Un processo in coda crea l'ordine nel gestionale con una chiave di idempotenza: se il messaggio arriva due volte, l'ordine resta uno.
3. Il gestionale scala le giacenze e restituisce il proprio numero d'ordine, che viene salvato accanto a quello dell'e-commerce.
4. Si genera il documento fiscale corretto; l'esito dell'invio al Sistema di Interscambio torna nel sistema di origine, con un avviso in caso di scarto.
5. Si crea la spedizione presso il corriere, con etichetta e codice di tracciamento.
6. Gli stati di consegna aggiornano l'ordine e attivano le comunicazioni al cliente.
7. Ogni notte la riconciliazione confronta ordini, documenti e movimenti di magazzino e segnala le differenze.

Ogni passaggio può fallire, e ognuno ha un tentativo automatico, una coda di errori e un responsabile.

Come la vedo io

Considero le integrazioni software a tutti gli effetti, non configurazioni. Per questo le scrivo come servizi versionati in un repository, con test sui casi limite e un deploy controllato, invece di affidarle a catene di connettori che nessuno sa più ricostruire. Nel gestionale di Altura Vela, per esempio, i pagamenti con Stripe sono gestiti dal webhook del provider, non dal ritorno del browser: è un dettaglio, ma è il dettaglio che evita le prenotazioni pagate e mai registrate.

La mia regola pratica: un'integrazione è finita quando sai rispondere in cinque minuti alla domanda «che fine ha fatto l'ordine 1234?».

Infine, documento sempre le integrazioni: flussi, mappature e procedure di recupero, perché chi arriva dopo non debba ricostruirle dal codice.

Perché affidarlo a me

Programmo dal 1999, ho consegnato più di 300 progetti e lavoro come sviluppatore esterno con circa 30 agenzie, da Roma e da remoto. Progetto integrazioni tra e-commerce, gestionali, fatturazione, pagamenti e corrieri con code, idempotenza e riconciliazione.

Se i tuoi sistemi non si parlano, o si parlano male, scrivimi: in una chiacchierata di circa 20 minuti disegniamo i flussi e capiamo dove si rompono. Il servizio è in Integrazioni API.