---
title: "Connettore HubSpot"
description: "Guida completa all'integrazione di HubSpot CRM per sincronizzare contatti, aziende, deal, ticket e dati di marketing con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/crm/hubspot/
markdown: https://tajo.io/it/docs/connectors/crm/hubspot.md
lang: it-IT
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Connettore HubSpot

Stato del connettore: In corso In costruzione. Non ancora verificato.

| Campo di origine | Campo di destinazione | Valore di esempio |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Collega il tuo HubSpot CRM a Brevo tramite Tajo per una sincronizzazione bidirezionale dei contatti, tracciamento dei deal, dati di engagement e automazione marketing unificata tra entrambe le piattaforme.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | HubSpot |
| **Categoria** | CRM |
| **Complessità di setup** | Media |
| **Integrazione ufficiale** | Sì |
| **Dati sincronizzati** | Contatti, Aziende, Deal, Ticket, Eventi |
| **API Base URL** | `https://api.hubapi.com` |

## Funzionalità

- **Sincronizzazione bidirezionale dei contatti** - Mantieni i contatti sincronizzati tra HubSpot e Brevo in tempo reale
- **Tracciamento pipeline deal** - Sincronizza gli stage e i valori dei deal per la segmentazione basata sui ricavi
- **Sincronizzazione dati azienda** - Associa i contatti ai record aziendali e ai dati firmografici
- **Integrazione ticket** - Traccia i ticket di supporto per il customer health scoring
- **Tracciamento engagement** - Sincronizza aperture email, click, riunioni, chiamate e note
- **Supporto oggetti personalizzati** - Mappa gli oggetti personalizzati HubSpot agli attributi Brevo
- **Trigger workflow** - Usa i cambiamenti di lifecycle stage HubSpot per attivare automazioni Brevo
- **Eventi webhook** - Notifiche in tempo reale per i cambiamenti dei dati CRM

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account HubSpot (Free, Starter, Professional o Enterprise)
2. Una private app o un’app OAuth HubSpot con gli scope richiesti
3. Un account Brevo con accesso API
4. Un account Tajo

## Autenticazione

### Access Token Private App (consigliato)

Crea una private app in HubSpot per l’accesso diretto alle API con controllo granulare degli scope.

1. Vai in HubSpot Impostazioni > Integrazioni > Private Apps
2. Crea una nuova private app
3. Configura gli scope richiesti
4. Copia l’access token

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

Usa OAuth 2.0 per integrazioni multi-account che richiedono l’autorizzazione dell’utente.

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

#### Scope richiesti

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

## Configurazione

### Setup di 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
```

### Mappatura dei campi

Mappa le proprietà HubSpot agli attributi di contatto Brevo:

#### Mappature predefinite

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | Email del contatto (identificatore primario) |
| `firstname` optional | string | Mappato all'attributo FIRSTNAME in Brevo |
| `lastname` optional | string | Mappato all'attributo LASTNAME in Brevo |
| `phone` optional | string | Mappato all'attributo SMS per WhatsApp/SMS |
| `company` optional | string | Nome dell'azienda associata |
| `lifecyclestage` optional | string | Lifecycle stage HubSpot (subscriber, lead, MQL, SQL, customer) |
| `hs_lead_status` optional | string | Stato di qualificazione del lead |
| `hubspot_owner_id` optional | string | ID del sales owner assegnato |

#### Mappatura proprietà personalizzate

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

## Endpoint API

### Oggetti CRM

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/contacts` | Elenca i contatti |
| `POST` | `/crm/v3/objects/contacts` | Crea un contatto |
| `PATCH` | `/crm/v3/objects/contacts/{id}` | Aggiorna un contatto |
| `GET` | `/crm/v3/objects/companies` | Elenca le aziende |
| `GET` | `/crm/v3/objects/deals` | Elenca i deal |
| `POST` | `/crm/v3/objects/deals` | Crea un deal |
| `GET` | `/crm/v3/objects/tickets` | Elenca i ticket |

### Associazioni

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}` | Ottieni associazioni |
| `PUT` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}` | Crea associazione |

### Engagement

