> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot CRM

> Contatos, empresas, negócios, tickets, proprietários e engajamentos do HubSpot CRM no Data Catalog e no Memory, com permissão por registro.

O conector HubSpot lê, pela API do HubSpot CRM, os contatos, as empresas, os negócios, os tickets, os proprietários (usuários internos) e os engajamentos (ligações, e-mails, reuniões e notas), com as associações entre eles. Cada registro chega com a permissão que o HubSpot dá a ele.

| | |
| - | - |
| **Status** | Disponível |
| **Conteúdo** | Registros |
| **Autenticação** | Service Key (token de acesso) |
| **Permissões** | Por item |
| **Sincronização** | Incremental e full refresh, por recurso |
| **Última revisão** | 15/10/2026 |

## Capacidades

* Lê contatos, empresas, negócios e tickets, os proprietários do portal, e as ligações, os e-mails, as reuniões e as notas registrados.
* Lê as associações entre contato e empresa, negócio e contato, negócio e empresa, ticket e contato, e ticket e empresa.
* Instala 14 tabelas clean prontas: 9 de cadastro e atividade (`hubspot_contacts`, `hubspot_companies`, `hubspot_deals`, `hubspot_tickets`, `hubspot_owners`, `hubspot_calls`, `hubspot_emails`, `hubspot_meetings` e `hubspot_notes`) e 5 de associação. Em todas as tabelas de cadastro e atividade, as colunas de data são `TIMESTAMPTZ`, em UTC, então você compara datas em SQL sem conversão.
* Enriquece o contato com o domínio da empresa, e o negócio com o id, o nome e o domínio da empresa.
* Traz o nome do estágio e do funil de cada negócio e de cada ticket, lidos da lista de funis do HubSpot. Veja **Estágios dos funis**.
* Alimenta o Memory com os nós `Customer` (contatos), `Company`, `Deal` (com o nome, a probabilidade e a ordem do estágio), `Ticket` (com o nome, o estado e a ordem do estágio), `Agent` (proprietários), `Email`, `Call`, `Meeting` e `Note`, ligados pelas associações e pelo proprietário de cada registro. `Customer` casa com nós de outros conectores pelo e-mail e pelo telefone, `Company` pelo domínio e `Agent` pelo e-mail. Os nós só entram no grafo depois que a ontologia unificada é aplicada.
* Traz fragmentos de Knowledge: a indexação semântica de `dealname` e `description` dos negócios, e textos de referência sobre as tabelas de tickets e de engajamentos.
* Aplica a permissão de cada contato, empresa, negócio e ticket do HubSpot, e o proprietário e o time dele nos engajamentos. Veja **Permissões (ACL)**.

## Recursos disponíveis

Todo recurso nasce desligado no Data Catalog. Você escolhe quais carregar depois de conectar. Os recursos `deal_pipelines` e `ticket_pipelines` não têm opção própria no Data Catalog: entram quando você liga `deals` e `hs_tickets`, respectivamente, e saem junto com eles.

