API HubSpot

Configurer et utiliser l'intégration HubSpot

Connecte Oniva à HubSpot et gère tes contacts, inscriptions et données de participation directement dans ton CRM – sans étapes intermédiaires manuelles.

L'intégration HubSpot connecte ton compte HubSpot de manière bidirectionnelle avec Oniva :

• Import : Tu importes des contacts depuis une liste HubSpot directement dans ton événement.
• Export via Événements marketing : Oniva crée automatiquement tes événements avec le statut des contacts dans HubSpot et transfère les nouveaux contacts.
• Export via Objet personnalisé : Oniva transfère les liens d'événement personnels sous forme de fiches d'informations d'objets personnalisés vers HubSpot, p. ex. pour les utiliser dans des e-mails ou des workflows HubSpot.

Prérequis

• Le module payant « HubSpot API » d'Oniva doit être activé pour ton compte. Contacte le support Oniva ou ton chargé·e de compte pour l'activation.
• La création d'une application privée dans HubSpot requiert des droits de l'admin de l'entité.
• L'export de liens d'événement personnels via les objets personnalisés nécessite un abonnement HubSpot Enterprise, car les objets personnalisés ne sont disponibles que dans les comptes Enterprise. L'import et l'export via événements marketing fonctionnent également avec des abonnements inférieurs, pour autant que les applications privées y soient disponibles.

‍

Étape 1 : Créer un access jeton dans HubSpot

1. Clique sur l'icône d'engrenage (Paramètres) dans la barre de navigation supérieure.
2. Dans la barre latérale gauche, navigue vers Intégrations → Applications privées.
3. Clique sur une application existante ou crée-en une nouvelle. Donne un nom explicite à l'application (p. ex. « Oniva Integration »).
   ⚠️ Remarque : Dans HubSpot, les applications privées peuvent parfois être affichées sous le nom « Applications héritées » ou « Legacy App ». Elles peuvent néanmoins être utilisées pour l'intégration avec Oniva.
4. Passe à l'onglet « Domaines » et active les autorisations correspondant à ton cas d'utilisation (voir tableau ci-dessous).
5. Enregistre l'application et passe à l'onglet « Authentification ».
6. Clique sur « Afficher le jeton », puis sur « Copier ».
7. Colle l'access jeton (= token) dans Oniva sous Connexions d'applications (voir étape 2).

Domaines requis

Active au minimum les domaines correspondant aux fonctionnalités que tu utilises. N'active que les autorisations dont tu as réellement besoin.

Pour l'import de contacts depuis HubSpot vers Oniva :

• crm.lists.read
• crm.schemas.contacts.read
• crm.objects.contacts.read

En plus pour l'export des données d'événements depuis Oniva (Événements marketing) :

• crm.objects.contacts.write
• crm.objects.marketing_events.read
• crm.objects.marketing_events.write

En plus pour l'export de liens d'événement personnels (objet personnalisé, HubSpot Enterprise uniquement) :

• crm.schemas.custom.read
• crm.schemas.custom.write
• crm.objects.custom.read
• crm.objects.custom.write

👉 Remarque : Les domaines manquants peuvent être ajoutés à tout moment dans l'application existante, sans qu'il soit nécessaire d'en créer une nouvelle.

Jeton statique ou rotatif

Pour une connexion stable et sans interruption, nous recommandons un jetonstatique. Il n'expire pas et ne doit pas être renouvelé. Si tu utilises un jeton rotatif pour des raisons de sécurité, pense à mettre à jour le jeton dans Oniva immédiatement après chaque rotation – sans quoi la connexion sera interrompue.

‍

Étape 2 : Connecter HubSpot dans Oniva

1. Navigue vers la vue d'ensemble du compte dans Oniva et sélectionne « Connexions d'applications ».
2. Sélectionne HubSpot dans la liste et colle l'access jeton copié.
3. Définis si HubSpot doit être utilisé uniquement pour l'import de contacts ou également pour l'export de données d'événements. Deux fonctions d'export sont disponibles et peuvent être activées individuellement :
   • Synchronisation événements marketing – Crée de nouveaux événements avec le statut des contacts dans HubSpot et transfère les nouveaux contacts vers HubSpot.
   • Objet personnalisé – Permet le transfert de liens d'événement personnels vers HubSpot.
4. Confirme la connexion.