| Metodo | Endpoint | Descrizione |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/calls` | Elenca gli engagement di tipo chiamata |
| `GET` | `/crm/v3/objects/emails` | Elenca gli engagement email |
| `GET` | `/crm/v3/objects/meetings` | Elenca le riunioni |
| `GET` | `/crm/v3/objects/notes` | Elenca le note |
| `GET` | `/crm/v3/objects/tasks` | Elenca i task |

## Eventi

### Eventi contatto

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `contact.creation` | Nuovo contatto creato | Trigger flusso di benvenuto |
| `contact.propertyChange` | Proprietà contatto aggiornata | Sincronizzazione attributi |
| `contact.merge` | Contatti uniti | Gestione deduplicazione |
| `contact.deletion` | Contatto eliminato | Pulizia in Brevo |

### Eventi deal

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `deal.creation` | Nuovo deal creato | Notifica vendite |
| `deal.propertyChange` | Stage deal modificato | Automazione pipeline |
| `deal.deletion` | Deal rimosso | Reportistica ricavi |

### Eventi azienda

| Evento | Trigger | Caso d’uso |
| --- | --- | --- |
| `company.creation` | Nuova azienda aggiunta | Account-based marketing |
| `company.propertyChange` | Dati azienda aggiornati | Sync firmografica |

## Esempi di codice

### Inizializza il connettore

```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
});
```

### Esegui sincronizzazione contatti

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

### Gestisci eventi 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');
});
```

## Limiti di velocità

HubSpot applica i limiti di velocità per private app o app OAuth:

| Piano | Limite | Burst Limit |
| --- | --- | --- |
| Free/Starter | 100 richieste/10 secondi | 150 richieste/10 secondi |
| Professional | 150 richieste/10 secondi | 200 richieste/10 secondi |
| Enterprise | 200 richieste/10 secondi | 250 richieste/10 secondi |
| API add-on | 200 richieste/10 secondi | 250 richieste/10 secondi |

Limiti aggiuntivi:

- **Search API**: 5 richieste/secondo per app
- **Operazioni batch**: 100 record per richiesta batch
- **Limite giornaliero**: 500.000 richieste/giorno (app OAuth)

Gestione dei limiti di velocità

HubSpot restituisce una risposta `429 Too Many Requests` quando i limiti vengono superati. Usa il backoff esponenziale e monitora gli header `X-HubSpot-RateLimit-*`.

## Risoluzione dei problemi

### Problemi comuni

| Problema | Causa | Soluzione |
| --- | --- | --- |
| 401 Unauthorized | Token scaduto o non valido | Rigenera il token della private app o aggiorna il token OAuth |
| Contatto non sincronizzato | Proprietà email mancante | I contatti HubSpot richiedono un’email per la sync con Brevo |
| Contatti duplicati | Nessuna regola di deduplicazione | Configura le regole di merge in HubSpot |
| Webhook non ricevuto | Subscription non attiva | Registra nuovamente le subscription webhook |
| Proprietà non mappata | Proprietà personalizzata non creata | Crea prima la proprietà in HubSpot |

### Modalità debug

Abilita il logging dettagliato:

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

### Testa la connessione

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

## Best practice

1. **Usa le private app invece delle API key** - Le API key sono deprecate; usa le private app per maggiore sicurezza
2. **Implementa la sync bidirezionale con attenzione** - Evita loop infiniti tracciando la sorgente di sync
3. **Mappa i lifecycle stage** - Usa i lifecycle stage HubSpot per segmentare i contatti in Brevo
4. **Richieste API in batch** - Usa gli endpoint batch per operazioni in blocco e rimani entro i limiti
5. **Monitora la consegna dei webhook** - Imposta logica di retry e gestione delle dead letter
6. **Usa la sync incrementale** - Sincronizza solo i record modificati usando la proprietà `lastmodifieddate`

## Sicurezza

- **Private App Token** - Access token con scope granulari
- **OAuth 2.0** - Autorizzazione standard del settore con rotazione dei refresh token
- **Firme webhook** - Verifica firma basata su HMAC (v3)
- **Cifratura TLS** - Tutte le comunicazioni API cifrate in transito
- **Permessi con scope** - Accesso agli scope minimi richiesti per integrazione

## Risorse correlate

- [Documentazione API HubSpot](https://developers.hubspot.com/docs/api/overview)
- [Guida autenticazione HubSpot](https://developers.hubspot.com/docs/api/working-with-oauth)
- [Connettore Salesforce](https://tajo.io/it/docs/connectors/crm/salesforce)
- [Skill Customer Sync](https://tajo.io/it/docs/skills/data-sync/customer-sync)
- [API Contatti Brevo](https://tajo.io/it/docs/contact-management)