| Recurso | O que contém | Carga | Cursor | Destino | Permissão por item |
| - | - | - | - | - | - |
| `contacts` | Contatos, com nome, e-mail, telefones, cargo, endereço, `lifecyclestage`, status do lead e proprietário | Incremental ou full refresh | `lastmodifieddate` | Catálogo e Memory | Sim |
| `companies` | Empresas, com nome, domínio, setor, endereço, número de funcionários, receita anual e proprietário | Incremental ou full refresh | `hs_lastmodifieddate` | Catálogo e Memory | Sim |
| `deals` | Negócios, com nome, estágio, pipeline, valor, descrição, data de fechamento e proprietário | Incremental ou full refresh | `hs_lastmodifieddate` | Catálogo, Memory e Knowledge | Sim |
| `hs_tickets` | Tickets de suporte, com assunto, descrição, pipeline, estágio, prioridade, categoria, origem e proprietário | Incremental ou full refresh | `hs_lastmodifieddate` | Catálogo e Memory | Sim |
| `owners` | Proprietários do portal: usuários internos, com id, e-mail, nome, `userId` e se está arquivado | Full refresh | Nenhum | Catálogo e Memory | Sim, a mesma para todas as linhas |
| `calls` | Ligações, com título, anotações, direção, resultado, duração, números, gravação e proprietário | Incremental ou full refresh | `hs_lastmodifieddate` | Catálogo e Memory | Sim |
| `emails` | E-mails registrados, com direção, assunto, texto, remetente, destinatário, status e proprietário | Incremental ou full refresh | `hs_lastmodifieddate` | Catálogo e Memory | Sim |
| `meetings` | Reuniões, com título, anotações, início, término, resultado, local, link e proprietário | Incremental ou full refresh | `hs_lastmodifieddate` | Catálogo e Memory | Sim |
| `notes` | Notas, com o texto, a data e o proprietário | Incremental ou full refresh | `hs_lastmodifieddate` | Catálogo e Memory | Sim |
| `contact_company_associations` | Pares contato e empresa | Full refresh | Nenhum | Catálogo e Memory | Não |
| `deal_contact_associations` | Pares negócio e contato | Full refresh | Nenhum | Catálogo e Memory | Não |
| `deal_company_associations` | Pares negócio e empresa | Full refresh | Nenhum | Catálogo e Memory | Não |
| `ticket_contact_associations` | Pares ticket e contato | Full refresh | Nenhum | Catálogo e Memory | Não |
| `ticket_company_associations` | Pares ticket e empresa | Full refresh | Nenhum | Catálogo e Memory | Não |
| `deal_pipelines` | Funis de negócios, com uma linha por estágio: nome do funil e do estágio, ordem, `probability` e se estão arquivados | Full refresh | Nenhum | Catálogo | Não |
| `ticket_pipelines` | Funis de tickets, com uma linha por estágio: nome do funil e do estágio, ordem, `ticket_state` e se estão arquivados | Full refresh | Nenhum | Catálogo | Não |

> [!NOTE]
>
> As 14 tabelas clean do HubSpot são instaladas quando você cria o conector, fora do contexto. Ligue no Data Catalog as que você quer usar. Cada uma passa a ser atualizada depois de cada sincronização. As tabelas de associação têm pares de ids e servem de ligação entre as outras.

### Estágios dos funis

O HubSpot guarda no negócio e no ticket só o código do estágio. Nos estágios padrão o código é um texto, como `appointmentscheduled`. Nos estágios que você criou, é um número. O nome só existe na lista de funis, que o conector lê nos recursos `deal_pipelines` e `ticket_pipelines`. As tabelas `hubspot_deals` e `hubspot_tickets` juntam essa lista pelo par de códigos do funil e do estágio e ganham estas colunas, além dos códigos, que continuam como estavam:

| Tabela clean | Coluna | Conteúdo |
| - | - | - |
| `hubspot_deals` | `dealstage_name` | Nome do estágio |
| `hubspot_deals` | `pipeline_name` | Nome do funil |
| `hubspot_deals` | `dealstage_probability` | Probabilidade de ganho do estágio, de 0,0 (perdido) a 1,0 (ganho) |
| `hubspot_deals` | `dealstage_order` | Posição do estágio no funil |
| `hubspot_tickets` | `pipeline_stage_name` | Nome do estágio |
| `hubspot_tickets` | `pipeline_name` | Nome do funil |
| `hubspot_tickets` | `ticket_state` | `OPEN` ou `CLOSED`, conforme o estágio |
| `hubspot_tickets` | `pipeline_stage_order` | Posição do estágio no funil |

* Quando o estágio do negócio ou do ticket não aparece na lista de funis, as quatro colunas ficam NULL. O conector não preenche o nome com o código.
* Funis e estágios arquivados continuam na lista, para que um negócio parado num estágio arquivado mantenha o nome.
* Os dois recursos guardam só nomes de configuração do portal, sem dado de pessoa, e não têm permissão por item. Eles não ampliam quem vê cada negócio ou ticket.

