---
title: "Connecteur HubSpot"
description: "Guide complet d'intégration du CRM HubSpot pour synchroniser contacts, entreprises, transactions, tickets et données marketing avec Brevo via Tajo."
url: https://tajo.io/fr/docs/connectors/crm/hubspot/
markdown: https://tajo.io/fr/docs/connectors/crm/hubspot.md
lang: fr-FR
robots: noindex
---

Demandez un accès anticipé

Indiquez votre prénom et votre adresse e-mail professionnelle. Nous vous enverrons un lien pour confirmer votre demande d’accès à Tajo.

# Connecteur HubSpot

Statut du connecteur: En cours En construction. Pas encore vérifié.

| Champ source | Champ de destination | Valeur d’exemple |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Connectez votre CRM HubSpot à Brevo via Tajo pour bénéficier d’une synchronisation bidirectionnelle des contacts, d’un suivi des transactions, des données d’engagement et d’une automatisation marketing unifiée sur les deux plateformes.

## Vue d’ensemble

| Propriété | Valeur |
| --- | --- |
| **Plateforme** | HubSpot |
| **Catégorie** | CRM |
| **Complexité d’installation** | Moyenne |
| **Intégration officielle** | Non |
| **Données synchronisées** | Contacts, entreprises, transactions, tickets, événements |
| **URL de base de l’API** | `https://api.hubapi.com` |

## Fonctionnalités

- **Synchronisation bidirectionnelle des contacts**, Gardez les contacts synchronisés entre HubSpot et Brevo en temps réel
- **Suivi du pipeline de transactions**, Synchronisez les étapes et les montants des transactions pour une segmentation basée sur le chiffre d’affaires
- **Synchronisation des données d’entreprise**, Associez les contacts à des fiches entreprise et à des données firmographiques
- **Intégration des tickets**, Suivez les tickets de support pour évaluer la santé client
- **Suivi de l’engagement**, Synchronisez ouvertures d’e-mails, clics, réunions, appels et notes
- **Prise en charge des objets personnalisés**, Mappez les objets personnalisés HubSpot vers des attributs Brevo
- **Déclencheurs de workflow**, Utilisez les changements d’étape de cycle de vie HubSpot pour déclencher des automatisations Brevo
- **Événements webhook**, Notifications en temps réel lors des changements de données CRM

## Prérequis

Avant de commencer, assurez-vous de disposer de :

1. Un compte HubSpot (Free, Starter, Professional ou Enterprise)
2. Une application privée HubSpot ou une application OAuth avec les scopes requis
3. Un compte Brevo avec accès API
4. Un compte Tajo

## Authentification

### Jeton d’accès d’application privée (recommandé)

Créez une application privée dans HubSpot pour un accès API direct avec un contrôle granulaire des scopes.

1. Accédez à HubSpot Settings > Integrations > Private Apps
2. Créez une nouvelle application privée
3. Configurez les scopes requis
4. Copiez le jeton d’accès

```bash
curl -X GET "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

### OAuth 2.0

Utilisez OAuth 2.0 pour les intégrations multi-comptes nécessitant une autorisation utilisateur.

```bash
# Authorization URL
https://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}
```

#### Scopes requis

```
crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.custom.read
crm.schemas.custom.read
```

## Configuration

### Configuration de base

```yaml
connectors:
  hubspot:
    enabled: true
    access_token: "${HUBSPOT_ACCESS_TOKEN}"

    # Data sync options
    sync:
      contacts: true
      companies: true
      deals: true
      tickets: true
      engagements: true

    # Sync direction
    direction: bidirectional  # or 'hubspot_to_brevo' | 'brevo_to_hubspot'

    # List assignment in Brevo
    lists:
      all_contacts: 10
      qualified_leads: 11
      customers: 12