⚠️ Important : Les fonctions sélectionnées ici doivent être couvertes par les scopes correspondants de ton access token (voir étape 1). Si tu actives les objets personnalisés sans avoir accordé les scopes correspondants, le transfert échouera.

‍

Étape 3 : Activer la connexion au niveau du workspace et de l'événement

La connexion doit également être activée au niveau du workspace et de l'événement.

1. Ouvre les paramètres du workspace souhaité et va dans « Connexion d'application » → « Activer ».
2. Ouvre l'événement souhaité et fais de même : « Connexion d'application » → « Activer ».

Une fois activés, les contacts HubSpot seront disponibles pour l'import de contacts dans l'événement. Si la synchronisation événements marketing a également été activée, les données d'événement seront automatiquement transmises à HubSpot à partir de ce moment.

‍

Import : importer des contacts HubSpot dans un événement

Une fois la connexion d'application activée au niveau de l'événement, tu peux importer des contacts depuis une liste HubSpot directement.

1. Navigue dans le tableau de bord de l'événement vers « Contacts ».
2. Sélectionne « Importer des contacts ».
3. Choisis la liste HubSpot souhaitée (voir les segments dans HubSpot).
4. Sélectionne « Créer de nouveaux contacts » comme mode d'import.
5. Associe les champs HubSpot aux champs correspondants dans Oniva.
6. Clique sur « Importer des contacts » pour finaliser l'import.

Synchroniser les contacts ajoutés ultérieurement

Les contacts HubSpot ne sont pas automatiquement mis à jour dans Oniva. Si de nouveaux contacts ont été ajoutés à la liste HubSpot en cours d'événement, ou si des contacts existants ont été modifiés, l'import doit être répété manuellement.

1. Navigue dans le tableau de bord de l'événement vers « Contacts ».
2. Sélectionne « Importer des contacts ».
3. Choisis la liste HubSpot souhaitée (voir les segments dans HubSpot).
4. Sélectionne « Ajouter de nouveaux contacts ou mettre à jour les contacts existants » comme mode d'import.
5. Associe les champs HubSpot aux champs correspondants dans Oniva.
6. Clique sur « Importer des contacts » pour finaliser la synchronisation.

👉 Remarque : Cette opération peut être répétée à tout moment sans dupliquer les contacts existants. Les contacts déjà présents seront mis à jour ; les nouveaux contacts seront ajoutés.

‍

Import : créer des contacts HubSpot comme comptes dans Oniva

En plus de l'import de contacts au niveau de l'événement, tu peux également créer des contacts HubSpot comme comptes (comptes utilisateur·trice·s) dans Oniva. Cela permet de donner accès à Oniva à des personnes.

1. Sélectionne « Comptes » via l'icône d'engrenage.
2. Sélectionne « Importer des comptes ».
3. Sélectionne HubSpot comme source.
4. Choisis la liste HubSpot souhaitée (voir les segments dans HubSpot).
5. Sélectionne le type de compte si plusieurs sont disponibles (p. ex. SSO).
6. Sélectionne « Ajouter de nouveaux comptes ou mettre à jour les comptes existants ».
7. Associe les champs HubSpot aux champs correspondants dans Oniva.
8. Sélectionne « Lancer l'import ».

Une fois l'import effectué, les comptes sont disponibles dans Oniva. Avec « Tout sélectionner » et l'action « Activer les comptes », tous les utilisateur·trice·s reçoivent un e-mail d'activation pour créer leur compte.

‍

Export : transférer les données d'événements vers HubSpot via événements marketing

Si la synchronisation événements marketing est activée (étape 2) et la connexion d'application est activée au niveau du workspace et de l'événement (étape 3), Oniva transfère automatiquement les données d'événements vers HubSpot. Aucun export manuel n'est nécessaire.

Qu'est-ce qui est transféré ?

• Pour chaque événement Oniva, exactement un événements marketing est créé dans HubSpot (relation 1:1).
• Le statut de participation (p. ex. inscrit·e, confirmé·e, annulé·e, présent·e) est enregistré sur le événements marketing pour chaque participant·e.
• Les contacts qui n'existent pas encore dans HubSpot sont créés comme nouveaux contacts.

Quand le transfert a-t-il lieu ?

Le transfert s'effectue automatiquement dès qu'une réservation est créée dans Oniva ou que le statut d'un·e participant·e change. Contrairement à l'import (manuel), la synchronisation événements marketing est un processus continu, déclenché par des événements.

Comment vérifier le résultat dans HubSpot

