---
title: "Conector HubSpot"
description: "Guia completo de integração do HubSpot CRM para sincronizar contatos, empresas, negócios, tickets e dados de marketing com o Brevo via Tajo."
url: https://tajo.io/pt/docs/connectors/crm/hubspot/
markdown: https://tajo.io/pt/docs/connectors/crm/hubspot.md
lang: pt-BR
robots: noindex
---

Solicite acesso antecipado

Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo.

# Conector HubSpot

Status do conector: Em andamento Em construção. Ainda não verificado.

| Campo de origem | Campo de destino | Valor de exemplo |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Conecte seu HubSpot CRM ao Brevo via Tajo para sincronização bidirecional de contatos, rastreamento de negócios, dados de engajamento e automação de marketing unificada entre as duas plataformas.

## Visão geral

| Propriedade | Valor |
| --- | --- |
| **Plataforma** | HubSpot |
| **Categoria** | CRM |
| **Complexidade de configuração** | Média |
| **Integração oficial** | Não |
| **Dados sincronizados** | Contatos, Empresas, Negócios, Tickets, Eventos |
| **URL base da API** | `https://api.hubapi.com` |

## Recursos

- **Sincronização bidirecional de contatos** - Mantenha contatos em sincronia entre HubSpot e Brevo em tempo real
- **Rastreamento de pipeline de negócios** - Sincronize estágios e valores de negócios para segmentação baseada em receita
- **Sincronização de dados de empresa** - Associe contatos a registros de empresa e dados firmográficos
- **Integração de tickets** - Acompanhe tickets de suporte para pontuação de saúde do cliente
- **Rastreamento de engajamento** - Sincronize aberturas de e-mail, cliques, reuniões, chamadas e notas
- **Suporte a objetos personalizados** - Mapeie objetos personalizados do HubSpot para atributos do Brevo
- **Gatilhos de workflow** - Use mudanças de estágio de ciclo de vida do HubSpot para disparar automações do Brevo
- **Eventos de webhook** - Notificações em tempo real para mudanças de dados no CRM

## Pré-requisitos

Antes de começar, certifique-se de que você tem:

1. Uma conta HubSpot (Free, Starter, Professional ou Enterprise)
2. Um app privado HubSpot ou app OAuth com os escopos necessários
3. Uma conta Brevo com acesso à API
4. Uma conta Tajo

## Autenticação

### Token de acesso de app privado (Recomendado)

Crie um app privado no HubSpot para acesso direto à API com controle granular de escopo.

1. Acesse HubSpot Settings > Integrations > Private Apps
2. Crie um novo app privado
3. Configure os escopos necessários
4. Copie o token de acesso

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

Use OAuth 2.0 para integrações multi-conta que exigem autorização do usuário.

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

#### Escopos necessários

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

## Configuração

### Configuração básica

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

### Mapeamento de campos

Mapeie propriedades do HubSpot para atributos de contato do Brevo:

#### Mapeamentos padrão

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | E-mail do contato (identificador primário) |
| `firstname` optional | string | Mapeia para o atributo FIRSTNAME no Brevo |
| `lastname` optional | string | Mapeia para o atributo LASTNAME no Brevo |
| `phone` optional | string | Mapeia para o atributo SMS para WhatsApp/SMS |
| `company` optional | string | Nome da empresa associada |
| `lifecyclestage` optional | string | Estágio de ciclo de vida do HubSpot (subscriber, lead, MQL, SQL, customer) |
| `hs_lead_status` optional | string | Status de qualificação do lead |
| `hubspot_owner_id` optional | string | ID do responsável de vendas atribuído |

#### Mapeamento de propriedades personalizadas

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

### Objetos de CRM

| Método | Endpoint | Descrição |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/contacts` | Listar contatos |
| `POST` | `/crm/v3/objects/contacts` | Criar um contato |
| `PATCH` | `/crm/v3/objects/contacts/{id}` | Atualizar um contato |
| `GET` | `/crm/v3/objects/companies` | Listar empresas |
| `GET` | `/crm/v3/objects/deals` | Listar negócios |
| `POST` | `/crm/v3/objects/deals` | Criar um negócio |
| `GET` | `/crm/v3/objects/tickets` | Listar tickets |

### Associações

| Método | Endpoint | Descrição |
| --- | --- | --- |
| `GET` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}` | Obter associações |
| `PUT` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}` | Criar associação |

### Engajamentos

| Método | Endpoint | Descrição |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/calls` | Listar engajamentos de chamadas |
| `GET` | `/crm/v3/objects/emails` | Listar engajamentos de e-mail |
| `GET` | `/crm/v3/objects/meetings` | Listar reuniões |
| `GET` | `/crm/v3/objects/notes` | Listar notas |
| `GET` | `/crm/v3/objects/tasks` | Listar tarefas |