```

### Mappage des champs

Mappez les propriétés HubSpot vers les attributs de contact Brevo :

#### Mappages par défaut

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | E-mail du contact (identifiant principal) |
| `firstname` optional | string | Mappé vers l'attribut FIRSTNAME dans Brevo |
| `lastname` optional | string | Mappé vers l'attribut LASTNAME dans Brevo |
| `phone` optional | string | Mappé vers l'attribut SMS pour WhatsApp/SMS |
| `company` optional | string | Nom de l'entreprise associée |
| `lifecyclestage` optional | string | Étape du cycle de vie HubSpot (subscriber, lead, MQL, SQL, customer) |
| `hs_lead_status` optional | string | Statut de qualification du prospect |
| `hubspot_owner_id` optional | string | ID du commercial assigné |

#### Mappage des propriétés personnalisées

```yaml
field_mapping:
  # Standard fields
  email: email
  firstname: FIRSTNAME
  lastname: LASTNAME
  phone: SMS

  # CRM fields
  lifecyclestage: LIFECYCLE_STAGE
  hs_lead_status: LEAD_STATUS
  company: COMPANY_NAME

  # Deal metrics
  hs_total_deal_value: DEAL_VALUE
  num_associated_deals: DEAL_COUNT

  # Custom properties
  preferred_channel: PREFERRED_CHANNEL
  customer_segment: SEGMENT
```

## Endpoints API

### Objets CRM

| Méthode | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/contacts` | Lister les contacts |
| `POST` | `/crm/v3/objects/contacts` | Créer un contact |
| `PATCH` | `/crm/v3/objects/contacts/{id}` | Mettre à jour un contact |
| `GET` | `/crm/v3/objects/companies` | Lister les entreprises |
| `GET` | `/crm/v3/objects/deals` | Lister les transactions |
| `POST` | `/crm/v3/objects/deals` | Créer une transaction |
| `GET` | `/crm/v3/objects/tickets` | Lister les tickets |

### Associations

| Méthode | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}` | Obtenir les associations |
| `PUT` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}` | Créer une association |

### Engagements

| Méthode | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/calls` | Lister les engagements d’appel |
| `GET` | `/crm/v3/objects/emails` | Lister les engagements e-mail |
| `GET` | `/crm/v3/objects/meetings` | Lister les réunions |
| `GET` | `/crm/v3/objects/notes` | Lister les notes |
| `GET` | `/crm/v3/objects/tasks` | Lister les tâches |

## Événements

### Événements de contact

| Événement | Déclencheur | Cas d’usage |
| --- | --- | --- |
| `contact.creation` | Nouveau contact créé | Déclencheur de workflow de bienvenue |
| `contact.propertyChange` | Propriété de contact mise à jour | Synchronisation des attributs |
| `contact.merge` | Contacts fusionnés | Gestion des doublons |
| `contact.deletion` | Contact supprimé | Nettoyage dans Brevo |

### Événements de transaction

| Événement | Déclencheur | Cas d’usage |
| --- | --- | --- |
| `deal.creation` | Nouvelle transaction créée | Notification commerciale |
| `deal.propertyChange` | Étape de transaction modifiée | Automatisation du pipeline |
| `deal.deletion` | Transaction supprimée | Reporting des revenus |

### Événements d’entreprise

| Événement | Déclencheur | Cas d’usage |
| --- | --- | --- |
| `company.creation` | Nouvelle entreprise ajoutée | Marketing basé sur les comptes |
| `company.propertyChange` | Données d’entreprise mises à jour | Synchronisation firmographique |

## Exemples de code

### Initialiser le connecteur

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect HubSpot
await tajo.connectors.connect('hubspot', {
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});
```

### Lancer une synchronisation des contacts

```javascript
// Full bidirectional sync
await tajo.connectors.sync('hubspot', {
  type: 'full',
  resources: ['contacts', 'companies', 'deals'],
  direction: 'bidirectional',
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('hubspot');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 34200,
//   companiesSynced: 5100,
//   dealsSynced: 2340
// }
```

### Gérer les événements webhook