1. Ouvre dans HubSpot le menu Marketing → Événements marketing.
2. Recherche l'événement par nom et ouvre la fiche d'informations.
3. Sous les contacts associés, tu verras les participant·e·s transféré·e·s avec leur statut.

💡 Astuce : personnaliser la vue HubSpot
‍Pour une vue plus claire des participations aux événements, il est recommandé d’afficher les événements marketing sous forme de carte sur la partie droite de la fiche contact.
La vue par défaut peut être personnalisée dans HubSpot via Paramètres (icône engrenage en haut à droite) → Gestion des données → Objets → Personnalisation des fiches d'informations. Il est possible d’y configurer la fiche contact afin d’afficher les événements marketing sous forme de carte.

‍

Export : transférer les liens d'événement personnels via objet personnalisé

Les liens d'événement personnels (liens de participation individuels par contact) sont transférés via un objet personnalisé HubSpot. Ils peuvent ainsi être réutilisés dans HubSpot, par exemple comme lien personnalisé dans des e-mails marketing ou comme déclencheur dans des workflows.

Prérequis

• Abonnement HubSpot Enterprise (les objets personnalisés ne sont disponibles que dans les comptes Enterprise)
• Scopes d'objets personnalisés dans l'access token (voir étape 1)
• Fonction objet personnalisé activée dans la connexion d'application Oniva (étape 2)

Déroulement

• S’assurer que les conditions préalables mentionnées ci-dessus sont remplies.
• Dès qu'une réservation est créée dans un événement, Oniva la transfère sous forme d'enregistrement de l'objet personnalisé vers HubSpot et la relie au contact correspondant. Seul le lien personnel est transféré – aucun autre champ.
• Dans HubSpot, les enregistrements transférés se trouvent sous Contacts → Objets personnalisés ou directement sur la fiche contact dans les objets associés.

💡 Astuce : Grâce au lien personnel associé, il est possible de créer dans HubSpot des e-mails avec des appels à l’action personnalisés ou de mettre en place des workflows basés sur le statut de participation.

Où est-ce que je trouve le lien personnel dans HubSpot ?

Pour le transfert des liens personnels, Oniva crée dans HubSpot des objets personnalisés appelés « Oniva Participant ». Cet objet est créé dès qu'une réservation est effectuée. Cela permet par exemple de déclencher des confirmations de réservation via des e-mails automatisés depuis HubSpot, ou de déclencher d'autres workflows. Merci de noter qu'actuellement, seuls les e-mails marketing automatisés (par exemple déclenchés par un workflow) sont pris en charge par HubSpot.

‍

Résolution des problèmes

La connexion échoue

Assure-toi que ton access token inclut les scopes requis pour ton cas d'utilisation (voir étape 1). Tu peux les vérifier et les compléter dans HubSpot sous Paramètres → Intégrations → Applications privées → ton application → Scopes.

HubSpot n'est pas disponible comme source d'import

Assure-toi que la connexion d'application est activée à la fois au niveau du workspace et de l'événement (étape 3).

HubSpot n'apparaît pas comme source dans l'import de comptes

L'import de comptes utilise la même connexion HubSpot que l'import de contacts. Assure-toi que HubSpot est connecté au niveau du compte avec un access token valide (étape 2) et que le token inclut les scopes de lecture crm.lists.read, crm.objects.contacts.read et crm.schemas.contacts.read.

Les données d'événements ne sont pas transférées vers HubSpot

Vérifie si la synchronisation événements marketing est activée dans la connexion d'application (étape 2) et si l'access token inclut les scopes crm.objects.marketing_events.read, crm.objects.marketing_events.write et crm.objects.contacts.write. Le transfert ne s'effectue qu'à partir d'une nouvelle réservation ou d'un changement de statut – les participant·e·s enregistré·e·s avant l'activation ne sont pas transféré·e·s rétroactivement.

Les liens d'événement personnels n'apparaissent pas dans HubSpot

Les objets personnalisés nécessitent un abonnement HubSpot Enterprise. Vérifie également si la fonction objet personnalisé est activée et si le token inclut les scopes d'objets personnalisés (crm.schemas.custom.*, crm.objects.custom.*).

La connexion fonctionnait mais s'est soudainement interrompue

Si tu utilises un token rotatif, il a probablement été renouvelé. Mets à jour le token dans Oniva sous Connexions d'applications. Pour une connexion sans interruption, nous recommandons un token statique.