Un contact existe dans HubSpot, l’API répond 200 et le devis part pourtant vers le mauvais compte ERP. Le risque apparaît quand le connecteur traite la première société associée comme le compte de facturation. Vérifiez d’abord le contact, la relation avec sa société et la correspondance avec le tiers ERP.
Commencez par une lecture limitée aux propriétés utiles. Vérifiez ensuite ce que chaque système peut écrire et comment reprendre une écriture dont la réponse manque. Les exemples CRM utilisent les routes REST 2026-09. L’archive montre les routes produites par la version du SDK PHP testée, avec des réponses simulées.
Pour cadrer une intégration de HubSpot à votre ERP, choisissez le premier flux, la propriété à synchroniser et la personne qui pourra résoudre un rapprochement. Appliquez ces règles aux autres échanges entre le CRM et vos applications.
Choisir entre connecteur natif, Data Sync et développement
Commencez par le flux attendu : transmettre un prospect, corriger un téléphone, qualifier une demande B2B ou restituer un statut de gestion. Consultez ensuite les objets et les règles couverts par le connecteur existant. Une synchronisation de contacts n’implique pas une prise en charge des associations typées, des archives ou des corrections après fusion.
Si le connecteur standard couvre les champs, la direction et les reprises, alors gardez-le pour ce flux. Par exemple, Data Sync peut alimenter le CRM en coordonnées, tandis qu’un traitement dédié vérifie le compte ERP qui recevra le devis. Testez les deux écritures ensemble. Si elles modifient la même propriété, désignez sa source et retirez l’écriture concurrente.
- À faire d’abord : identifier un objet témoin, sa clé source et le responsable de chaque propriété.
- À différer : l’enrichissement des champs sans usage commercial ou opérationnel défini.
- À refuser : une création automatique destinée à masquer une identité ambiguë.
Le pilier des intégrations API CRM compare les responsabilités entre logiciels. Pour une architecture où le CRM rejoint un portail ou une application interne, le cadrage CRM et application métier précise les frontières d’écriture.
Préparer Service Key, OAuth et permissions minimales
Pour les appels API d’une intégration dans un seul compte, HubSpot recommande une Service Key. Si votre flux requiert des webhooks, configurez les souscriptions dans une application HubSpot créée sur la plateforme de développement. Les applications privées historiques peuvent encore fonctionner. La création de nouvelles applications privées historiques depuis l’interface a été retirée en septembre et octobre 2026. Consulter le calendrier des accès historiques.
Pour une application qui s’installe dans plusieurs comptes, préparez le parcours OAuth, les scopes, le stockage chiffré et le renouvellement des jetons. Indexez la correspondance locale par compte HubSpot et par identifiant de connexion. Vérifiez à quelle installation appartient chaque opération avant de lire ou modifier un objet.
Pour les démonstrations de lecture des contacts, vérifiez notamment crm.objects.contacts.read. La correction demande les droits d’écriture ; les transactions et sociétés ont leurs propres scopes. Les propriétés sensibles ou certaines fonctions peuvent imposer des droits supplémentaires et un abonnement compatible. Validez les opérations retenues dans le compte cible.
Le token Bearer reste dans le gestionnaire de secrets du serveur. Il ne doit apparaître ni dans une URL, ni dans le navigateur, ni dans les logs. Le secret client d’une application, utilisé pour certaines signatures de notifications, constitue un secret distinct de la Service Key.
HubSpot API : lire les premiers contacts
Après avoir chargé la variable depuis votre gestionnaire de secrets, l’appel suivant demande seulement les propriétés nécessaires. Les guillemets doubles autour du header permettent bien au shell d’interpoler la variable. Ne l’exécutez pas dans une session qui journalise les secrets.
curl --fail-with-body --get \
'https://api.hubapi.com/crm/objects/2026-09/contacts' \
--header "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
--data-urlencode 'limit=100' \
--data-urlencode 'properties=email,firstname,lastname' \
--data-urlencode 'archived=false'
Une réponse de liste contient results et, lorsqu’une suite existe, un curseur paging.next.after. Réutilisez sa valeur avec les mêmes propriétés et filtres. Ne fabriquez pas le curseur suivant en incrémentant un identifiant. Le contrat officiel Contacts distingue lecture, correction et upsert.
Dans le compte de recette, vérifiez que la lecture contient un contact témoin et les propriétés demandées. Si l’appel renvoie 403, alors examinez les scopes et l’accès de la connexion avant de modifier le code. Le test de l’archive utilise des réponses simulées pour contrôler le parcours paginé.
Distinguer personne, entreprise, transaction et compte ERP
Le contact décrit une personne. Une company représente une organisation CRM. Le deal suit une opportunité commerciale. L’ERP peut distinguer tiers facturable, établissement de livraison, payeur et compte de gestion. Conserver ces objets séparés évite de transformer une modification de contact en changement de destinataire d’une facture.
Stockez les identifiants HubSpot comme des valeurs opaques, avec le portail et l’identifiant source vérifié. Une propriété personnalisée déclarée unique peut fournir une clé métier pour certaines opérations. Son existence, son unicité et les permissions doivent être vérifiées dans le schéma ; ajouter un nom de propriété au payload ne crée pas cette contrainte.
Pour lire la relation du contact vers sa société principale, cherchez la catégorie HUBSPOT_DEFINED et le typeId 1 sur l’ensemble des pages. Vérifiez le sens de la relation et les libellés via /crm/associations/2026-09/{fromObjectType}/{toObjectType}/labels. Rapprochez ensuite la société principale du tiers autorisé à recevoir le devis. Consulter les types d’association HubSpot.
Le parcours sélectionner la société primaire du contact collecte les pages avant de décider. Le cas fusion de contacts et identité ERP conserve les anciennes références sans fusionner automatiquement deux comptes de gestion.
Corriger une fiche existante sans créer un autre contact
Pour corriger une fiche connue, envoyez un PATCH /crm/objects/2026-09/contacts/{contactId} limité aux propriétés autorisées. Si la lecture renvoie 404, alors retenez la tâche et examinez l’archivage, une fusion, les droits et la correspondance locale avant de décider de la reprise.
{
"properties": {
"phone": "+33102030405"
}
}
Le payload demande uniquement la correction de phone. Le planificateur de l’archive traite séparément les valeurs à écrire et les champs dont l’effacement est explicitement demandé. Si le téléphone manque dans un import, conservez la valeur CRM tant qu’aucune règle d’effacement ne s’applique.
L’upsert répond à un autre contrat : il peut créer l’objet absent. HubSpot précise que l’upsert partiel des contacts n’est pas pris en charge avec l’email comme idProperty ; une propriété unique personnalisée est à étudier pour cet usage. Le parcours PATCH d’un contact existant depuis l’ERP fournit le planificateur et le prolongement avec persistance.
Paginer, limiter les appels et préparer les reprises
Conservez le portail, l’opération, les propriétés, les filtres, le curseur et la version REST dans le journal de collecte. Écrivez les observations avant d’avancer la position de reprise. Si un worker s’arrête, relisez la page incomplète et dédupliquez les observations avant de relancer leurs traitements.
Les limites dépendent de l’accès, de l’endpoint et de l’offre. Consultez les headers et les règles de l’API concernée au lieu d’appliquer un chiffre universel. Une réponse 429 impose de réduire la pression et de planifier une reprise bornée selon les indications disponibles, dont Retry-After lorsqu’il est retourné. Tous les workers ne doivent pas repartir simultanément.
Après une création dont la réponse s’est perdue, l’état est inconnu : un autre POST peut dupliquer le résultat. Le journal local conserve une réservation en attente avant le départ de la requête. Il bloque le rejeu automatique jusqu’au rapprochement ; il ne prouve pas une exécution exactement une fois côté HubSpot.
Deux signaux méritent une alerte : le nombre de recherches unitaires augmente plus vite que les contacts traités, ou des opérations en attente restent invisibles dans les tableaux du support. Le coût comprend les investigations et la réconciliation, en plus des appels HTTP et de l’hébergement.
Vérifier une signature v3 avant de stocker le webhook
Pour une livraison signée en v3, lisez X-HubSpot-Signature-v3 et X-HubSpot-Request-Timestamp. Construisez le message à partir de la méthode, de l’URL publique, du corps brut et du timestamp en millisecondes, dans cet ordre. Rejetez les timestamps datant de plus de cinq minutes. Comparez la signature avant de décoder le JSON.
La validation officielle des requêtes prévoit un décodage limité de certains caractères de l’URI, puis un HMAC SHA-256 encodé en base64. Décoder intégralement l’URL ou convertir un signe plus en espace produit un autre message. Le client secret de l’application et une comparaison en temps constant sont nécessaires.
Stocker le lot avant de confirmer la livraison
Le laboratoire fixe une tolérance locale de trente secondes pour les timestamps futurs et contrôle le compte de chaque élément. Configurez l’URL publique attendue à partir du point d’entrée connu du proxy. Si le message est valide, stockez le lot dans l’inbox avant de confirmer sa livraison.
Le numéro de tentative peut changer lors d’un nouvel envoi. Le laboratoire déduplique les livraisons à partir du contenu qualifié en excluant ce champ. Le worker doit aussi protéger l’idempotence de l’écriture métier par sa propre clé. En cas de notification tardive, relisez l’objet et vérifiez que la décision s’applique toujours avant de modifier le CRM.
Reproduire les décisions avant la recette du compte
L’archive des implémentations HubSpot contient les sources Python, le programme PHP et les instructions. Les cinquante-huit tests Python couvrent les associations paginées, les corrections, les effets en attente, les fusions, les générations de tâches, les préférences et les signatures. Trois tests exercent réellement le transport HTTP sur une boucle locale.
python3 test_integration.py
python3 demo.py
composer require hubspot/api-client:15.1.0
php sdk_lab.php
Le programme PHP exécute vingt-quatre assertions sur six requêtes simulées avec le SDK officiel. Sa version 15.1.0 utilise encore des chemins v3 pour ces opérations, notamment le type d’objet 0-3 pour les deals. Le tutoriel SDK HubSpot sous Symfony détaille les modèles et la configuration testée.
Avant production, testez les droits, les propriétés, les archives et les événements dans votre compte de recette. Inventoriez aussi les chemins émis. HubSpot annonce la fin du support des routes historiques v4 en mars 2027. L’archive utilise la v4 pour lire les préférences de communication. Validez le passage aux routes datées avec des cas de retrait et de reprise. Consulter le calendrier de support v4.
Plan d’action pour valider le premier lot
Comparer les propriétés attendues aux définitions du portail
Avant les écritures, préparez une fiche de contrat par objet : nom interne de propriété, type, valeurs admises, source responsable, transformation et droit d’effacement. Pour une liste de choix, conservez la valeur interne attendue par l’API et son libellé de lecture séparément. Une modification de traduction ne doit pas changer silencieusement la valeur envoyée par le connecteur.
Le contrat du téléphone peut être simple : l’ERP propose une chaîne qualifiée, le connecteur modifie seulement les contacts déjà rapprochés et un champ absent reste inchangé. Le responsable CRM peut choisir une autre priorité lorsqu’une correction commerciale a été validée plus récemment. Cette décision doit produire un motif de retenue consultable plutôt qu’une écriture systématique du dernier import reçu.
Pour un deal, utilisez l’identifiant interne de l’étape dans le pipeline concerné. Depuis la version 2026-09, HubSpot applique aux écritures CRM les règles de validation configurées par l’administrateur. Si la date de clôture est requise pour l’étape visée, alors un payload sans cette date peut recevoir un 400. Consignez la propriété refusée et faites corriger le dossier avant la reprise. Consulter les règles de validation des écritures.
Définir une sortie pour chaque cas qui retient une écriture
| Observation du premier lot | Décision attendue | Responsable |
|---|---|---|
| Demande qualifiée et société vérifiée | Préparer le deal avec la clé de demande | Commerce |
| Deux sociétés possibles ou mauvais compte ERP | Vérifier les deux liens avant d’écrire | CRM et ADV |
| Réponse perdue après une création | Rechercher le deal et maintenir l’attente | Support |
| Ancienne tâche après archivage | Bloquer la tâche et revoir la demande | Équipe du flux |
Dans le rapport de recette, consignez le portail, la demande et l’ID éventuellement retrouvé. Si deux sociétés apparaissent pour le même contact, indiquez les deux références et la règle qui les départage. Ce relevé permet de cadrer la reprise des écritures dans le connecteur HubSpot avec le support et l’ADV.
Dans le jeu fictif, la demande request-1 reçoit le deal 600. Le second passage retrouve ce résultat et le nombre de POST reste à un. Paradoxalement, une requête sans réponse peut aussi avoir créé le deal. Dans ce scénario, vérifiez que la demande reste en attente et que le support doit confirmer l’écriture avant de poursuivre.
Repérer les erreurs fréquentes dans un flux existant
Si les reprises créent des doublons, examinez la clé de demande utilisée à l’entrée et le résultat conservé à la sortie. Si une écriture touche le mauvais compte, vérifiez le portail, le sens de l’association et la table ERP. La journalisation doit conserver ces trois éléments pour permettre une correction ciblée.
- Rejouer une création dont la réponse a été perdue et vérifier le statut en attente dans la file du support.
- Présenter une association sans rôle primaire et vérifier que le responsable CRM peut examiner les sociétés candidates.
- Envoyer une correction après archivage et vérifier que le worker retient la tâche.
Préparer le support avant la généralisation
Le journal d’exploitation relie portail, objet source, opération, version de mapping et état de l’effet. Le support n’a pas besoin du token ni d’une copie complète des conversations. Les informations nécessaires au diagnostic doivent être accessibles selon les rôles, avec des durées de conservation et une protection adaptées aux données concernées.
Comptez les dossiers retenus par motif, leur âge et la prochaine action attendue. Une file qui diminue parce que les erreurs sont jetées ne constitue pas un progrès. Un statut visible « en attente de rapprochement » coûte moins de recherche qu’une opportunité dupliquée découverte par le commercial au moment de relancer.
Le plan de mise en service commence par les lectures et les décisions sans effet distant, puis ouvre une opération ciblée sur le segment reçu. Le repli peut suspendre les nouvelles écritures et conserver la collecte utile au diagnostic. Revenir à une version précédente du connecteur n’annule pas les effets déjà enregistrés dans HubSpot ou dans l’ERP.
Choisir le parcours métier à approfondir
Qualifier une demande issue de l’e-commerce
Le cas leads e-commerce, clients et ERP utilise une identité vérifiée côté serveur et la société primaire pour préparer une transaction. Une vue de page ne crée aucune opportunité ; une demande qualifiée possède sa propre clé durable.
Pour le premier lot, reprenez une demande qui comporte une société connue et une autre dont le compte reste ambigu. Vérifiez que le commerce retrouve la demande dans les deux cas et qu’une seule transaction est confirmée pour la demande qualifiée.
Conserver les oppositions et les décisions d’archivage
Le contrôle des consentements et préférences de contact bloque un ancien opt-in après retrait. Le parcours contact archivé et reprise invalide les anciennes tâches, même après restauration de la fiche.
Testez la file en conservant une tâche créée avant le retrait ou l’archivage. À la reprise, le worker doit vérifier l’état courant et l’autorisation associée à la tâche. Consignez le motif retenu pour que l’équipe puisse distinguer les cas d’identité et de préférence.
Relier le CRM à la gestion sans confondre les statuts
Le pilier CRM–ERP, du pipeline à la facture distingue intention commerciale et acceptation de gestion. La qualification des interfaces ERP se fait avec l’installateur concerné lorsque son intervention est nécessaire.
Lorsqu’une offre devient une commande, retrouvez les lignes du devis HubSpot accepté. Conservez la version validée par le client et comparez ses lignes avant de créer la commande dans l’ERP.
Conclusion : vérifier l’identité et la reprise avant d’étendre les flux
Une intégration HubSpot commence par une opération limitée dont le résultat est explicable. Les clés et les associations déterminent la fiche cible ; les responsabilités par propriété déterminent ce que le connecteur peut réellement écrire.
La recette doit couvrir la réponse perdue, la fusion, l’archivage et le retrait d’une préférence. Ces événements changent l’autorisation de reprendre une tâche, même lorsqu’un appel nominal semblait correct au départ.
Pour cadrer une intégration HubSpot dans votre système d’information, Dawap peut vous aider à choisir la première opération, à vérifier ses droits et à tester les reprises avec les équipes CRM, gestion et support.