Connettori bidirezionali tra CRM Ubiquity o Odoo e i sistemi aziendali che li circondano: ERP, mail, ticketing, data warehouse, piattaforme e-commerce. Sincronizzazione eventi in near-real-time via webhook, queue durable per gestire picchi, retry esponenziale con dead-letter queue, monitoring dei job. Deploy production-grade con clienti retail, servizi, editoria.
01Perché un'integrazione custom e non un "connector marketplace"
I connettori pronti esistono. Il problema è che risolvono bene il 60% dei casi d'uso generici e zero dei casi d'uso che hanno un senso nel vostro dominio. Un cliente retail con listini stagionali, un editore con abbonamenti a rinnovo mensile, un'azienda di servizi con SLA per classe di contratto: ognuno ha regole di business che non stanno in una UI "drag-and-drop".
Quello che serve, dopo vent'anni di viste passare, è sempre lo stesso: logica di dominio specifica codificata dove può essere letta, testata, versionata; mapping field complesso con trasformazioni condizionali (non "copia campo A su campo B"); governance dati chiara su chi è la fonte di verità per ogni campo; e capacità di fare debugging quando alle 7 di mattina il commerciale dice che l'ordine di ieri non è passato in ERP.
Il marketplace connector è una scatola nera. Il connettore che scriviamo noi è codice in chiaro, sotto Git, con log strutturati e test di regressione. Quando si rompe — e prima o poi si rompe — sappiamo dove guardare.
02Pattern che usiamo
Non c'è un'unica architettura giusta. Ci sono quattro pattern che combiniamo in base a cosa serve davvero:
- Event-driven (webhook → queue → worker): il CRM emette un evento, entra in una coda, un worker lo processa con ritmo sostenibile. È il pattern di default per near-real-time.
- Bulk sync notturno: per grandi volumi di anagrafiche o riconciliazioni contabili, un job batch è più efficiente di mille webhook. Di notte, quando i sistemi non sono sotto carico.
- Riconciliazione periodica: un processo che ogni N ore confronta due fonti e rileva drift — record modificati che non sono passati, eventi persi, stato incoerente. È la rete di sicurezza che nessuno pensa di dover avere finché non serve.
- Idempotency key su ogni operazione: ogni evento porta un identificatore unico. Se arriva due volte (succede), il secondo tentativo è no-op. Senza questo, ogni retry diventa potenzialmente un duplicato.
03Resilience
L'integrazione deve continuare a funzionare quando qualcosa va storto, non se. Ogni sistema con cui parliamo andrà giù, lentamente o tutto in una volta, almeno una volta all'anno. Cosa mettiamo di default:
- Retry esponenziale con jitter: primo tentativo dopo 2 secondi, poi 4, 8, 16, fino a un tetto. Il jitter serve a non sincronizzare tutti i worker sullo stesso secondo quando un endpoint torna su.
- Circuit breaker su endpoint che mostrano latenza anomala o tasso di errore alto: smettiamo di chiamare per N minuti e ripartiamo in half-open. Meglio stoppare pulito che saturare un sistema già in difficoltà.
- Dead-letter queue per eventi che hanno esaurito i retry: non vengono persi, restano ispezionabili, possono essere rilanciati a mano dopo che un umano ha capito cosa è successo.
- Alert quando la coda cresce oltre soglia: se il backlog aumenta, qualcosa a valle non sta tenendo il passo. Lo sappiamo prima che il cliente lo noti.
04Monitoring
Un'integrazione che non è osservabile è un bug in attesa. Su ogni deployment configuriamo un cruscotto minimo ma serio: job status in tempo reale (quanti elaborati, quanti in coda, quanti in errore), latenza per endpoint (p50 / p95 / p99), tasso di errore per tipo di evento e per sistema di destinazione, backlog queue con trend.
Stack tipico: Prometheus + Grafana per metriche, Loki o ELK per log strutturati, alerting su Slack o email verso il NOC PSA. Nessun plugin proprietario: se domani il cliente vuole portarsi l'intero osservatorio altrove, lo fa in un pomeriggio.
05Mapping dati bidirezionale
La parte in cui si spendono davvero le ore, onestamente, non è il codice di trasporto. È il mapping. Due sistemi che dicono "cliente" non intendono quasi mai la stessa cosa. Cosa curiamo:
- Anagrafiche unificate con deduplicazione: stesso cliente in due sistemi, codici fiscali normalizzati, fuzzy matching per catturare le varianti (S.r.l. vs srl vs S.R.L.).
- Normalization: telefoni in E.164, email lowercase, partite IVA validate con checksum, indirizzi passati per un geocoder quando serve.
- Policy "source of truth" per campo: il CRM è autoritativo per il nome commerciale, l'ERP per la ragione sociale fiscale, il ticketing per lo stato del contratto. Scritto, non implicito.
- Storico modifiche: audit log di chi ha cambiato cosa, quando, e da quale sistema. Indispensabile quando bisogna capire perché un campo è cambiato ieri notte.
06Sistemi tipici integrati
Abbiamo messo in piedi pipeline verso molti ambienti diversi. Quelli che ricorrono di più:
- ERP: SAP (Business One e S/4HANA), Odoo ERP, gestionali custom, sistemi legacy AS/400 via middleware REST.
- Mail: Postfix aziendali on-premise, Google Workspace, Microsoft 365 via Graph API.
- Ticketing: Zendesk, Freshdesk, sistemi interni basati su DB relazionale.
- E-commerce: Magento, WooCommerce, piattaforme proprietarie.
- Data warehouse e BI: export incrementali verso Postgres analitici, BigQuery, Power BI, Metabase.
Il pattern è sempre lo stesso: capiamo cosa deve arrivare dove, con che SLA di freschezza, e scegliamo il meccanismo di trasporto adatto. Non c'è una risposta universale.
07Adozione tipica
Un progetto medio prende questa forma:
- Audit sistemi esistenti (1 settimana): inventario endpoint, credenziali, volumi, punti dolenti attuali. Niente riunioni da 15 persone — due chiamate tecniche mirate.
- Design integrazione (2 settimane): diagramma flussi, decisioni sul source-of-truth per campo, scelta pattern (event-driven vs batch), dimensionamento code.
- Sviluppo (4-8 settimane a seconda della complessità): implementazione connettori, test unitari e di integrazione, ambiente di staging con dati sintetici.
- Pilot (2 settimane): traffico reale su un sottoinsieme — una filiale, un tipo di documento, un canale — per vedere come si comporta sotto carico vero.
- Go-live con monitoring attivo e reperibilità PSA sulle prime due settimane post-rollout.
Poi c'è la parte che nessuno mette nelle slide commerciali: la manutenzione continuativa. Le API cambiano, i volumi crescono, il cliente aggiunge un sistema. Inclusa come canone fisso, con SLA scritti e interventi tracciati.
Pattern di sync a confronto
| Pattern | Pro | Contro |
|---|---|---|
| Real-time webhook | Freschezza sub-minuto, nessun polling, leggero sulla rete | Richiede endpoint pubblici, gestione retry critica, sensibile a picchi |
| Batch notturno | Robusto sui grandi volumi, riconciliabile, impatto zero sui sistemi di giorno | Latenza fino a 24h, non adatto a dati operativi |
| Polling periodico | Funziona anche senza webhook lato sorgente, freschezza configurabile | Carico continuo sugli endpoint, costi API più alti, lag inevitabile |
La scelta giusta quasi mai è una sola di queste tre: il deploy tipico mescola webhook per i flussi caldi (ordini, ticket), batch notturno per riallineamenti contabili, polling periodico per i sistemi che non offrono hook. E sopra a tutto, riconciliazione periodica come rete di sicurezza.