Connecter HubSpot

HubSpot a retiré ses clés d’API classiques en 2022. La façon moderne d’accorder à une application tierce l’accès à vos données HubSpot est une application privée : vous créez l’application dans votre propre compte, cochez exactement les portées qu’elle peut utiliser, et HubSpot délivre un jeton d’accès de longue durée à coller dans Anexus.

HubSpot organise vos données en quatre objets CRM — Contacts, Entreprises, Transactions et Tickets. Cette intégration ne demande que les portées Contact : le jeton qu’elle nous transmet ne peut donc physiquement ni lire ni écrire vos transactions ou vos tickets.

Qui peut créer le jeton, et dans quel compte

• Les applications privées sont une fonction réservée aux super administrateurs dans HubSpot. Un utilisateur standard — même s’il peut modifier tous les contacts — ne verra pas le menu. Si vous n’êtes pas super administrateur, demandez au responsable du compte d’effectuer l’étape 1 et de vous transmettre le jeton.
• Fonctionne avec tous les abonnements HubSpot, y compris le CRM gratuit. Les applications privées ne sont pas une fonction payante.
• Un jeton est lié au seul compte qui l’a créé. Il ne peut pas être déplacé vers un autre compte HubSpot, et un jeton créé dans un environnement de test n’écrira jamais ailleurs que dans cet environnement.

Vérifiez d’abord votre Hub ID

Si vous avez déjà été ajouté à un compte client, un compte partenaire ou un environnement de test, vous possédez probablement plus d’un compte HubSpot. Votre Hub ID est le numéro visible dans la barre d’adresse — app.hubspot.com/contacts/12345678/… — et il figure aussi dans le menu du compte en haut à droite. Notez-le avant de commencer : si les contacts semblent ensuite n’arriver « nulle part », ils se trouvent presque toujours tranquillement dans un autre Hub ID.

Créer l’application privée et copier son jeton d’accès

Ce que le préfixe du jeton vous apprend

Un jeton d’application privée HubSpot commence par pat-, suivi de la région où votre compte est hébergé — pat-na1-… pour l’Amérique du Nord, pat-eu1-… pour le centre de données de l’UE — puis d’un long identifiant. Si ce que vous avez collé ne comporte pas le préfixe pat-, vous avez copié la mauvaise chaîne : l’identifiant de l’application et le secret client se trouvent sur le même écran et sont faciles à prendre par erreur.

Le connecter dans Anexus

Correspondance entre un contact Anexus et les propriétés HubSpot

Chaque contact capté via votre formulaire d’échange devient — ou met à jour — une fiche de l’objet Contact de HubSpot. HubSpot attribue à chaque propriété un libellé lisible et un nom interne en minuscules ; c’est le nom interne que vous recherchez lorsque vous créez une liste ou un filtre de workflow.

Le courriel est le pivot de tout le flux. Comme HubSpot déduplique les contacts sur l’adresse de courriel, nous recherchons la personne avant d’écrire : une fiche existante est mise à jour sur place, sinon une nouvelle est créée. Une personne qui tapote votre carte deux fois avec la même adresse ne deviendra jamais deux contacts.

Le message du formulaire d’échange et la note indiquant comment le contact a été capté (tapotement NFC, lecture QR, Apple Wallet, lien partagé) accompagnent également chaque contact — consultez Connecter un CRM pour la liste complète de ce qu’Anexus envoie.

Nom de l’entreprise et objet Entreprise

C’est la source numéro un des tickets « l’entreprise est incorrecte » sur HubSpot. company est une simple propriété texte située sur le contact. C’est autre chose que l’objet Entreprise — la fiche distincte, avec son propre domaine, son secteur d’activité et ses contacts associés.

HubSpot dispose d’un réglage global : Paramètres → Objets → Entreprises → « Créer et associer automatiquement des entreprises aux contacts ». Lorsqu’il est activé, HubSpot ignore le nom d’entreprise saisi et construit plutôt l’association à partir du domaine du courriel. Un prospect qui écrit « Acme Manufacturing » mais fournit une adresse @acme-mfg.ca sera donc associé à l’entreprise que HubSpot possède déjà pour ce domaine — et un prospect utilisant un fournisseur gratuit comme Gmail ou Outlook n’obtiendra aucune entreprise, car HubSpot exclut délibérément les domaines de courriel gratuits.

