01 / Caso studio 01
Distribuzione B2B — 34 persone, 6 agenti in visita
Integrazione gestionale e CRM per un distributore di ricambi
Due sistemi che descrivevano gli stessi clienti in modo diverso, e sei agenti che scoprivano la giacenza vera solo telefonando in sede. Ho messo un middleware in mezzo e ho deciso, riga per riga, chi ha ragione quando i due non concordano.
Stack dell'intervento
- Node.js
- TypeScript
- PostgreSQL
- Redis
- SQL Server
- REST
- Docker
- VPN IPsec
Nessuna riga scritta dentro il database del gestionale: si legge da viste dedicate e si scrive nelle tabelle di appoggio previste dal fornitore. È il vincolo che ha disegnato tutto il resto.
- Settore
- Ricambi industriali, vendita B2B con rete agenti
- Sistemi coinvolti
- Gestionale on-premise, CRM cloud, e-mail
- Durata
- 9 settimane, di cui 2 di sola misurazione
- Intervento
- Middleware di sincronizzazione bidirezionale
Che cosa stai leggendo
02 / Contesto
Da dove si parte
Trentaquattro persone, due verità sullo stesso cliente
Un distributore di ricambi per l'industria: magazzino proprio, sei agenti sul territorio, un ufficio commerciale di quattro persone che tiene insieme tutto a mano. Il gestionale c'è da undici anni e funziona; il CRM è arrivato tre anni fa per dare agli agenti qualcosa di usabile in visita.
Il gestionale è il sistema che fattura
Anagrafiche, listini, giacenze, ordini e fatture stanno lì da undici anni. È on-premise, il fornitore lo mantiene con un contratto annuale e non concede accesso in scrittura alle tabelle native. Qualunque architettura che pretenda di scriverci dentro è morta prima di iniziare.
Il CRM è il sistema che gli agenti usano davvero
È in cloud, va sul telefono, ha le note delle visite e lo storico delle trattative. Nessuno degli agenti aprirebbe mai il gestionale: è pensato per chi sta a una scrivania con due schermi, non per chi è in piedi in un reparto con il casco in mano.
In mezzo c'era una persona
Un'addetta del commerciale esportava ogni lunedì mattina anagrafiche e listini dal gestionale, li ripuliva in Excel e li importava nel CRM. Gli ordini facevano il percorso inverso, uno per uno, copiati a mano. Quel lavoro non era in nessun mansionario e non compariva in nessun costo.
Il vincolo vero era il contratto di manutenzione
Toccare il database del gestionale in modo non previsto avrebbe fatto decadere l'assistenza. Non è un dettaglio tecnico: è il perimetro dentro cui il progetto poteva esistere, e va accertato nella prima riunione, non alla terza settimana.
Dimensione
- Dipendenti
- 34, di cui 6 agenti sul territorio
- Clienti attivi
- circa 1.400
- Referenze a magazzino
- circa 9.000
- Ordini medi
- 70–90 al giorno
Sistemi in campo
- Gestionale
- on-premise, database SQL Server
- CRM
- cloud, API REST documentate
- Listini
- personalizzati per cliente e per famiglia
- Connettività
- linea FTTC in sede, senza IP statico
03 / Punto di partenza
Misurato prima, non ricordato dopo
Prima di proporre qualcosa ho contato quanto costava non fare niente
Due settimane di sola misurazione, prima di scrivere una riga. Non è una fase di cortesia: è quella che rende il risultato finale dimostrabile invece che raccontato, e in più capita spesso che la cosa più cara non sia quella di cui il cliente si lamenta.
Undici ore alla settimana di ribattitura
Contate con un foglio ore tenuto per dieci giorni dalle due persone che facevano il lavoro: export, pulizia in Excel, import, correzione degli scarti, reinserimento degli ordini. Il lunedì mattina se ne andava quasi tutto in questo.
Trecentododici clienti esistevano due volte
Su 1.847 anagrafiche nel CRM, 312 erano duplicati della stessa azienda con codice diverso — nate da chi creava il cliente in visita senza cercarlo prima. Ogni duplicato porta con sé uno storico spezzato e un listino potenzialmente sbagliato.
Il 6% degli ordini partiva con un prezzo che non esisteva
Gli agenti lavoravano su un listino esportato in media otto giorni prima. In un mercato dove il rame e l'acciaio si muovono, otto giorni bastano: il prezzo veniva corretto in sede, e la correzione era una telefonata al cliente che aveva già firmato.
L'offerta ci metteva due giorni per uscire
Non perché scriverla richieda due giorni, ma perché l'agente chiedeva conferma di giacenza e prezzo alla sede, e la sede rispondeva quando poteva. Nel frattempo il cliente chiamava anche il concorrente.
Le grandezze rilevate nelle prime due settimane
Ognuna con la fonte da cui è stata presa, così a fine progetto lo stesso conto si può rifare identico.
| Grandezza | Valore rilevato | Come è stata misurata |
|---|---|---|
| Ore di ribattitura | 11 h/settimana | Foglio ore compilato per 10 giorni lavorativi dalle 2 persone coinvolte |
| Anagrafiche duplicate | 312 su 1.847 | Confronto su partita IVA normalizzata più somiglianza sulla ragione sociale |
| Ordini con prezzo corretto a posteriori | 6,1% | Estrazione ordini di 3 mesi dal gestionale, righe con prezzo diverso dall'offerta |
| Tempo medio di emissione offerta | 2,1 giorni | Differenza fra data della visita nel CRM e data del documento nel gestionale |
| Età media del listino in mano agli agenti | 8,3 giorni | Data dell'ultimo export inviato per e-mail, su 3 mesi di storico |
Nessuna di queste cifre è stata chiesta a memoria a qualcuno. Quando si chiede a memoria, la risposta è sempre la stessa: «tantissimo tempo» — che non è un numero e non si può migliorare.
04 / Diagnosi
Che problema è davvero
Non era un problema di sincronizzazione. Era un problema di autorità
Due sistemi che si scambiano dati senza che sia scritto chi comanda su ogni campo non sono integrati: sono due sistemi che si sovrascrivono a turno.
La richiesta iniziale era «fai in modo che i due parlino». Ma nel momento in cui parlano davvero, la domanda diventa un'altra e diventa subito urgente: se l'agente cambia l'indirizzo di consegna nel CRM e l'amministrazione lo cambia nel gestionale, chi vince? Se non è deciso prima, vince l'ultimo che ha salvato — cioè il caso. Il grosso del lavoro delle prime settimane è stato compilare una tabella noiosissima: per ogni entità e per ogni campo, chi è la fonte di verità, chi può proporre una modifica e cosa succede quando i due non concordano. Quella tabella è il progetto; il codice che ne è seguito è la parte facile.
Come sono arrivato alla diagnosi
- Due giornate in sede seduto accanto a chi faceva il lavoro a mano, senza proporre niente: quello che le persone raccontano di fare e quello che fanno differiscono sempre, e la differenza è dove sta il problema.
- Estrazione completa delle anagrafiche dai due sistemi e confronto campo per campo su partita IVA normalizzata, per contare le divergenze invece di stimarle.
- Lettura del contratto di manutenzione del gestionale, per sapere cosa si può toccare prima di disegnare qualcosa che non si potrà fare.
- Colloquio con due agenti sul territorio: quali informazioni cercano in visita, in che ordine, e cosa fanno quando non le trovano.
- Prova pratica delle API del CRM e delle viste del gestionale su un ambiente di collaudo, per verificare limiti di chiamate, formati di data e comportamento sugli errori prima di prometterli.
Cosa è saltato fuori
- Il campo su cui i due sistemi divergevano di più non era il prezzo ma il codice di pagamento: nel CRM era testo libero, nel gestionale un codice a tabella. Nessuno lo sapeva.
- Il 70% dei duplicati veniva da tre agenti su sei: non è un problema di sistema, è un problema di come si crea un cliente in visita — e si risolve con una ricerca prima del pulsante «nuovo», non con un import migliore.
- Le giacenze servivano agli agenti aggiornate al quarto d'ora, non al secondo. È una differenza che cambia l'architettura: consente un polling e rende inutile una coda di eventi in tempo reale con tutto il suo costo di esercizio.
- Il gestionale esponeva già delle viste di sola lettura predisposte dal fornitore, mai usate da nessuno. Metà del lavoro di lettura era già stato fatto e nessuno in azienda lo sapeva.
05 / Architettura
Cosa ho costruito
Un middleware in mezzo, e nessuno dei due sistemi che sa dell'altro
Il gestionale è la fonte di verità su anagrafiche, listini e giacenze. Il CRM propone; il gestionale conferma. Il middleware è l'unico posto dove questa regola è scritta.
Nessun collegamento diretto fra i due sistemi: si sarebbero legati a vicenda per sempre, e cambiare CRM fra tre anni sarebbe costato quanto rifare tutto. In mezzo c'è un servizio che ha un database proprio, dove tiene la mappatura fra le chiavi dei due mondi, lo stato di ogni sincronizzazione e la coda dei lavori. Legge dal gestionale attraverso viste di sola lettura, scrive solo nelle tabelle di appoggio che il fornitore prevede per l'import, e parla con il CRM via API. Se domani il CRM cambia, si riscrive un adattatore e il resto resta in piedi.
Flusso dei dati
Chiave di riconciliazione, non chiave interna
I due sistemi hanno identificatori propri che non si possono cambiare. Il middleware tiene una tabella di corrispondenza fra i due, costruita sulla partita IVA normalizzata più il codice fiscale come riserva. Nessuno dei due sistemi ha dovuto adottare gli ID dell'altro: è la ragione per cui il collegamento si può smontare.
Ogni operazione è ripetibile senza danni
Ogni messaggio porta una chiave derivata dal contenuto: se lo stesso ordine arriva due volte — succede, dopo un timeout o un ritentativo — il secondo passaggio non crea niente. È la proprietà che permette di rimandare tutto in caso di dubbio invece di ricostruire a mano cosa era passato e cosa no.
Le giacenze passano ogni quindici minuti, i listini di notte
Frequenze diverse per dati con vita diversa. Le giacenze cambiano di continuo e servono fresche; i listini cambiano di rado e pesano. Un solo ritmo per tutto avrebbe significato o dati vecchi o un carico inutile sul gestionale in orario di lavoro.
Gli ordini dal CRM entrano come proposte
Non diventano ordini finché il gestionale non li ha validati su fido, giacenza e listino corrente. L'agente vede lo stato cambiare in pochi minuti. È una scelta commerciale prima che tecnica: nessuno vuole un ordine automatico a un cliente che ha lo scaduto aperto.
Un registro che si legge senza essere programmatori
Ogni sincronizzazione lascia una riga: cosa, quando, esito, e in caso di errore il messaggio originale. L'ufficio commerciale ha una pagina dove vede gli scarti del giorno e li rimanda con un pulsante. Senza questo, ogni anomalia sarebbe una mia telefonata.
Il collegamento con la sede è una VPN, non una porta aperta
Tunnel IPsec fra il server in sede e il servizio, nessun servizio del gestionale esposto su internet, indirizzi consentiti dichiarati uno per uno. Il gestionale non ha autenticazione moderna: la sua difesa è non essere raggiungibile.
06 / Decisioni
Ogni scelta con la sua alternativa scartata
Le cinque scelte che hanno determinato tutto il resto
Una decisione senza alternativa scartata non è una decisione: è un'abitudine. Qui ci sono entrambe le colonne, compreso il prezzo che ognuna ha comportato.
Scelte tecniche e loro costo
| Decisione | Alternativa scartata | Perché così |
|---|---|---|
| Middleware autonomo in mezzo | Collegamento diretto CRM ↔ gestionale con connettore del CRM | Il connettore avrebbe legato i due sistemi per sempre e non gestiva le regole di autorità. Costo della scelta: un servizio in più da mantenere e monitorare. |
| Lettura da viste, scrittura in tabelle di appoggio | Scrittura diretta nelle tabelle del gestionale | La scrittura diretta faceva decadere il contratto di manutenzione. Costo: la conferma di un ordine non è istantanea ma passa dalla procedura del fornitore, con un ritardo di qualche minuto. |
| Polling programmato a frequenze diverse | Eventi in tempo reale con coda di messaggi | Le giacenze servono aggiornate al quarto d'ora: il tempo reale avrebbe raddoppiato il costo di esercizio per un beneficio che nessuno avrebbe percepito. Costo: fino a 15 minuti di ritardo, dichiarati in pagina agli agenti. |
| Gestionale come fonte di verità su tutto tranne le note di visita | Fonte di verità per campo, decisa caso per caso | Una regola sola si spiega in una riunione e si ricorda dopo due anni. Costo: l'agente non può correggere un dato anagrafico da solo, deve proporlo. |
| Blocco della creazione cliente senza ricerca preventiva | Deduplicazione automatica a posteriori | La deduplicazione automatica sbaglia sulle sedi secondarie e fonde clienti che vanno tenuti distinti. Costo: due tocchi in più all'agente quando apre un cliente nuovo. |
07 / Come è andata
Nove settimane, quattro fasi
Le fasi, con quello che è stato consegnato a ognuna
Ogni fase finisce con qualcosa che il cliente ha in mano e che vale anche se il progetto si ferma lì. È la regola che rende reversibile un investimento: se dopo la prima fase decidi di non proseguire, quello che hai pagato resta tuo e utilizzabile.
- 01
Misura e perimetro
Foglio ore sul lavoro manuale, estrazione e confronto delle anagrafiche, lettura del contratto di manutenzione, prova pratica di API e viste su ambiente di collaudo.
- Cosa ricevi
- Documento con le grandezze di partenza, la mappa dei campi e chi comanda su ognuno, e l'elenco di cosa non si può toccare
- Durata
- 2 settimane
- 02
Anagrafiche e listini
Middleware, mappatura delle chiavi, prima sincronizzazione in sola lettura verso il CRM. Bonifica dei 312 duplicati fatta una volta, a mano assistita, con l'ufficio commerciale a decidere i casi dubbi.
- Cosa ricevi
- Anagrafiche e listini allineati ogni notte, elenco dei duplicati risolti e regola di creazione nuovo cliente attiva
- Durata
- 3 settimane
- 03
Giacenze e ordini
Sincronizzazione delle giacenze a quindici minuti e percorso di ritorno degli ordini dal CRM alle tabelle di appoggio, con stato visibile all'agente. Collaudo su tre agenti prima di aprire a tutti.
- Cosa ricevi
- Ordini inviati dal CRM e confermati dal gestionale, disponibilità visibile in visita
- Durata
- 3 settimane
- 04
Consegna e autonomia
Pagina degli scarti per l'ufficio commerciale, avvisi automatici sui blocchi, documentazione operativa e mezza giornata di formazione. Nuova misurazione delle stesse grandezze della fase 01.
- Cosa ricevi
- Manuale operativo, accessi, monitoraggio attivo e confronto prima/dopo sulle stesse fonti
- Durata
- 1 settimana
Le tre settimane della fase 02 sono state la parte più lunga e la meno tecnica: decidere cosa fare dei 312 duplicati significa decidere quale storico commerciale sopravvive, e non è una scelta che può fare chi scrive il codice.
08 / Attriti
Quello che è andato storto
Tre cose che non erano nel piano
Le metto perché sono la parte che distingue un progetto raccontato da uno fatto. In tutti i lavori che ho consegnato, il tempo perso non è mai stato dove me lo aspettavo.
Il fornitore del gestionale non rispondeva
Servivano due viste aggiuntive, che solo loro potevano creare. Fra la richiesta e la consegna sono passate tre settimane, di cui due di silenzio. Ho lavorato nel frattempo su una copia del database ripristinata in locale, ma il collaudo vero è slittato. Da quel progetto in poi la prima telefonata del lavoro la faccio al fornitore del gestionale, non al cliente, e la sua disponibilità entra nel piano come dipendenza esterna con una data.
Gli agenti hanno aggirato il blocco sui duplicati
Impedito di creare un cliente senza cercarlo prima, due agenti hanno cominciato a usare un cliente generico «da definire» e a scrivere il nome vero nelle note. Tecnicamente il blocco funzionava; nei fatti il problema si era spostato. Si è risolto rendendo la ricerca tollerante agli errori di battitura e alle abbreviazioni — cercare «F.lli Rossi» e non trovare «Fratelli Rossi» era il motivo per cui premevano «nuovo».
I codici di pagamento non combaciavano e nessuno lo sapeva
Testo libero da una parte, codice a tabella dall'altra: 40 varianti scritte a mano per 9 condizioni reali. È saltato fuori al primo collaudo degli ordini, non in analisi, perché nessuno pensava che fosse un campo problematico. Sono servite due giornate non previste per costruire la tabella di conversione con l'amministrazione. È il tipo di sorpresa per cui tengo un margine dichiarato in preventivo invece di fingere che non esista.
09 / Risultati
Stesse grandezze, stesse fonti
Cosa è cambiato, misurato dove era stato misurato prima
Le righe qui sotto sono le stesse della tabella di partenza, rilevate con lo stesso metodo a otto settimane dalla consegna. Le grandezze che non sono migliorate restano in tabella: toglierle sarebbe il modo più elegante di mentire.
Prima e dopo, con la fonte di ogni numero
| Grandezza | Prima | Dopo | Come è misurata |
|---|---|---|---|
| Ore di ribattitura manuale | 11 h/settimana | 1,5 h/settimana | Stesso foglio ore, ripetuto per 10 giorni lavorativi |
| Anagrafiche duplicate | 312 su 1.847 | 0, con 4 casi nuovi in 2 mesi | Stesso confronto su partita IVA normalizzata |
| Ordini con prezzo corretto a posteriori | 6,1% | 0,4% | Estrazione ordini dal gestionale, stesso criterio su 2 mesi |
| Tempo medio di emissione offerta | 2,1 giorni | 3,2 ore | Differenza fra data visita nel CRM e data documento nel gestionale |
| Età del listino in mano agli agenti | 8,3 giorni | meno di 24 ore | Registro delle sincronizzazioni notturne |
| Chiamate in sede per verifiche di disponibilità | circa 20 al giorno | circa 12 al giorno | Conteggio tenuto dal centralino per 2 settimane, prima e dopo |
L'ultima riga è quella che è migliorata meno delle attese: le telefonate agli operativi sono scese di un terzo, non di due. Guardando meglio, metà delle chiamate non riguardava la disponibilità ma i tempi di consegna — un dato che il gestionale non espone e che il progetto non toccava. È rimasto sul tavolo come intervento successivo, non come risultato mancato.
Quello che non si misura in tabella
- Il lunedì mattina dell'ufficio commerciale è tornato a essere una mattina di lavoro commerciale.
- Gli agenti hanno smesso di tenere un listino personale in PDF sul telefono, che era la vera fonte di verità parallela.
- Le riunioni sul «quale numero è giusto» sono finite, perché la risposta è scritta in un posto e non è opinabile.
10 / Dopo
Perimetro e manutenzione
Cosa è entrato nel progetto e cosa no
Il perimetro dichiarato in partenza è rimasto quello. Le cose emerse in corsa sono state annotate e rimandate, non infilate dentro: è così che un progetto di nove settimane resta di nove settimane.
Consegnato
- Middleware in esercizio con monitoraggio e avvisi automatici
- Sincronizzazione di anagrafiche, listini e giacenze
- Percorso di ritorno degli ordini con stato visibile all'agente
- Bonifica una tantum dei duplicati e regola per non ricrearli
- Pagina degli scarti gestibile dall'ufficio commerciale
- Documentazione operativa e formazione di mezza giornata
- Codice sorgente e accessi consegnati al cliente
Fuori perimetro, dichiarato in partenza
- Sostituzione del gestionale o del CRM
- Tempi di consegna e stato delle spedizioni (non esposti dal gestionale)
- Automazione delle campagne di marketing sul CRM
- Portale web per i clienti finali
- Migrazione dello storico trattative anteriore al 2023
La lezione che mi porto da questo lavoro
La parte difficile di un'integrazione non è far passare i dati: è ottenere che qualcuno decida chi ha ragione. Se in azienda nessuno ha l'autorità di dire «sul prezzo comanda il gestionale, punto», nessuna architettura risolve il problema — lo sposta soltanto. Da allora la mappa dei campi con la colonna «chi comanda» la faccio firmare prima di aprire l'editor, e la riunione in cui si compila la conduco io.
11 / Obiezioni
Le domande che mi fanno su questo caso
Le tre domande che arrivano sempre
Sono quelle che si fa chi ha un problema simile e vuole sapere se vale anche per lui.
- Il mio gestionale è vecchio e chiuso. Vale lo stesso?
- Nella maggior parte dei casi sì, ed è esattamente la situazione di questo progetto: nessun accesso in scrittura, nessuna API moderna, contratto di manutenzione da non violare. Si lavora con quello che il fornitore espone — viste di sola lettura, tabelle di appoggio, export programmati — e il middleware assorbe la differenza. Se davvero non esiste nessun modo di leggere i dati, lo si scopre nella prima settimana e non nella terza.
- Quanto costa tenerlo acceso dopo?
- Un servizio del genere gira su una macchina piccola e ha un costo di esercizio nell'ordine delle decine di euro al mese, più il tempo di chi guarda gli avvisi. Quello che va messo a bilancio è la manutenzione evolutiva: ogni aggiornamento del gestionale o cambio di API del CRM è una verifica. Lo dichiaro in preventivo come canone facoltativo, non come vincolo: il codice è del cliente e chiunque può prenderlo in mano.
- Perché non avete usato un connettore già pronto?
- Perché i connettori pronti sanno spostare i campi, non decidere chi ha ragione quando due sistemi non concordano — e in questo progetto quello era il problema. Quando invece il problema è davvero solo spostare campi fra due sistemi molto diffusi, il connettore pronto è la risposta giusta e lo dico: non ho interesse a costruire a mano qualcosa che esiste già e costa meno.
12 / Correlate
Dove approfondire
Se questo caso somiglia al tuo
La pagina del servizio spiega il metodo in generale; gli altri casi mostrano lo stesso metodo su problemi diversi.
13 / Contatto
Trenta minuti, senza impegno
Il tuo caso somiglia a questo?
In mezz'ora capiamo se il problema è di integrazione o di autorità sui dati, e quale delle due cose va risolta per prima. Se non serve un intervento, te lo dico in chiamata.
Prima della chiamata puoi scaricare la mappa dei flussi dati e compilarne anche solo due righe: la conversazione parte da un altro punto.
Tutti i dati di contattoCome funziona la chiamata
- Minuti 0–10
- Cosa fai ribattere a mano oggi, e a chi
- Minuti 10–20
- Quali sistemi ci sono e cosa espongono davvero
- Minuti 20–30
- Se ha senso intervenire, da dove partirei e in quanto