## Eventos

### Eventos de contato

| Evento | Gatilho | Caso de uso |
| --- | --- | --- |
| `contact.creation` | Novo contato criado | Gatilho de fluxo de boas-vindas |
| `contact.propertyChange` | Propriedade de contato atualizada | Sincronização de atributos |
| `contact.merge` | Contatos mesclados | Tratamento de deduplicação |
| `contact.deletion` | Contato excluído | Limpeza no Brevo |

### Eventos de negócio

| Evento | Gatilho | Caso de uso |
| --- | --- | --- |
| `deal.creation` | Novo negócio criado | Notificação de vendas |
| `deal.propertyChange` | Estágio do negócio alterado | Automação de pipeline |
| `deal.deletion` | Negócio removido | Relatório de receita |

### Eventos de empresa

| Evento | Gatilho | Caso de uso |
| --- | --- | --- |
| `company.creation` | Nova empresa adicionada | Marketing baseado em conta |
| `company.propertyChange` | Dados de empresa atualizados | Sincronização firmográfica |

## Exemplos de código

### Inicializar o conector

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

### Executar sincronização de contatos

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

### Tratar eventos de 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 taxa

O HubSpot aplica limites de taxa por app privado ou app OAuth:

| Plano | Limite de taxa | Limite de burst |
| --- | --- | --- |
| Free/Starter | 100 requisições/10 segundos | 150 requisições/10 segundos |
| Professional | 150 requisições/10 segundos | 200 requisições/10 segundos |
| Enterprise | 200 requisições/10 segundos | 250 requisições/10 segundos |
| API add-on | 200 requisições/10 segundos | 250 requisições/10 segundos |

Limites adicionais:

- **API de busca**: 5 requisições/segundo por app
- **Operações em lote**: 100 registros por requisição em lote
- **Limite diário**: 500.000 requisições/dia (apps OAuth)

Tratamento de limite de taxa

O HubSpot retorna uma resposta `429 Too Many Requests` quando os limites são excedidos. Use backoff exponencial e monitore os cabeçalhos `X-HubSpot-RateLimit-*`.

## Solução de problemas

### Problemas comuns

| Problema | Causa | Solução |
| --- | --- | --- |
| 401 Unauthorized | Token expirado ou inválido | Regere o token do app privado ou renove o token OAuth |
| Contato não sincronizado | Propriedade de e-mail ausente | Contatos do HubSpot exigem e-mail para sincronizar com o Brevo |
| Contatos duplicados | Sem regra de deduplicação | Configure regras de mesclagem no HubSpot |
| Webhook não recebido | Assinatura não ativa | Registre novamente as assinaturas de webhook |
| Propriedade não mapeada | Propriedade personalizada não criada | Crie a propriedade no HubSpot primeiro |

### Modo de depuração

Habilite o log detalhado:

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

### Testar conexão

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

## Melhores práticas

1. **Use apps privados em vez de chaves de API** - Chaves de API estão obsoletas; use apps privados para melhor segurança
2. **Implemente sincronização bidirecional com cuidado** - Evite loops infinitos rastreando a fonte da sincronização
3. **Mapeie estágios de ciclo de vida** - Use estágios de ciclo de vida do HubSpot para segmentar contatos no Brevo
4. **Use requisições em lote** - Use endpoints em lote para operações em massa para ficar dentro dos limites de taxa
5. **Monitore a entrega de webhooks** - Configure lógica de retry e tratamento de dead letter
6. **Use sincronização incremental** - Sincronize apenas registros alterados usando a propriedade `lastmodifieddate`

## Segurança

- **Tokens de app privado** - Tokens de acesso com escopo e permissões granulares
- **OAuth 2.0** - Autorização padrão de mercado com rotação de refresh token
- **Assinaturas de webhook** - Verificação de assinatura baseada em HMAC (v3)
- **Criptografia TLS** - Toda comunicação com a API é criptografada em trânsito
- **Permissões com escopo** - Acesso de escopo mínimo necessário por integração

## Recursos relacionados

- [Documentação da API do HubSpot](https://developers.hubspot.com/docs/api/overview)
- [Guia de autenticação do HubSpot](https://developers.hubspot.com/docs/api/working-with-oauth)
- [Conector Salesforce](https://tajo.io/pt/docs/connectors/crm/salesforce)
- [Skill de sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync)
- [API de contatos do Brevo](https://tajo.io/pt/docs/contact-management)