Rien n’est cassé lorsque cela se produit : le nom saisi reste sur le contact, dans la propriété company. Si vous voulez que les deux concordent, désactivez le réglage d’association automatique, ou construisez vos vues sur company plutôt que sur l’entreprise associée.

Statut du lead, étape du cycle de vie et contacts marketing

Les nouveaux contacts arrivent avec hs_lead_status défini à NEW : ils tombent donc directement dans le filtre standard « Nouveau » du statut du lead, et vous pouvez traiter la file d’attente depuis le haut.

Le statut du lead n’est pas l’étape du cycle de vie. HubSpot propose deux listes déroulantes aux noms voisins : hs_lead_status (Nouveau, Ouvert, En cours, Non qualifié…) est celle que cette intégration écrit, tandis que lifecyclestage (Abonné, Prospect, MQL, SQL, Client…) est la propriété d’entonnoir sur laquelle reposent la plupart des tableaux de bord et des listes. Si votre vue enregistrée filtre sur l’étape du cycle de vie, des personnes tout juste synchronisées peuvent être présentes dans HubSpot et rester invisibles dans cette vue. À retenir également : HubSpot ne fait pas reculer une étape du cycle de vie de lui-même ; une personne déjà Client reste Client, même si elle tapote votre carte comme un nouveau prospect.

Une dernière particularité propre à HubSpot : si votre compte utilise le modèle des contacts marketing de Marketing Hub, les contacts créés via l’API sont normalement créés comme contacts non marketing. Ils sont parfaitement visibles et exploitables par les ventes, mais vous ne pouvez pas les inclure dans un courriel marketing tant qu’ils ne sont pas convertis en contacts marketing — manuellement, ou à l’aide d’un workflow qui s’en charge.

Récupérer les contacts déjà captés

Pour récupérer les contacts saisis avant la connexion, cliquez sur Synchroniser les contacts passés sur la carte HubSpot. Nous les envoyons par lots de 50 avec une barre de progression en direct.

HubSpot applique deux limites de requêtes, qui ne fonctionnent pas de la même façon. La limite de rafale est comptée par application sur une fenêtre glissante de dix secondes — 100 requêtes sur les offres Free et Starter, 190 sur Professional et Enterprise : c’est donc le trafic de cette intégration seule qui est compté, et non celui de tout ce qui est installé sur votre compte. La limite quotidienne, elle, est partagée par toutes les applications du compte, et son ampleur dépend de votre abonnement. Si une synchronisation volumineuse atteint l’une ou l’autre, HubSpot répond par une erreur 429 et les contacts refusés restent en attente ; cliquez de nouveau sur Synchroniser les contacts passés un peu plus tard pour les envoyer.

Résoudre les erreurs réellement renvoyées par HubSpot

Lorsqu’une synchronisation échoue, la carte HubSpot affiche le motif que HubSpot nous a transmis. Voici ceux que vous êtes susceptible de rencontrer.

401 — identifiants d’authentification introuvables

HubSpot ne reconnaît pas du tout le jeton. Soit il a été tronqué en chemin (vérifiez qu’il commence toujours par pat- et qu’il n’a pas été rogné par un gestionnaire de mots de passe), soit l’application privée a été supprimée ou son jeton renouvelé dans HubSpot. Ouvrez Paramètres → Intégrations → Applications privées, vérifiez que « Anexus Connect » figure toujours dans la liste, recopiez le jeton depuis l’onglet Auth et reconnectez-vous dans Anexus.

403 — l’application n’a pas reçu les portées requises

Le jeton est valide, mais il manque crm.objects.contacts.read ou crm.objects.contacts.write dans sa liste de portées. Les portées appartiennent à l’application, pas au jeton : la correction se fait donc dans HubSpot et non dans Anexus. Ouvrez l’application privée Anexus Connect, allez à l’onglet Portées, cochez la portée manquante et validez la modification. Recopiez ensuite le jeton d’accès depuis l’onglet Auth et reconnectez-vous. L’erreur classique est de cocher la lecture et d’oublier l’écriture.