### Como ler os dados

* Toda coluna de data das 9 tabelas de cadastro e atividade é `TIMESTAMPTZ`, em UTC. São `created_at` e `updated_at` em todas, `close_date` em `hubspot_deals`, `closed_date` em `hubspot_tickets`, `occurred_at` em `hubspot_calls`, `sent_at` em `hubspot_emails`, `start_time`, `end_time` e `scheduled_at` em `hubspot_meetings` e `noted_at` em `hubspot_notes`. O HubSpot entrega datas em texto ISO 8601 ou em milissegundos desde 1970, e a clean aceita as duas formas. Um valor vazio ou ilegível vira NULL.
* `close_date` e `closed_date` são NULL enquanto o negócio ou o ticket está aberto.
* Os `created_at` de engajamentos e proprietários, e o `updated_at` de proprietários, não vêm de uma propriedade de data, e sim dos campos `createdAt` e `updatedAt` da resposta da API, que só trazem texto ISO 8601.
* E-mails e domínios saem em minúsculas, sem espaços nas pontas. `priority`, `source_type`, `direction` e `status` saem em maiúsculas.
* Em `hubspot_contacts`, `company_domain` vem da empresa principal do contato, a associação de tipo primário. Em `hubspot_deals`, `company_id`, `company_name` e `company_domain` vêm da empresa associada ao negócio, e um negócio com mais de uma empresa gera uma linha por empresa.
* `owner_id` é o proprietário do registro. Ele casa com `external_id` em `hubspot_owners`, e não com o `user_id`.
* `hubspot_calls.duration_ms` é a duração em milissegundos. O HTML do e-mail não entra em `hubspot_emails`, só o texto.

## Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em **Comportamento dos dados**, você escolhe entre dois modos:

| Modo | Quem vê |
| - | - |
| Aberto | Quem puder usar este conector vê todos os registros. As permissões da fonte são ignoradas. |
| Espelhar a fonte | Cada pessoa vê apenas os registros que a própria fonte libera para ela. |

No modo "Espelhar a fonte", marque **Exigir login na fonte como prova de identidade**. O HubSpot identifica cada pessoa por um id próprio, não pelo e-mail, então a Strattum só reconhece quem se autenticou no HubSpot.

### Como a fonte define acesso

No HubSpot, o acesso a contatos, empresas, negócios e tickets é por registro: a API informa quais usuários do portal podem ver cada um. Ligações, e-mails, reuniões e notas pertencem a um proprietário, e o HubSpot não tem permissão por pessoa para eles.

### Como a Strattum traduz o acesso

| Recursos | De onde vem a permissão | Principal gravado |
| - | - | - |
| `contacts`, `companies`, `deals`, `hs_tickets` | Uma chamada de usuários permitidos por registro, com a ação de visualizar | O usuário, pelo `userId` do portal |
| `calls`, `emails`, `meetings`, `notes` | O proprietário que já vem no registro, sem chamada extra | O proprietário, pelo id de proprietário (`hubspot_owner_id`) |
| `owners` | Nenhuma permissão por registro: a lista de usuários internos é do portal | A própria conexão: vê quem pode usar o conector |
| `deal_pipelines`, `ticket_pipelines` | Nenhuma: são nomes de configuração do portal, sem dado de pessoa | Nenhum |

O `userId` e o id de proprietário são numeração diferente para a mesma pessoa. O conector grava cada um como veio e não os unifica, porque nenhum registro recebe os dois. Em contatos e negócios, a linha clean reúne também quem vê a empresa associada: quem pode ver qualquer um dos dois vê a linha. As associações não carregam permissão própria.

Além dos usuários, o conector acrescenta o time do proprietário do registro, lido do campo de times dos proprietários. Esse acesso só passa a valer quando o token tem o escopo `settings.users.teams.read` e algum proprietário pertence a um time. Ele concede o registro ao time inteiro, o que dá mais acesso do que a lista de usuários permitidos de um contato.