```javascript
// Handle HubSpot webhook notifications
app.post('/webhooks/hubspot', async (req, res) => {
  const signature = req.get('X-HubSpot-Signature-v3');

  // Verify webhook signature
  if (!verifyHubSpotSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  for (const event of req.body) {
    await tajo.connectors.handleWebhook('hubspot', {
      eventType: event.subscriptionType,
      objectId: event.objectId,
      propertyName: event.propertyName,
      propertyValue: event.propertyValue
    });
  }

  res.status(200).send('OK');
});
```

## Limites de débit

HubSpot applique des limites de débit par application privée ou par application OAuth :

| Plan | Limite de débit | Limite en rafale |
| --- | --- | --- |
| Free/Starter | 100 requêtes/10 secondes | 150 requêtes/10 secondes |
| Professional | 150 requêtes/10 secondes | 200 requêtes/10 secondes |
| Enterprise | 200 requêtes/10 secondes | 250 requêtes/10 secondes |
| Add-on API | 200 requêtes/10 secondes | 250 requêtes/10 secondes |

Limites supplémentaires :

- **API de recherche** : 5 requêtes/seconde par application
- **Opérations par lot** : 100 enregistrements par requête batch
- **Limite quotidienne** : 500 000 requêtes/jour (applications OAuth)

Gestion des limites de débit

HubSpot renvoie une réponse `429 Too Many Requests` lorsque les limites sont dépassées. Utilisez un backoff exponentiel et surveillez les en-têtes `X-HubSpot-RateLimit-*`.

## Dépannage

### Problèmes courants

| Problème | Cause | Solution |
| --- | --- | --- |
| 401 Unauthorized | Jeton expiré ou invalide | Régénérez le jeton d’application privée ou rafraîchissez le jeton OAuth |
| Contact non synchronisé | Propriété e-mail manquante | Les contacts HubSpot nécessitent un e-mail pour la synchronisation Brevo |
| Contacts dupliqués | Aucune règle de déduplication | Configurez les règles de fusion dans HubSpot |
| Webhook non reçu | Abonnement inactif | Réenregistrez les abonnements webhook |
| Propriété non mappée | Propriété personnalisée non créée | Créez d’abord la propriété dans HubSpot |

### Mode débogage

Activez la journalisation détaillée :

```yaml
connectors:
  hubspot:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### Tester la connexion

```bash
tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies readable
# ✓ Deals readable
# ✓ Webhooks registered
```

## Bonnes pratiques

1. **Privilégiez les applications privées aux clés API**, Les clés API sont dépréciées ; utilisez des applications privées pour une meilleure sécurité
2. **Implémentez la synchronisation bidirectionnelle avec précaution**, Évitez les boucles infinies en traçant la source de synchronisation
3. **Mappez les étapes du cycle de vie**, Utilisez les étapes de cycle de vie HubSpot pour segmenter les contacts dans Brevo
4. **Regroupez les requêtes API**, Utilisez les endpoints batch pour les opérations en masse et rester dans les limites de débit
5. **Surveillez la livraison des webhooks**, Mettez en place une logique de nouvelle tentative et un traitement des messages morts
6. **Utilisez la synchronisation incrémentale**, Synchronisez uniquement les enregistrements modifiés en utilisant la propriété `lastmodifieddate`

## Sécurité

- **Jetons d’application privée**, Jetons d’accès avec scopes et permissions granulaires
- **OAuth 2.0**, Autorisation conforme aux standards de l’industrie avec rotation des refresh tokens
- **Signatures de webhook**, Vérification de signature basée sur HMAC (v3)
- **Chiffrement TLS**, Toutes les communications API sont chiffrées en transit
- **Permissions délimitées**, Accès minimum requis par intégration

## Ressources associées

- [Documentation de l’API HubSpot](https://developers.hubspot.com/docs/api/overview)
- [Guide d’authentification HubSpot](https://developers.hubspot.com/docs/api/working-with-oauth)
- [Connecteur Salesforce](https://tajo.io/fr/docs/connectors/crm/salesforce)
- [Skill Customer Sync](https://tajo.io/fr/docs/skills/data-sync/customer-sync)
- [API Contacts Brevo](https://tajo.io/fr/docs/contact-management)