Connecteur HubSpot

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

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

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.

# 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

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 :

Mappage des propriétés personnalisées

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

Associations

Engagements

Événements

Événements de contact

Événements de transaction

Événements d’entreprise

Exemples de code

Initialiser le connecteur

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

// 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

// 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 :

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)

Dépannage

Problèmes courants

Mode débogage

Activez la journalisation détaillée :

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

Tester la connexion

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
• Guide d’authentification HubSpot
• Connecteur Salesforce
• Skill Customer Sync
• API Contacts Brevo