### Quando a identidade não é encontrada

No modo "Espelhar a fonte", quem não vinculou a conta do HubSpot não vê contatos, empresas, negócios, tickets nem engajamentos. A lista de proprietários continua visível para quem pode usar o conector. Um registro cuja leitura de usuários permitidos falha, por falta de acesso do token ou porque foi apagado no meio da leitura, é gravado sem ninguém e não aparece para nenhuma pessoa nesse modo. O conector registra um aviso no log da sincronização.

### Quando a permissão é atualizada

A permissão do registro é lida junto com o registro, a cada vez que ele é lido. Em full refresh, isso é a cada execução. Em incremental, só os registros alterados são lidos de novo, então uma mudança de permissão no HubSpot que não altera o registro só chega num full refresh. A participação em times é atualizada por uma rotina própria, a cada 10 minutos por padrão.

## Pré-requisitos

* Uma conta HubSpot com acesso para criar uma Service Key: super admin, ou usuário com a permissão de acesso às ferramentas de desenvolvedor.
* Os escopos de leitura da tabela de **Autenticação e escopos**, adicionados à Service Key.
* Uma Service Key cujos escopos cubram todos os recursos que você quer carregar.
* Para o login na fonte, um app do HubSpot com Client ID e Client Secret, pelo qual as pessoas se autenticam.
* Uma só conexão HubSpot por instalação da Strattum.

## Autenticação e escopos

A autenticação é por token de acesso do HubSpot, no formato `pat-...`, enviado como Bearer. O Console pede uma **Service Key**, criada no Developer Portal. O conector não renova nem troca o token: ele usa o valor guardado até você trocá-lo.

| Escopo ou permissão | Para quê |
| - | - |
| `crm.objects.contacts.read` | Ler contatos. A documentação do HubSpot também o lista para ligações, e-mails, reuniões e notas. |
| `crm.objects.companies.read` | Ler empresas. |
| `crm.objects.deals.read` | Ler negócios. |
| `crm.objects.tickets.read` | Ler tickets. |
| `crm.objects.owners.read` | Ler os proprietários. |
| `sales-email-read` | Alternativa a `crm.objects.contacts.read` para ler e-mails registrados. |
| `settings.users.teams.read` | Ler os times, para o acesso por time do proprietário e para a participação em times. Opcional. |

Os recursos `deal_pipelines` e `ticket_pipelines` não pedem escopo novo: a leitura dos funis usa os escopos de leitura que o conector já pede.

> [!WARNING]
>
> O texto do Console lista só os escopos de contatos, empresas e negócios, e o teste de conexão lê só um contato. Um token sem os demais escopos passa no teste, e a sincronização do recurso sem escopo falha depois. O HubSpot não documenta o escopo que o conector usa para ler os usuários permitidos de cada registro e o id do portal (`/account-info/v3/details`). Sem acesso a eles, a sincronização de contatos, empresas, negócios e tickets falha ou grava registros sem ninguém. Se isso acontecer, confira as permissões da Service Key com o suporte da Strattum.

**1. Abra as Service Keys**

No HubSpot, abra o **Developer Portal** e vá em **Development → Keys → Service Keys**.

**2. Crie a Service Key**

Clique em **Create service key**, dê um nome como `strattum-sync` e adicione os escopos de leitura da tabela acima.

**3. Copie o token**

Copie o token que começa com `pat-`.

> [!WARNING]
>
> O token dá acesso aos dados do portal. Guarde-o em local seguro e nunca o comite em repositórios.

## Configuração no Console

**1. Abra o assistente**

Em **Conectores**, clique em **+ Nova Conexão** e selecione **HubSpot**.

**2. Preencha a conexão**

**Nome do Conector** (Opcional): como a conexão aparece na lista. O padrão é `HubSpot CRM`.

**Service Key (Access Token)** (Obrigatório): o token `pat-...` gerado no Developer Portal.

**3. Teste a conexão**

