
Integrazioni
Parte di Integrazioni tra software aziendali
Evitare duplicazioni tra sistemi
Come definire identificativi, regole di aggiornamento e controlli sui casi ambigui per evitare record doppi tra applicazioni.
Perché i duplicati nascono quando i sistemi si parlano
Un contatto o un'azienda può entrare nel CRM da un modulo, un inserimento manuale, un file di import, una chiamata API o un'app di sincronizzazione. Se ogni canale scrive senza verificare l'esistenza del record, lo stesso soggetto finisce in archivio più volte.
Il duplicato nasce in due casi: manca una chiave univoca condivisa tra i sistemi, oppure il flusso di scrittura non confronta i valori prima di creare il record. La soluzione parte dalla scelta di un identificatore e dalla sua applicazione in ogni canale.
HubSpot usa criteri automatici: email per i contatti, nome di dominio aziendale per le aziende. Quando non bastano, intervengono Record ID e proprietà personalizzate a valore unico.
Scegliere la chiave univoca giusta
HubSpot deduplica automaticamente i contatti tramite email e le aziende tramite nome di dominio aziendale. Sono i valori cercati prima di creare un nuovo record.
Per gli altri casi si usa il Record ID: consente la deduplica manuale di contatti, aziende, deal, ticket, prodotti, oggetti attivati dall'admin (per esempio gli appuntamenti) e oggetti personalizzati.
Nei file di import si possono includere la proprietà Record ID o proprietà personalizzate con valori univoci. Se il sistema esterno conserva una chiave stabile, quella è l'identificatore più affidabile; per i contatti da moduli e inserimenti manuali resta l'email.
Deduplica automatica nei canali di acquisizione
All'aggiunta di un nuovo contatto, HubSpot cerca un valore corrispondente nella proprietà Email. Il comportamento successivo varia per canale di ingresso.
Inserimento manuale: creando un contatto con un'email già presente, HubSpot avvisa che il contatto esiste e blocca l'aggiunta.
Invio di un modulo: se il contatto esiste con la stessa email, le nuove informazioni si aggiungono alla scheda esistente. Se il modulo usa l'email secondaria, quell'indirizzo sovrascrive l'email sul contatto.
Import: se il contatto esiste con la stessa email, i dati importati aggiornano il record esistente. Si aggiornano solo le proprietà mappate e l'import non elimina record.
Per le aziende, la deduplica automatica si basa sui valori primari della proprietà Company domain name. Se le aziende sono sincronizzate con un'app di data sync, possono applicarsi regole personalizzate.
Import massivi senza creare cloni
Per aggiornare record esistenti durante un import, il file deve contenere un identificatore: proprietà Email, Record ID o proprietà personalizzata a valore unico.
Se l'Email o un altro identificatore univoco non è presente, ogni riga del file viene importata come nuovo contatto.
L'import aggiorna solo le proprietà mappate: le colonne non incluse restano invariate sul record esistente. Nessun record viene cancellato dal caricamento.
Upsert in batch: creare o aggiornare con una sola chiamata
Per gli oggetti CRM esiste un endpoint batch upsert, invocato con POST, che crea o aggiorna oggetti in base a valori di proprietà univoci. Il tipo di oggetto si indica nel percorso della richiesta.
Il corpo della richiesta contiene un array inputs; ogni elemento comprende i campi id, properties, idProperty e objectWriteTraceId.
idProperty indica la proprietà da usare per il confronto. Se la si valorizza con una proprietà univoca condivisa tra i sistemi, la stessa entità viene aggiornata anziché duplicata, anche se la chiamata arriva da un'integrazione diversa dal CRM.
Sincronizzazione tra sistemi e regole personalizzate
Nelle sincronizzazioni le regole di deduplica non sono sempre predefinite: per le aziende sincronizzate con un'app di data sync di HubSpot possono valere regole personalizzate.
Va verificato il comportamento su entrambi i lati: se origine e destinazione creano record con criteri diversi, un record nato a valle può tornare a monte come entità nuova.
Nei pattern publish/subscribe un publisher invia eventi a un broker senza conoscere i consumatori; ogni subscriber riceve i messaggi che gli interessano. Lo stesso evento può raggiungere più sistemi e, se rielaborato, produrre scritture ripetute.
Un consumatore che riceve un evento già trattato dovrebbe aggiornare il record tramite una proprietà univoca, con la stessa logica dell'upsert, invece di creare una seconda scheda.
Correggere i duplicati già presenti
La deduplica manuale si esegue tramite Record ID. La proprietà è utilizzabile su contatti, aziende, deal, ticket, prodotti, oggetti attivati dall'admin (per esempio gli appuntamenti) e oggetti personalizzati.
Quando due schede sono già presenti, l'import è uno dei modi per unirle: si include il Record ID del record da mantenere, oppure una proprietà a valore univoco, e si caricano i dati da consolidare.
Poiché l'import non elimina record esistenti, la scheda duplicata resta in archivio dopo l'aggiornamento e va rimossa separatamente.
Errori tipici e accorgimenti operativi
Import senza Email e senza altro identificatore univoco: ogni riga del file diventa un nuovo contatto.
Più record già esistenti con la stessa email del contatto importato: l'import restituisce un errore e quel contatto non viene importato.
Email secondaria e colonna Record ID nel file, con l'email secondaria usata come identificatore univoco: l'email secondaria sostituisce l'email primaria sul contatto esistente.
Per evitare la sovrascrittura dell'email primaria in questo scenario, la colonna Record ID non va inclusa nel file di import.
Casi di errore comuni durante l'import
- Import senza identificatore
- Ogni riga diventa un nuovo contatto
- Più record con stessa email
- Import fallisce e blocca il contatto
- Email secondaria come identificatore
- Sovrascrive l'email primaria sul contatto esistente
Checklist per evitare duplicazioni tra sistemi
Definire per ogni oggetto un identificatore univoco: email per i contatti, dominio aziendale per le aziende, Record ID o proprietà a valore unico per gli altri oggetti.
Mappare quell'identificatore in tutti i canali di scrittura — moduli, inserimenti manuali, import e chiamate API — e sapere quali proprietà vengono effettivamente aggiornate.
Negli import includere sempre l'identificatore: senza di esso ogni riga crea un nuovo record, mentre le email già duplicate bloccano il caricamento.
Nelle integrazioni usare l'upsert in batch con idProperty e controllare le regole di deduplica su origine e destinazione, comprese quelle personalizzate delle app di data sync.
Monitorare gli errori di import e correggere i duplicati già presenti con il Record ID, rimuovendo alla fine le schede che restano in archivio.



