Un client communique une nouvelle adresse email à votre équipe. La correction entre dans l’ERP, puis le connecteur HubSpot transmet le prochain lot. Une seconde fiche apparaît, ou la mise à jour reste bloquée alors que le contact existe déjà. Le problème commence souvent avant le transport : le middleware a demandé une création ou une mise à jour par email, alors que le métier voulait modifier une personne déjà identifiée.
En réalité, le bon identifiant ne suffit pas : il faut aussi choisir la bonne opération. Une correction de téléphone n’autorise pas l’ouverture d’un contact. À l’inverse, un flux d’acquisition peut réellement devoir créer une personne encore inconnue. Réunir ces deux intentions derrière une méthode interne appelée « synchroniser » masque la décision qui compte pour le commercial et pour le support.
Vous allez suivre une correction de contact, distinguer PATCH et upsert, puis éprouver un préparateur local avec 48 contrôles exécutés. Il conserve la différence entre champ absent, valeur inconnue et effacement demandé. Il produit seulement des descriptions de requêtes sur des données fictives : aucune opération HubSpot n’est envoyée et aucune réussite distante n’est simulée comme une preuve réelle.
Cette analyse précise une difficulté traitée dans nos intégrations API entre logiciels métier. Pour votre portail, le cadrage d’une connexion HubSpot avec l’ERP et les applications internes doit établir qui peut modifier le contact, par quelle référence et dans quels cas une création reste autorisée.
Pour qui : une correction ERP produit une nouvelle fiche HubSpot
Retrouver la personne derrière les deux adresses
Le cas concerne une personne déjà rapprochée entre la gestion et le CRM. Sa référence interne reste la même, mais ses coordonnées changent. Dans notre scénario fictif, ERP-PERSON-007 désigne cette personne et 901 son Record ID HubSpot fourni au laboratoire. La nouvelle adresse doit devenir une propriété de cette fiche, plutôt que remplacer automatiquement la clé utilisée pour la retrouver.
Une boîte partagée ou un changement d’employeur demande un examen différent. Le métier peut vouloir créer un nouveau contact, modifier une association ou conserver plusieurs coordonnées. Le programme ne décide pas que deux emails représentent toujours une même personne. Il commence avec une correspondance déjà qualifiée ; il ne résout ni les homonymes ni les relations entre personne, société commerciale et client facturable.
Identifier l’écriture réellement demandée par le connecteur
Retrouvez la méthode HTTP, le chemin, la clé de recherche et les propriétés de l’exécution concernée. Une ligne de journal « contact synchronisé » ne permet pas de savoir si le connecteur a ciblé une fiche connue ou autorisé sa création. Le signal faible est une référence CRM qui change après une simple correction de coordonnées, sans décision d’ouverture enregistrée dans le dossier métier.
Le coût des corrections se lit ensuite dans les activités dispersées, les conversations ouvertes sur deux fiches et les corrections manuelles. Ne fusionnez pas immédiatement les contacts pour faire disparaître ce symptôme. Il faut d’abord comprendre quelle requête les a produits et quels liens ont été consommés. Une fusion peut modifier d’autres références ; elle ne corrige pas le choix d’opération qui recréera le problème au lot suivant.
PATCH et upsert ne portent pas la même autorisation de création
Modifier une fiche connue avec son Record ID
La référence native Update a contact en CRM v3 documente un PATCH vers /crm/v3/objects/contacts/{contactId}. Les propriétés fournies remplacent leurs valeurs correspondantes. Une chaîne vide peut effacer une valeur ; les propriétés inexistantes ou en lecture seule provoquent une erreur. Le laboratoire utilise ce contrat explicitement legacy, sans remplacer silencieusement son chemin par celui d’une API datée.
Le mode local update_only exige un contact connu dans le portail déclaré. Il prépare le chemin avec le Record ID et garde le nouvel email dans les propriétés. Si cette correspondance manque, il retient la demande. Il ne bascule pas vers un autre endpoint pour obtenir à tout prix une réponse positive. Ce refus préserve l’intention « corriger l’existant » jusqu’à ce qu’une personne qualifie la cible.
Autoriser explicitement le cas où la personne n’existe pas
La référence native Contacts CRM v3 distingue le batch update, identifié par Record ID, et le batch upsert, capable de créer ou modifier. L’upsert utilise une propriété d’identification et sa valeur. Les noms de ces opérations ne sont pas interchangeables dans le SDK : leur différence doit remonter jusqu’au service qui autorise l’écriture.
L’annonce développeur HubSpot de septembre 2024 présente déjà l’extension de l’upsert à l’email. Ce mécanisme n’est donc pas une nouveauté réservée aux APIs datées de 2026. Pour autant, sa présence dans le catalogue ne signifie pas qu’il convient à chaque correction ERP. Un flux de maintenance peut avoir l’interdiction de créer, même si son compte technique possède les droits nécessaires.
Conserver la cible lors du changement d’email
Séparer référence de personne et compte de facturation
La référence ERP-PERSON-007 représente ici un contact de l’application source. Elle n’est pas le code du client qui reçoit les factures. Réutiliser un code société partagé par plusieurs personnes comme clé unique de contact empêcherait de les distinguer. Avant de créer une propriété, documentez l’objet exact que sa valeur identifie, sa provenance et le périmètre dans lequel elle est attribuée.
L’analyse HubSpot, e-commerce et clients ERP détaille ces niveaux d’identité. Notre correction intervient après cette qualification. Le middleware conserve le couple portail et référence de personne, retrouve le contact convenu et prépare uniquement les propriétés autorisées. Un email nouveau n’est ni une preuve de nouvelle personne ni une autorisation de déplacer ses documents vers un autre compte ERP.
Prévoir les correspondances absentes ou devenues contradictoires
Le laboratoire retient deux correspondances fournies pour une même personne, même si elles donnent accidentellement le même Record ID. Cette politique signale un inventaire à nettoyer au lieu de choisir le premier résultat. Elle retient aussi une fiche déclarée archivée. Ces décisions locales n’établissent pas les permissions réelles du compte technique et ne cherchent aucun autre contact dans le portail.
Une fusion ou une intervention humaine peut faire évoluer l’identité retournée par le CRM. Le Record ID n’est donc pas présenté comme immuable pendant tout le cycle de vie. Il faut vérifier la correspondance au moment utile et conserver son origine. En cas de divergence, le support recherche la fiche et son historique avant de remplacer la référence ou d’autoriser une création pour contourner l’anomalie.
Pourquoi un upsert partiel par email demande un autre contrat
Lire la limite native sans lui inventer un comportement
La documentation Contacts avertit que les upserts partiels ne sont pas pris en charge avec email comme idProperty et demande une propriété personnalisée unique pour ce besoin. L’exemple voisin utilise pourtant l’email avec peu de propriétés. Cette proximité ne prouve ni un effacement des champs omis, ni un code d’erreur précis, ni un échec systématique. Le connecteur doit qualifier le contrat, plutôt que déduire une garantie de la brièveté d’un exemple.
Dans notre préparateur, le profil de création ou mise à jour partielle refuse donc l’email comme clé. Ce refus est produit par notre politique, avant tout appel. Il ne reproduit pas une réponse native HubSpot. Si le besoin porte seulement sur un contact connu, le mode PATCH reste distinct ; il n’a pas à obtenir l’autorisation de créer pour pouvoir changer un téléphone.
Qualifier la propriété unique avant de lui confier les personnes
La référence Properties CRM v3 décrit la création d’une propriété avec hasUniqueValue et l’utilisation de valeurs uniques pour identifier des enregistrements. Une propriété texte simplement nommée « référence ERP » n’offre pas cette preuve. Son nom interne, son type et sa définition doivent être vérifiés dans le bon portail avant d’en faire une clé d’écriture.
Le laboratoire reçoit une définition fictive erp_contact_ref, de type chaîne, déclarée unique. Son mode create_or_update exige aussi une autorisation explicite de création. Il place idProperty, la référence source et les propriétés dans chaque entrée du batch v3. Cette préparation ne remplit pas rétroactivement la propriété sur les anciens contacts : un déploiement réel doit rapprocher ces fiches et traiter les valeurs manquantes avant ouverture.
Exercice corrigé : préparer les requêtes sans écrire dans HubSpot
Comparer une modification, un effacement et un upsert autorisé
Le préparateur Python complet s’exécute avec la bibliothèque standard. Ses identités et ses coordonnées sont inventées ; le domaine example.test sert au scénario local. Il ne charge aucun secret, ne réalise aucun HTTP et ne modifie aucun stockage. Les descripteurs produits permettent de relire la décision et la forme de requête, sans prétendre certifier une opération acceptée par votre portail.
python3 contact_patch_inventory.pyLa sortie affiche les noms des 48 contrôles réussis et quatre exemples préparés. La première correction et la suivante gardent le chemin du contact 901, même si la première change l’email. Une autre entrée prépare un effacement de téléphone expressément autorisé. Le dernier exemple montre un batch upsert par clé personnalisée avec son risque de création indiqué séparément.
| Demande du scénario | Décision locale attendue |
|---|---|
| Changer l’email d’une personne déjà rapprochée | PATCH sur le Record ID connu |
| Corriger sans correspondance CRM qualifiée | Attente, aucune création de secours |
| Envoyer un téléphone inconnu, noté null | Attente, aucune conversion en chaîne vide |
| Effacer le téléphone avec une instruction explicite | PATCH avec phone vide |
| Créer ou modifier par clé personnalisée qualifiée | POST upsert avec création autorisée |
Garder trois intentions pour une propriété manquante
Un champ absent n’est pas ajouté au descripteur. Une valeur None est considérée comme inconnue et retient la préparation. Une chaîne vide exige une autorisation d’effacement sur l’un des champs prévus par le profil, téléphone ou fonction. Ce choix évite qu’une cellule non renseignée dans un export soit transformée en consigne destructive par un simple remplacement de null.
Cette convention appartient à notre entrée locale. Elle ne prétend pas décrire tous les traitements de null par HubSpot. Elle refuse également les espaces non qualifiés, les booléens utilisés comme chaînes et les propriétés hors périmètre. Le programme n’est pas un validateur complet d’email, de téléphone ou de droits CRM. Une sortie « préparée » demande encore la validation métier, le schéma du portail et la recette du transport.
Les contrôles vérifient aussi la séparation des portails déclarés, les contacts archivés, les métadonnées de clé insuffisantes et l’intégrité des entrées après préparation. Un exemple d’encodage garde un identifiant fictif dans un seul segment de chemin ; il ne certifie pas son format natif. Répéter le calcul produit le même descripteur, sans démontrer l’idempotence des automatismes qu’une écriture réelle pourrait déclencher.
Une réponse perdue ne change pas une correction en création
Retrouver l’effet sur la fiche initialement ciblée
Si le transport expire après l’envoi d’un PATCH, le dossier doit conserver son chemin, ses propriétés et sa référence de corrélation. Remplacer cette tentative par un upsert utilisant le nouvel email modifie la question posée au CRM. La reprise commence par relire le contact autorisé et par rechercher l’effet de la tentative, dans les limites des accès disponibles.
La comparaison doit tenir compte des écritures concurrentes. Une valeur identique à celle demandée constitue une observation utile, mais ne prouve pas à elle seule l’origine du changement ou l’exécution de chaque workflow attendu. Si le commercial a effectué une autre correction entre-temps, rejouer l’ancien payload peut restaurer une donnée dépassée. Le runbook doit expliquer qui arbitre cette situation et quelle nouvelle commande peut être préparée.
Limiter l’effacement et le retour arrière à leur véritable portée
Un effacement réussi de téléphone n’autorise pas l’effacement des autres coordonnées. Conservez les champs visés, leur état connu avant traitement et la décision qui a permis la chaîne vide. Une correction inverse doit vérifier l’état actuel ; restaurer un ancien export entier pourrait écraser des informations ajoutées depuis. Le laboratoire ne construit aucune compensation et ne garantit pas une annulation distante.
La gestion des consentements HubSpot reste un chantier séparé. Modifier une adresse ou une fonction ne donne pas le droit d’élargir une préférence de communication. Le profil de l’exercice ne transporte aucun consentement, association ou étape commerciale ; ces objets demandent leurs propres propriétaires et règles de validation.
Erreurs fréquentes dans le SDK et dans les imports de contacts
Utiliser le nouvel email pour retrouver la fiche à corriger. Le middleware possède parfois déjà un Record ID mais l’écarte au profit d’un champ qui vient de changer. Comparez le code qui construit la cible avec celui qui prépare les propriétés. La recette doit montrer que la correction et l’enrichissement suivant rejoignent la personne qualifiée, plutôt que déduire une création de l’absence d’une correspondance locale.
Traiter une valeur absente comme une demande d’effacement. Le signal apparaît lorsque les champs enrichis par le commerce disparaissent après un export ERP plus pauvre. Faites relire la transformation de chaque valeur inconnue, puis conservez l’instruction de suppression séparément. Ajouter un retry au même payload ne réparera pas cette ambiguïté ; il répétera une demande dont le sens n’a jamais été validé.
Activer l’upsert parce que le PATCH est en erreur. Une permission, une propriété supprimée ou une correspondance périmée exige un diagnostic de sa cause. Changer d’opération pour contourner ce refus peut ouvrir une fiche inattendue. Le service métier doit demander explicitement une création ou mise à jour lorsqu’il la souhaite, avec une clé qualifiée et une procédure pour les contacts historiques dépourvus de cette valeur.
Transformer la propriété unique en règle de fusion. L’unicité d’une clé de contact n’indique pas comment réunir deux fiches préexistantes, leurs activités et leurs sociétés. Une collision doit rester visible pour être instruite. La présentation du SDK HubSpot sous Symfony replace ce contrôle dans l’architecture du connecteur ; le préparateur présent isole le choix précis de l’écriture et ses propriétés.
Plan d’action : recevoir une correction avant d’ouvrir le flux suivant
Construire la recette sur les coordonnées qui changent réellement
Le référent CRM choisit une fiche de recette et vérifie sa définition de propriétés. Le responsable de l’application source explique ce qu’une valeur absente signifie dans l’export. L’intégrateur documente les deux services, modification seule et création ou modification, dans le contrat du SDK. Le runbook décrit leur reprise ; la journalisation conserve l’opération choisie sans transformer les emails et les téléphones en étiquettes de métriques exposées partout.
- Retrouver le contact, le portail concerné et la référence de personne conservée dans l’application source.
- Nommer séparément les autorisations de modification et de création avant de choisir PATCH ou upsert.
- Définir les propriétés permises et la différence entre absence, valeur inconnue et effacement explicite.
- Éprouver le changement d’email, la correspondance absente, le téléphone vide et le retour de réponse perdu.
- Qualifier la propriété unique et les contacts historiques avant d’autoriser un upsert par référence externe.
- Faire recevoir les résultats, les exceptions et la procédure de reprise par les équipes CRM et gestion.
Le critère d’ouverture porte sur des dossiers expliqués : chaque correction du périmètre rejoint une fiche identifiée, ou reste retenue avec un motif et un responsable. Les compteurs utiles sont les créations demandées par le flux de maintenance, les effacements expressément autorisés et les correspondances à requalifier. Aucun seuil universel ne remplace la décision sur les conséquences réelles d’une fiche ouverte ou d’une coordonnée perdue.
Livrer un premier périmètre que le support peut reprendre
Le budget dépend notamment des clés déjà renseignées, des imports historiques, des propriétés partagées et des automatismes déclenchés par leur modification. Une première livraison peut couvrir les coordonnées de personnes déjà rapprochées, puis ouvrir séparément les nouvelles créations. Ce découpage fournit une preuve utile sans attendre que toutes les règles d’acquisition et de fusion soient résolues.
Le runbook de rollback doit permettre de suspendre la file des corrections et de restaurer la version précédente du mapping. Il ne supprime pas une fiche déjà créée ni une action déclenchée dans une autre application. Conservez donc les demandes émises et leurs résultats qualifiés avant d’élargir le périmètre. Le support doit pouvoir isoler une correction sans rejouer l’ensemble des apports partenaires ou le dernier export complet.
Projets liés : contrôler les apports de contacts avant HubSpot
Opteven : distinguer la ligne importée du dossier à propager
Le projet Opteven de souscription connectée à HubSpot, ERP et DocuSign comprend un portail partenaires dont les fichiers suivent réception, extraction, contrôle, validation et déploiement. Les lignes conservent leurs états avant transmission des contacts qualifiés au CRM. Les échanges externes disposent aussi d’un monitoring qui rattache une anomalie à son appel.
Ce cas étaye l’intérêt d’un contrôle entre le fichier source et la propagation CRM. Il ne prouve pas que le préparateur publié ici ait été utilisé sur ce projet, ni qu’Opteven ait subi un doublon lié à un changement d’email. Le point transférable est concret : une ligne reçue et une décision d’écriture sont deux étapes distinctes, avec une trace permettant de reprendre l’échange concerné.
Relier le choix d’écriture aux contrats du connecteur HubSpot
Conserver la version du transport et la responsabilité des propriétés
L’analyse générale de l’API HubSpot et de ses générations de contrats explique le versioning daté et le maintien explicite des parcours legacy. Une migration doit réexaminer chemins, droits, propriétés et forme des entrées. Le descripteur v3 du laboratoire ne valide pas une autre version par substitution de quelques caractères dans son URL.
Le cadrage des responsabilités entre HubSpot et la gestion prolonge le choix par champ : quelle application apporte le téléphone, qui peut le corriger et comment la décision revient au support. Cette responsabilité permet de recevoir l’effacement comme une demande distincte, plutôt que de laisser la forme d’un export décider seule de la donnée conservée.
Conclusion : corriger la personne connue avec une opération assumée
Une correction de contact doit conserver son intention lorsque l’email change, lorsqu’une valeur manque et lorsqu’une réponse tarde. Choisir PATCH pour la fiche qualifiée et réserver l’upsert à une création ou mise à jour autorisée rend cette intention vérifiable. La propriété d’identification et les propriétés modifiées ne jouent pas le même rôle dans la requête.
Les 48 contrôles locaux rendent visibles ces choix, jusqu’à l’effacement expressément demandé d’un téléphone. Ils ne démontrent aucun résultat sur un portail réel. La réception reste à compléter avec le schéma CRM, les droits, les automatismes et les observations nécessaires à la reprise des demandes incertaines.
Notre accompagnement en intégration HubSpot avec vos référentiels métier aide à qualifier ces opérations et à traiter les correspondances historiques avant d’ouvrir de nouvelles créations. L’intervention vise à remettre les corrections entre les mains d’équipes qui savent expliquer la cible et les champs transmis.
Pour structurer ce passage entre application source et CRM, Dawap propose une mise en œuvre d’intégrations API sur mesure : contrat d’identité, préparation sélective des propriétés, recette des changements et procédure de reprise. Le premier lot doit permettre de corriger une personne connue sans transformer une incertitude en nouvelle fiche.