Clique em **Testar Conexão**. Você só avança depois de um teste com sucesso. O teste lê um contato com o token. Ele falha com "Access token inválido ou expirado" quando o token é recusado e com "Token sem permissão para acessar contacts" quando falta o escopo de contatos.

**4. Escolha a frequência**

Em **Sincronização** (Obrigatório), escolha a frequência. A recomendada para o HubSpot é a cada 2 horas.

**5. Defina o acesso**

Em **Permissionamento**, defina **Quem pode usar este conector** e o **Comportamento dos dados**. Com "Espelhar a fonte", marque **Exigir login na fonte como prova de identidade** e preencha a **URL de autenticação** (Obrigatório; no HubSpot é sempre `https://app.hubspot.com/oauth/authorize`), o **Client ID** (Obrigatório) e o **Client Secret** (Obrigatório) do app do HubSpot. Em **Escopos** (Opcional), o padrão é `oauth`.

**6. Revise e salve**

Em **Revisão**, confira os dados e salve. A Service Key aparece mascarada.

**7. Ligue os recursos no Data Catalog**

No Data Catalog, ligue os recursos e as tabelas clean que você quer carregar. Nos recursos de CRM e de engajamento, escolha o modo **Incremental** na aba **Carga** quando quiser ler só o que mudou: sem essa escolha, o recurso roda em full refresh. `owners` e as associações rodam sempre em full refresh.

Para trocar a Service Key depois, abra o conector em **Conectores** e cole a nova chave. Os campos que você deixa em branco mantêm o valor guardado.

## Como a sincronização funciona

A frequência vem do passo **Sincronização**. A recomendada é a cada 2 horas. Cada execução testa a conexão uma vez, carrega os recursos ligados no Data Catalog um por vez, na ordem `contacts`, `companies`, `deals`, `hs_tickets`, `owners`, `calls`, `emails`, `meetings`, `notes` e as 5 associações, e só então monta as tabelas clean. Se a leitura de um recurso falha, a execução para nele e as tabelas clean não são montadas.

**Registros.** O conector lê em páginas de 100 registros, com as propriedades de cada recurso. Em full refresh, a tabela é reescrita por inteiro a cada execução. Em incremental, a primeira execução lê tudo. As seguintes pedem só os registros alterados depois do maior cursor já carregado e gravam por `id`, então um registro alterado substitui a linha anterior.

**Permissão por registro.** Para cada contato, empresa, negócio e ticket lido, o conector faz mais uma chamada ao HubSpot para saber quem pode ver o registro. Em full refresh, isso dobra o número de chamadas: uma por página e uma por registro.

**Associações.** Cada recurso de associação relê todos os contatos, negócios ou tickets de origem, sem a permissão, e pergunta ao HubSpot as associações de cada grupo de 100 deles. Por isso é sempre um full refresh. O par preferido é o de tipo primário, quando o registro tem mais de um.

**Proprietários.** A lista de proprietários é lida por inteiro a cada execução, sem os arquivados.

**Estágios dos funis.** `deal_pipelines` e `ticket_pipelines` fazem uma única chamada por execução, sem paginação, e gravam uma linha por estágio, em full refresh. Funis e estágios arquivados ficam na tabela.

**Remoção.** Em full refresh, um registro que deixou de existir no HubSpot some da tabela na execução seguinte. Em incremental, um registro apagado ou arquivado continua na tabela, porque a busca por alteração não devolve remoções. Um full refresh o remove.

**Falhas.** A tarefa de extração de cada recurso tenta de novo até 3 vezes, depois de 30, 60 e 120 segundos.

## API da fonte

