Skip to main content
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.

​
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.
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:
  • 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: 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

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

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

​
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

​
Próximos passos

Data Catalog

Ligue os recursos e as tabelas clean do HubSpot e acompanhe a carga.

Memory

Veja como contatos, empresas, negócios e proprietários viram nós do grafo de conhecimento.
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.
Veja o guia de configuração local para subir o Prefect e o worker.