409 CONFLICT — « Le contact existe déjà »

HubSpot refuse de créer un second contact portant une adresse de courriel qu’il possède déjà, et renvoie utilement l’identifiant de la fiche existante dans le message. Comme nous recherchons d’abord la personne, vous ne devriez normalement pas voir cette erreur. Lorsqu’elle apparaît, c’est que l’adresse a été ajoutée à HubSpot par autre chose au même instant — une soumission de formulaire, un import, une autre intégration — et la nouvelle tentative se contentera de mettre à jour cette fiche.

400 — « Les valeurs de propriété ne sont pas valides »

Presque toujours hs_lead_status. Le statut du lead est une énumération, et HubSpot n’accepte que les valeurs internes définies dans sa liste d’options. Les comptes qui ont personnalisé leur pipeline de leads suppriment ou renomment parfois l’option NEW — dès lors, chaque synchronisation échoue à la validation. Corrigez cela dans Paramètres → Propriétés : ouvrez Statut du lead et assurez-vous qu’une option ayant la valeur interne NEW existe toujours. Vous pouvez lui donner le libellé que vous voulez ; c’est la valeur interne qui doit correspondre.

429 — le compte a atteint sa limite de débit

Ce n’est pas un problème de configuration : HubSpot nous demande de ralentir. La limite de rafale à l’origine de la plupart des 429 est comptée par application ; il s’agit donc normalement de notre propre trafic pendant une grosse synchronisation, et non d’une autre intégration qui prendrait toute la place. C’est la limite quotidienne, elle, que vos autres applications partagent. Le contact reste en attente et le prochain clic sur Synchroniser les contacts passés le reprendra. Si des 429 apparaissent en permanence sur les captures quotidiennes ordinaires, et non pendant une synchronisation massive, contactez le soutien technique.

La synchronisation a réussi mais vous ne trouvez pas le contact

Procédez dans cet ordre. Cliquez sur Tester sur la carte HubSpot pour confirmer que le jeton est toujours actif. Comparez ensuite le nom du compte affiché sur la carte avec le Hub ID que vous aviez noté — un jeton créé dans un environnement de test n’écrit que dans cet environnement. Recherchez ensuite la personne par courriel avec la recherche globale de HubSpot plutôt qu’en faisant défiler une liste : une vue enregistrée n’affiche que les fiches correspondant à ses filtres, de sorte qu’un nouveau contact peut se trouver dans HubSpot tout en étant absent de la vue que vous consultez.

Des doublons apparaissent malgré tout

Deux fiches pour une même personne signifient presque toujours deux adresses de courriel — l’adresse professionnelle le lundi, l’adresse personnelle au salon le vendredi. HubSpot les traite volontairement comme deux contacts distincts, et nous aussi. Sur les abonnements Professional et Enterprise, l’outil Qualité des données → Gérer les doublons de HubSpot proposera des fusions pour les fiches qui semblent correspondre à la même personne. Sur les offres Free et Starter, cet outil n’est pas disponible, mais vous pouvez tout de même fusionner deux fiches à la main depuis le menu Actions d’une fiche de contact. Dans les deux cas, la fusion est sans risque, et les synchronisations futures sur l’une ou l’autre adresse aboutiront sur la fiche conservée.

Désactiver la connexion

Cliquez sur Déconnecter sur la carte HubSpot. Nous arrêtons immédiatement d’envoyer de nouveaux contacts. Pour révoquer également le jeton du côté de HubSpot — ce qu’il faut faire dès que la personne qui l’a créé quitte l’entreprise — retournez à Paramètres → Intégrations → Applications privées dans HubSpot, ouvrez l’application Anexus Connect et cliquez sur Supprimer. La suppression de l’application annule son jeton immédiatement et définitivement ; il n’y a pas de retour en arrière, et une nouvelle application signifie un nouveau jeton à coller.

Les contacts déjà écrits restent dans HubSpot tels quels. Se déconnecter n’est pas supprimer.

Et ensuite

• Retour à toutes les intégrations CRM
• Gérer les contacts dans Anexus