| Método e caminho | Usado para | Recurso |
| - | - | - |
| `GET /crm/v3/objects/{contacts, companies, deals, tickets}` | Ler os registros, em páginas de 100, com as propriedades de cada recurso | `contacts`, `companies`, `deals`, `hs_tickets` |
| `POST /crm/v3/objects/{contacts, companies, deals, tickets}/search` | Ler só os registros alterados depois do cursor, em ordem crescente | os mesmos, em incremental |
| `GET /crm/v3/objects/{calls, emails, meetings, notes}` | Ler os engajamentos, em páginas de 100 | `calls`, `emails`, `meetings`, `notes` |
| `POST /crm/v3/objects/{calls, emails, meetings, notes}/search` | Ler só os engajamentos alterados depois do cursor | os mesmos, em incremental |
| `GET /crm/v3/owners` | Ler os proprietários e os times de cada um, de 100 em 100 | `owners` e o acesso por time |
| `POST /crm/v4/associations/{origem}/{destino}/batch/read` | Ler as associações de 100 registros por chamada | as 5 associações |
| `GET /crm/v3/pipelines/{deals, tickets}` | Ler os funis e os estágios de cada um, em uma chamada só | `deal_pipelines`, `ticket_pipelines` |
| `GET /resource-permissions/v3/permitted-users` | Saber quais usuários podem ver cada contato, empresa, negócio e ticket | `contacts`, `companies`, `deals`, `hs_tickets` |
| `GET /account-info/v3/details` | Descobrir o id do portal, que monta o identificador de cada registro | `contacts`, `companies`, `deals`, `hs_tickets` |

Todas as chamadas só leem dados. O host da API é `https://api.hubapi.com`. O teste de conexão faz `GET /crm/v3/objects/contacts?limit=1`.

**Rate limits.** O HubSpot limita as chamadas de duas formas. Por app, são 100 chamadas a cada 10 segundos nos planos Free e Starter, 190 nos planos Professional e Enterprise e 250 com o complemento de aumento de limite. Por conta, o limite diário é compartilhado entre os private apps: 250.000 chamadas nos planos Free e Starter, 625.000 no Professional e 1.000.000 no Enterprise. O limite diário reinicia à meia-noite no fuso da conta. Passando do limite, a API responde 429.

O conector envia uma chamada por vez, com tempo limite de 30 segundos. Diante de um 429, espera o tempo do header `Retry-After` quando existe, senão 10 segundos, e tenta de novo, sem limite de tentativas. Quando o limite diário acaba, a espera repete até o reinício, e a tarefa de extração pode ficar presa enquanto isso. Erros 5xx têm até 3 novas tentativas, com espera de 10, 20 e 40 segundos. Como cada contato, empresa, negócio e ticket custa duas chamadas em full refresh, uma carga completa de 100.000 contatos usa cerca de 101.000 chamadas, contra 250.000 por dia nos planos Free e Starter. Nesses planos, o limite de 100 chamadas a cada 10 segundos faz essa carga levar mais de 2 horas. Use o modo incremental nesses recursos.

