CRM ed ERP
Pattern di integrazione con Salesforce, HubSpot, Dynamics 365, SAP, gestionali italiani e sistemi legacy AS/400.
Blu Pantheon non sostituisce il tuo CRM o il tuo ERP: li alimenta e li interroga. Questa pagina descrive i pattern di integrazione disponibili, la mappatura dei campi, la gestione dei duplicati e la sincronizzazione bidirezionale.
Prima di iniziare
- Ruolo Amministratore tenant oppure permesso config:integrations:write
- Credenziali di un utente tecnico sul CRM o ERP, con permessi minimi necessari
- Un ambiente di prova del sistema di destinazione (sandbox)
- Una chiave di correlazione condivisa fra i due sistemi, definita prima di iniziare
Scegliere il pattern
| Pattern | Come funziona | Quando usarlo | Latenza tipica |
|---|---|---|---|
| Event-driven via webhook | Blu Pantheon notifica il tuo sistema a ogni evento rilevante | Il tuo sistema può esporre un endpoint HTTPS pubblico | Da 1 a 5 secondi |
| Strumento richiamabile dal modello | L'assistente interroga il tuo sistema durante la conversazione | Serve un dato aggiornato in tempo reale (stato ordine, saldo punti) | Da 200 a 2000 ms |
| Polling delle API | Il tuo sistema interroga periodicamente Blu Pantheon | Il tuo sistema non può ricevere chiamate in ingresso | Pari all'intervallo di polling |
| Batch su file | Scambio di file CSV o JSON su SFTP a orari prestabiliti | Volumi elevati, sistemi legacy, allineamenti notturni | Da 1 a 24 ore |
| Middleware | Un livello intermedio (integration platform) media fra i due sistemi | Trasformazioni complesse, più sistemi coinvolti | Variabile |
Regola pratica
Usa i webhook per notificare, gli strumenti richiamabili per leggere durante la conversazione, il batch per l'allineamento massivo. La combinazione dei tre copre praticamente tutti gli scenari reali.
Webhook contro polling
| Criterio | Webhook | Polling |
|---|---|---|
| Latenza | Immediata | Pari all'intervallo |
| Consumo di quota API | Nullo in ingresso | Elevato, anche a vuoto |
| Complessità di implementazione | Endpoint pubblico e verifica della firma | Solo un client HTTP |
| Affidabilità | Ritentativi automatici con attesa crescente | Dipende dal tuo scheduler |
| Requisito di rete | Endpoint raggiungibile da Internet | Nessuno |
| Rischio di perdita eventi | Basso, con coda di ritentativi | Alto se lo scheduler si ferma |
Se scegli il polling
Usa la paginazione a cursore e il parametro updatedSince, non scaricare l'intero elenco a
ogni giro. Rispetta i limiti di frequenza e gestisci
l'header Retry-After.
Mappatura dei campi cliente
Mappatura di riferimento fra l'anagrafica di Blu Pantheon e i sistemi più diffusi.
| Blu Pantheon | Salesforce | HubSpot | Dynamics 365 | SAP | Note |
|---|---|---|---|---|---|
contact.id | Contact.Id | contact.hs_object_id | contact.contactid | BusinessPartner | Identificativo interno, non usarlo come chiave condivisa |
contact.externalId | Contact.External_Id__c | contact.external_id | contact.new_externalid | BusinessPartner | Chiave di correlazione, campo personalizzato dedicato |
contact.firstName | Contact.FirstName | contact.firstname | contact.firstname | FirstName | — |
contact.lastName | Contact.LastName | contact.lastname | contact.lastname | LastName | — |
contact.email | Contact.Email | contact.email | contact.emailaddress1 | EmailAddress | Normalizzare in minuscolo |
contact.phone | Contact.MobilePhone | contact.phone | contact.mobilephone | PhoneNumber | Formato E.164, es. +393401234567 |
contact.company | Account.Name | company.name | account.name | BusinessPartnerName | Su Salesforce serve la relazione con Account |
contact.vatNumber | Account.VAT_Number__c | company.vat_number | account.new_partitaiva | TaxNumber1 | Con prefisso IT |
contact.taxCode | Account.Codice_Fiscale__c | company.codice_fiscale | account.new_codicefiscale | TaxNumber2 | Specifico italiano, quasi sempre campo personalizzato |
contact.source | Contact.LeadSource | contact.hs_analytics_source | contact.leadsourcecode | — | Valorizzato a blupantheon |
contact.consent.marketing | Contact.HasOptedOutOfEmail | contact.hs_email_optout | contact.donotemail | — | Attenzione: logica invertita |
contact.tags | Contact.Topics | contact.hs_content_membership_notes | Campo personalizzato | — | Elenco di etichette |
contact.lastInteractionAt | Contact.LastActivityDate | contact.notes_last_updated | contact.lastonholdtime | — | Sola scrittura da Blu Pantheon |
Il consenso ha logica invertita
In Blu Pantheon consent.marketing = true significa consenso concesso. In Salesforce
HasOptedOutOfEmail = true significa rinuncia. Una mappatura diretta senza inversione
produce invii a persone che si sono opposte: è una violazione, non un semplice difetto.
Verifica esplicitamente questa trasformazione in fase di collaudo.
Chiave di correlazione e duplicati
Definisci una sola chiave di correlazione
Deve essere stabile (non cambia nel tempo), univoca e presente su entrambi i lati.
In ordine di preferenza: identificativo del CRM salvato in contact.externalId; in alternativa
Codice Fiscale o Partita IVA per i contesti B2B italiani. L'email è la scelta peggiore: cambia,
è condivisa in famiglia e in azienda, e viene scritta in modi diversi.
Normalizza i valori prima del confronto
Email in minuscolo, senza spazi. Telefono in formato E.164. Partita IVA senza spazi e con prefisso del Paese. Codice Fiscale in maiuscolo.
Definisci la strategia di deduplica
Confronto esatto sulla chiave primaria; in assenza, confronto su una chiave secondaria (email normalizzata più cognome). Non usare confronti approssimati per fondere automaticamente: generano fusioni errate difficili da annullare.
Stabilisci che cosa succede in caso di conflitto
Le opzioni sono: creare comunque un nuovo record e segnalarlo; aggiornare il record esistente; mettere in coda per revisione manuale. Per i dati anagrafici la revisione manuale è la scelta più prudente.
Attiva la deduplica in Console
| Scenario | Comportamento consigliato |
|---|---|
| Nuovo contatto senza corrispondenza | Crea il record nel CRM e salva l'identificativo restituito in externalId |
| Corrispondenza univoca sulla chiave primaria | Aggiorna solo i campi vuoti nel CRM, non sovrascrivere quelli valorizzati |
| Corrispondenze multiple | Non fondere: segnala per revisione manuale |
| Corrispondenza solo sull'email | Aggiorna con cautela, mai fondere automaticamente |
| Contatto cancellato nel CRM | Interrompi la sincronizzazione, non ricrearlo |
Sincronizzazione bidirezionale e conflitti
| Strategia | Descrizione | Quando usarla |
|---|---|---|
| Il CRM è la fonte di verità | Blu Pantheon scrive solo i campi che il CRM non gestisce | Scelta consigliata nella maggior parte dei casi |
| Blu Pantheon è la fonte di verità | Il CRM riceve e non contraddice | Quando il primo contatto avviene sempre dal canale conversazionale |
| Ultima scrittura vince | Prevale la modifica con timestamp più recente | Solo con orologi sincronizzati e campi non critici |
| Per campo | Ogni campo ha una propria fonte di verità | La più corretta, la più laboriosa da configurare |
Esempio di assegnazione per campo:
| Campo | Fonte di verità | Motivo |
|---|---|---|
| Nome e cognome | CRM | Verificati dal commerciale |
| Email e telefono | CRM | Verificati in fase di contratto |
| Consensi | Blu Pantheon | Raccolti nel widget con prova e versione dell'informativa |
| Ultima interazione | Blu Pantheon | Solo la piattaforma conosce le conversazioni |
| Segmento commerciale | CRM | Determinato dai processi di vendita |
| Etichette conversazionali | Blu Pantheon | Derivate dall'analisi delle sessioni |
Evita i cicli di aggiornamento
Se entrambi i sistemi scrivono e notificano, una modifica può rimbalzare all'infinito.
Marca sempre gli aggiornamenti con l'origine (source) e ignora gli eventi originati da te
stesso. È il difetto più comune nelle integrazioni bidirezionali.
Eventi disponibili
| Evento | Quando scatta | Uso tipico nel CRM |
|---|---|---|
contact.created | Nuovo contatto identificato | Creazione lead |
contact.updated | Modifica di dati anagrafici | Aggiornamento anagrafica |
contact.optout.updated | Modifica dei consensi | Aggiornamento preferenze di contatto |
session.started | Inizio di una conversazione | Registrazione attività |
session.ended | Chiusura della conversazione | Attività con riepilogo e sentiment |
session.handover.requested | Richiesta di operatore umano | Creazione caso o ticket |
lead.qualified | Il flusso ha qualificato un lead | Creazione opportunità |
booking.confirmed | Prenotazione confermata | Creazione appuntamento |
booking.cancelled | Disdetta | Annullamento appuntamento |
order.status.requested | L'utente chiede lo stato di un ordine | Interrogazione ERP |
Vedi il riferimento webhook per i payload completi.
Esempio end-to-end
Scenario: un visitatore chiede informazioni sul widget, viene qualificato come lead, il CRM crea l'opportunità e l'assistente conferma un appuntamento leggendo le disponibilità dell'ERP.
Il visitatore avvia la conversazione
Il widget apre una sessione. Blu Pantheon emette session.started con l'identificativo di
sessione e l'origine (pagina, campagna, dispositivo).
Il flusso raccoglie i dati di qualificazione
Nome, azienda, email aziendale, esigenza, tempistica. Il consenso privacy è già stato raccolto all'apertura del widget.
Blu Pantheon notifica il lead qualificato
{
"event": "lead.qualified",
"occurredAt": "2026-09-04T10:12:44Z",
"tenant": "acme-srl",
"data": {
"sessionId": "ses_01JQ8M4Z5T",
"contact": {
"firstName": "Mario",
"lastName": "Rossi",
"email": "mario.rossi@acme.it",
"phone": "+393401234567",
"company": "ACME S.r.l.",
"vatNumber": "IT01234567890"
},
"qualification": {
"need": "Assistenza clienti automatizzata",
"timeframe": "entro 3 mesi",
"score": 78
},
"consent": { "marketing": true, "version": "2026-09" },
"source": { "channel": "widget", "page": "https://www.acme.it/prezzi", "campaign": "ricerca-brand" }
}
}Il tuo middleware verifica la firma e deduplica
Verifica l'header di firma HMAC, poi cerca il contatto per email normalizzata. Se esiste, aggiorna; altrimenti crea il record e l'opportunità.
curl -X POST "https://integrazioni.acme.it/blupantheon/eventi" \
-H "Content-Type: application/json" \
-H "X-BP-Signature: sha256=FIRMA_CALCOLATA" \
-H "X-BP-Delivery: dlv_01JQ8M4Z5T7C" \
-d @evento.jsonIl middleware restituisce l'identificativo al contatto
curl -X PATCH "https://api.blupantheon.com/console/v1/contacts/cnt_01JQ8M4Z5T" \
-H "Authorization: Bearer $BP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"externalId": "0035g00000ABCDEfgh", "source": "salesforce"}'Da questo momento i due sistemi sono correlati in modo stabile.
L'assistente propone un appuntamento
Il modello richiama lo strumento disponibilita_consulenza, che interroga l'ERP e
restituisce gli slot liberi. L'utente sceglie, il flusso conferma.
Blu Pantheon notifica la conferma
L'evento booking.confirmed alimenta l'appuntamento nel CRM e la conferma via email o WhatsApp
parte automaticamente.
Integrazione con sistemi legacy
Per S/4HANA e Business One il percorso consigliato è l'esposizione di servizi OData tramite SAP Gateway, mediati da un livello di integrazione.
- Lettura (stato ordine, saldo, anagrafica): strumento richiamabile dal modello che chiama il tuo middleware, che a sua volta interroga OData. Non esporre mai SAP direttamente su Internet.
- Scrittura (creazione lead, attività): coda di messaggi alimentata dai webhook, consumata dal middleware con ritentativi.
- Allineamento massivo: estrazione notturna in CSV su SFTP.
- Prestazioni: prevedi una cache di 5 o 10 minuti sui dati poco volatili, altrimenti la latenza percepita in conversazione diventa inaccettabile.
Verifica e messa in produzione
Collauda in ambiente di prova
Usa la sandbox del CRM e un progetto di prova su Blu Pantheon. Non collaudare mai su dati reali.
Verifica i casi limite
Contatto senza email, nomi con apostrofi e accenti, numeri di telefono esteri, Partita IVA estera, contatto già esistente, contatto cancellato, campi obbligatori mancanti nel CRM.
Prova la resilienza
Simula il tuo endpoint non raggiungibile e verifica che i ritentativi funzionino e che nessun evento venga perso. Vedi Webhook non ricevuti.
Attiva il monitoraggio
Configura un alert sugli errori di consegna e verifica settimanalmente il registro delle sincronizzazioni.
Vai in produzione per gradi
Attiva prima un solo evento, verifica per qualche giorno, poi estendi agli altri.
Ricette pronte
Molte integrazioni sono già disponibili come modelli configurabili: vedi Ricette di automazione.