Referência oficial: [HubSpot, API usage details](https://developers.hubspot.com/docs/api/usage-details)

## Limitações conhecidas

* A permissão por registro vale para contatos, empresas, negócios, tickets e engajamentos. As associações e a lista de proprietários não têm permissão própria: os proprietários ficam visíveis para quem pode usar o conector.
* Uma conexão HubSpot por instalação, com um só portal por conexão.
* O HubSpot identifica as pessoas por id, não por e-mail, então no modo "Espelhar a fonte" só quem vinculou a conta do HubSpot é reconhecido.
* A permissão é lida com o registro. Em incremental, uma mudança de permissão que não altera o registro só chega num full refresh.
* O acesso por time do proprietário concede o registro ao time inteiro e não distingue quem, dentro do time, teria permissão individual. Ele só vale com o escopo `settings.users.teams.read` e com proprietários em times.
* Contatos e negócios mostram o registro para quem vê a empresa associada, mesmo sem acesso ao contato ou ao negócio: vale a união das duas permissões.
* Em incremental, registros apagados ou arquivados no HubSpot não saem da tabela, e um full refresh os remove.
* Cada contato, empresa, negócio e ticket custa uma chamada extra de permissão. Em portais grandes, a carga completa pode gastar boa parte da cota diária.
* O teste de conexão lê só um contato. Ele não confere os escopos de tickets, proprietários e engajamentos.
* Os campos que ligam as tabelas ficam bloqueados no Data Catalog, e uma política de dados pessoais não pode ser aplicada a eles: o proprietário de negócios, tickets e engajamentos (`hubspot_owner_id`), os ids das associações e as colunas de associação usadas para a união de permissões.
* Ligações, e-mails, reuniões e notas não têm tabela de associação: não há ligação direta entre um engajamento e o contato ou a empresa dele.
* Propriedades personalizadas do HubSpot não são lidas. O conector pede um conjunto fixo de propriedades por recurso.
* O SQL de cada tabela clean é instalado quando você cria o conector, e editar o conector não o reinstala. Uma conexão criada antes de 12/10/2026 mantém o SQL anterior, com as datas das tabelas clean em texto. Uma criada antes da versão que trouxe os estágios dos funis mantém também o SQL antigo de `hubspot_deals` e `hubspot_tickets`, sem as colunas de estágio. A Strattum precisa reinstalar esses dois modelos e rodar uma sincronização antes de as colunas aparecerem.
* Itens de linha, produtos, cotações e campanhas ficam de fora.

## Troubleshooting

| Mensagem ou sintoma | Causa | O que fazer |
| - | - | - |
| Informe o Access Token antes de testar | O campo da Service Key está vazio. | Cole o token `pat-...` no campo. |
| Access token inválido ou expirado | O token foi revogado, apagado ou digitado errado. | Gere ou copie o token de novo no Developer Portal e atualize o conector. |
| Token sem permissão para acessar contacts | A Service Key não tem `crm.objects.contacts.read`. | Adicione o escopo na Service Key e teste de novo. |
| Erro HTTP seguido de um número | O HubSpot recusou ou falhou na chamada. | Confira o número no HubSpot e teste de novo. |
| A sincronização de `hs_tickets`, `owners` ou engajamentos falha depois de um teste com sucesso | O token não tem o escopo do recurso. O teste só lê contatos. | Adicione `crm.objects.tickets.read`, `crm.objects.owners.read` ou o escopo do engajamento à Service Key. |
| A sincronização para e fica lenta, com avisos de limite no log | O limite por 10 segundos ou o limite diário do HubSpot foi atingido. | Aguarde. A espera termina quando a janela reinicia. Use o modo incremental. |
| Contatos, empresas, negócios ou tickets não aparecem no modo "Espelhar a fonte" | A pessoa não vinculou a conta do HubSpot, ou a leitura de permissão do registro falhou e ele foi gravado sem ninguém. | Peça à pessoa para vincular a conta. Confira no log os avisos de permissão e os escopos da Service Key. |
| A sincronização falha dizendo que a resposta de usuários permitidos foi ilegível para todos os registros do recurso | O HubSpot respondeu num formato que o conector não reconhece, em todos os registros. | A sincronização falha em vez de gravar tudo sem permissão. Contate o suporte da Strattum. |

## Próximos passos

> **[Data Catalog](https://docs.strattum.ai/data-catalog/overview.md)**
>
> Ligue os recursos e as tabelas clean do HubSpot e acompanhe a carga.

> **[Memory](https://docs.strattum.ai/memory/overview.md)**
>
> Veja como contatos, empresas, negócios e proprietários viram nós do grafo de conhecimento.

> **Desenvolvimento local**
>
> A sincronização lê o token só da conexão cadastrada pelo Console, que o guarda no cofre de credenciais. Não há variável de ambiente para a sincronização. A variável `HUBSPOT_ACCESS_TOKEN` é lida apenas quando você usa a classe do conector direto, em um script.
>
> | Variável | O que é |
> | - | - |
> | `HUBSPOT_ACCESS_TOKEN` | O token `pat-...`, só para uso direto da classe do conector. |
>
> ```bash theme={null}
> HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
> ```
>
> Veja o guia de [configuração local](https://docs.strattum.ai/data-pipelines/local-development.md) para subir o Prefect e o worker.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.