Como integrar a HubSpot a outros softwares

Toda empresa chega num ponto em que a HubSpot precisa conversar com outras ferramentas. O ERP que tem os pedidos. O BI que monta os painéis da liderança. O sistema interno que ninguém quer aposentar. E é aí que muitas integrações com o CRM nascem tortas, porque são tratadas como um problema técnico de ligar dois canos, quando na verdade são uma decisão de arquitetura: quem é dono do dado, e como ele viaja.

Errar essa decisão tem consequências caras e duradouras: registros duplicados, sistemas que se contradizem, relatórios em que ninguém confia e um laço infinito de atualização em que um sistema sobrescreve o outro para sempre. Acertar, por outro lado, cria uma operação em que cada dado tem um dono claro e circula sem atrito. Neste guia, vou organizar as opções de integração, do sync nativo até a construção dedicada, e ajudar você a escolher a arquitetura certa para ERP, automações e BI.

Defina o sistema mestre antes de qualquer código

A pergunta mais importante de qualquer integração vem antes da primeira linha de código: para cada tipo de dado, qual sistema é a fonte da verdade? O CRM pode ser dono dos contatos e dos negócios. O ERP pode ser dono dos pedidos e das faturas. Sem essa definição, dois sistemas acham que mandam no mesmo registro, editam ao mesmo tempo e brigam, e você acaba com dado que muda sozinho dependendo de qual sincronização rodou por último.

O sistema mestre decide quem escreve e quem só lê em cada campo. Essa clareza é o que evita o conflito e o laço de atualização. Definir o mestre por tipo de dado, e às vezes até por campo, parece burocracia no começo, mas é exatamente o que mantém a operação coerente conforme ela cresce e ganha mais sistemas conectados. É a planta baixa antes de levantar as paredes.

Os quatro caminhos para integrar a HubSpot

Antes de descer ao detalhe, vale ter o mapa. Praticamente toda integração com a HubSpot cai em um de quatro caminhos, e conhecê-los evita começar pela opção errada.

Integrações nativas são os conectores prontos do marketplace da HubSpot, como Zendesk, Slack, Typeform e Trello, além do data sync embutido na plataforma. São o caminho mais rápido quando o outro app está na lista: configuração sem código e monitoramento incluso.

Integrações via middleware ou iPaaS usam uma camada intermediária, como n8n, Make ou Zapier, para conectar sistemas que não têm conector direto. Você monta o fluxo visualmente, sem escrever a integração inteira na mão.

Integrações dedicadas são construídas sob medida quando o software é proprietário, as regras são complexas ou o volume é alto. Custam mais no início e exigem manutenção, mas entregam o controle de erro, concorrência e escala que os outros caminhos não alcançam.

API e webhooks são a base técnica de qualquer construção própria: a API REST da HubSpot permite ler e escrever qualquer objeto, e os webhooks notificam o seu sistema em tempo real quando algo muda na HubSpot, em vez de você ficar consultando de tempos em tempos.

Nos próximos tópicos, percorro esses caminhos na ordem em que você deve considerá-los.

Comece pelo data sync nativo, antes de escrever qualquer coisa

Antes de partir para uma plataforma de integração ou uma construção sob medida, vale checar se o próprio data sync da HubSpot já resolve o problema. Ele está disponível nos planos e conecta a HubSpot a apps do marketplace com sincronização em uma via ou nas duas, sem código. E ele implementa, como recurso de produto, exatamente o que a seção anterior prega: na configuração de resolução de conflito você escolhe qual app sobrescreve o outro quando os valores divergem, o que é o sistema mestre virando uma lista suspensa.

Além de direção e conflito, o sync nativo traz mapeamento de campos entre os dois apps, filtros que limitam quais registros participam, e um painel de saúde que mostra quantos registros estão em sincronia, falhando ou excluídos, com o motivo de cada falha. Depois do sync inicial, que indexa as duas bases e pode demorar em volumes grandes, as mudanças propagam em cerca de dez minutos. Mapeamentos customizados de propriedade exigem uma assinatura paga do Data Hub, o sync em si não.

O limite é a cobertura: ele só funciona com apps que suportam data sync, e segue as regras que o conector oferece, não uma lógica arbitrária. Se o seu sistema não está na lista, ou se a regra que você precisa é mais complexa do que mapear e filtrar, aí sim você avança para as próximas opções. Mas checar isso primeiro poupa muitos times de construir na mão algo que a plataforma já entrega pronto, com monitoramento incluso.

Use propriedades de id único para casar os registros

Para ligar um registro da HubSpot ao mesmo registro do outro sistema, não improvise um casamento por nome. A HubSpot já trata o email como identificador único primário de contato, e o nome ou o domínio para empresa, então para muitos casos você não precisa inventar chave nenhuma. Quando o sistema externo tem um id próprio, e normalmente tem, o caminho certo é criar uma propriedade marcada como identificador único e usá-la como ponte.

POST https://api.hubapi.com/crm/v3/properties/contacts {   "groupName": "contactinformation",   "name": "erp_customer_id",   "label": "Id do cliente no ERP",   "hasUniqueValue": true,   "type": "string",   "fieldType": "text" }

Uma vez criada, essa propriedade funciona no mesmo nível do id do registro, do email ou do domínio. Você consegue buscar um registro direto pelo valor dela, usando o parâmetro idProperty, e consegue ler registros em lote por ela. O teto é de dez propriedades de id único por objeto, bem mais do que qualquer integração saudável precisa. Vale saber de antemão: a marcação de único é definida na criação da propriedade, então se a propriedade já existe sem ela, o caminho prático é criar uma nova propriedade única e migrar os valores, não converter a antiga.

O ganho real aparece na escrita. Com a propriedade única no lugar, você para de fazer aquela dança frágil de buscar primeiro, decidir se existe e então criar ou atualizar. Você usa o upsert em lote com idProperty, e a HubSpot cria o registro se ele não existir e atualiza se existir, numa única chamada. Essa é a defesa estrutural contra duplicata, não uma gambiarra.

POST https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert {   "inputs": [     {       "idProperty": "erp_customer_id",       "id": "ERP-88231",       "properties": { "phone": "+5511999999999" }     }   ] }

Esse cuidado também viabiliza a reconciliação. Quando algo divergir entre os dois sistemas, e um dia vai divergir, ter o id externo guardado permite cruzar os dois lados e achar onde está a diferença. Sem essa âncora, reconciliar vira um pesadelo de comparar nomes parecidos e chutar correspondências. Com ela, a conferência é objetiva e rápida.

iPaaS: n8n, Make e Zapier

As plataformas visuais de integração, conhecidas como iPaaS, conectam a HubSpot a outras ferramentas sem que você escreva a integração inteira na mão. Elas trazem blocos prontos para as operações mais comuns e, nas mais técnicas, um bloco HTTP genérico para qualquer endpoint que os blocos prontos não cobrem. A credencial fica guardada no gerenciador da própria ferramenta, separada da lógica do fluxo, o que é uma boa prática de segurança.

As três não são equivalentes, porém. O n8n e o Make tratam a chamada HTTP livre como cidadã de primeira classe, o que significa que você alcança qualquer endpoint da HubSpot mesmo quando não existe bloco pronto para ele. O Zapier é mais opinativo e mais limitado nesse ponto, o que o torna excelente para automações simples e lineares e desconfortável quando você precisa tocar um endpoint menos comum. Escolher pelo teto que você vai encontrar, e não pela primeira tela, evita trocar de plataforma seis meses depois.

Esse caminho é excelente para automações de negócio e sincronizações de volume baixo a moderado, porque entrega resultado rápido e é fácil de manter por times menos técnicos. O limite aparece quando o volume cresce muito ou as regras ficam complexas demais: aí o fluxo visual vira uma teia difícil de entender, e uma integração dedicada, com mais controle de erro e de concorrência, passa a fazer mais sentido. Saber a hora de mudar de um para o outro faz parte da maturidade da operação.

Integração dedicada: API e webhooks

Quando nem o conector nativo nem o iPaaS dão conta, a construção dedicada assume. A base é a API da HubSpot: você cria uma aplicação privada, recebe as credenciais e passa a ler e escrever qualquer objeto com a lógica que a sua operação exige, incluindo filas para absorver picos, operações em lote para respeitar os limites de taxa e tratamento de erro com retentativa.

O complemento natural são os webhooks. Em vez de o seu sistema perguntar de tempos em tempos se algo mudou, a HubSpot avisa na hora: um contato criado ou um negócio atualizado dispara uma notificação para um endpoint seu, que escuta e aciona a ação correspondente. Para sincronizações que precisam de reação em tempo real, essa combinação de API para escrever e webhook para reagir é o desenho padrão de uma integração dedicada bem feita.

O preço desse caminho é o mesmo de qualquer software sob medida: custo inicial maior, prazo de implementação mais longo e manutenção contínua conforme as APIs evoluem. Por isso ele vem por último na ordem de consideração, e por isso compensa exatamente onde os outros caminhos quebram: volume alto, regras complexas e sistemas proprietários.

Extração para BI: da HubSpot para o warehouse, do warehouse para o BI

Aqui está o erro que mais se repete, e ele sai caro. É tentador apontar a ferramenta de BI direto para a API da HubSpot, porque parece um atalho. Não é. Cada atualização do painel reprocessa a base, queima o seu limite de taxa, fica mais lenta conforme a operação cresce e não guarda histórico: se um valor muda na HubSpot, o anterior some para sempre, e você nunca mais consegue explicar como o número estava no trimestre passado.

O desenho correto tem duas pernas. A HubSpot alimenta um data warehouse, e o BI lê do warehouse. O warehouse é o que absorve o volume, guarda o histórico, cruza os dados da HubSpot com o ERP e o produto, e responde uma consulta pesada sem encostar na API. O BI vira apenas a camada de exibição sobre uma base que já está pronta. Essa separação é o que deixa o painel rápido e o número auditável.

A extração para o warehouse segue o padrão incremental: trazer só o que mudou desde a última carga, em vez de reprocessar a base inteira a cada execução. Filtrar por data de modificação significa usar a Search API, e ela tem regras próprias: teto de dez mil registros por conjunto de filtros, limite de taxa próprio e um atraso de indexação, porque os resultados vêm de um índice de busca e não direto do banco. Os endpoints de listagem paginam por cursor sem teto, mas não filtram por data. Desenhar a extração levando essa diferença em conta é o que evita que ela quebre no dia em que a base crescer.

Para contatos existe mais um detalhe que derruba muita gente: há duas datas de modificação, e elas respondem perguntas diferentes. Uma reflete mudanças nas propriedades do registro, a outra também se mexe com atividade sobre o registro, como um email aberto. Escolher a errada significa trazer registros que ninguém editou ou perder edições que você precisava. Decida qual das duas corresponde ao que o seu relatório quer dizer, e seja explícito sobre isso.

Se a operação é grande e já vive sobre um warehouse, vale saber que a HubSpot oferece um compartilhamento nativo de dados, somente leitura, para o Snowflake, com os dados atualizados em cadência fixa e sem você escrever nem manter nenhum pipeline. Ele exige uma assinatura de nível enterprise, então não é para todo mundo, mas é o caminho mais limpo quando se encaixa, e reforça o mesmo princípio: o warehouse no meio, sempre.

Padrões que se repetem

Por mais única que cada operação seja, as integrações com a HubSpot tendem a cair em alguns padrões reconhecíveis. O primeiro é a sincronização em uma via, em que um sistema é dono e o outro só recebe, simples e segura. O segundo é a sincronização nas duas vias, mais poderosa e mais perigosa, que exige um sistema mestre por campo para não virar cabo de guerra. O terceiro é a extração para análise, leitura pura, que alimenta warehouses sem nunca escrever de volta.

Reconhecer em qual padrão a sua necessidade se encaixa já resolve metade do desenho. A maioria das integrações que parecem complicadas é, na verdade, uma combinação desses padrões básicos, e tratá-los separadamente deixa tudo mais claro. Em vez de tentar resolver tudo num fluxo gigante, identifique cada padrão presente e desenhe cada um com a arquitetura que ele pede.

Como escolher a arquitetura certa

Não existe uma arquitetura única que sirva para tudo. A escolha depende do volume, da complexidade das regras e de a integração ser somente de leitura ou nas duas vias. O resumo abaixo ajuda a decidir.

Dica de quem já apanhou: antes de integrar, desenhe no papel quem é dono de cada dado e para que lado ele flui. Cinco minutos de desenho economizam meses de duplicação e conflito. A maioria das integrações problemáticas que vemos não tem um erro de código, tem uma decisão de arquitetura que nunca foi tomada.

Na prática: o ERP e o CRM que brigavam

Uma operação integrou a HubSpot ao ERP nas duas vias, sem definir quem era dono de cada dado. O resultado foi um cabo de guerra: o vendedor atualizava o contato na HubSpot, a sincronização levava para o ERP, o ERP tinha uma regra que sobrescrevia o campo, e na próxima execução o valor voltava errado para a HubSpot. O dado oscilava sem fim, e ninguém sabia qual versão era a verdadeira.

A solução não foi técnica, foi de arquitetura. Definiram que o CRM era dono dos dados de contato e o ERP dos dados financeiros, e configuraram a sincronização para respeitar isso, com cada campo tendo um dono só. O cabo de guerra acabou na hora. O mesmo dado que oscilava ficou estável, porque enfim tinha um dono claro.

Reflexão para quem lidera a operação: uma integração não se julga por quantos sistemas ela conecta, e sim por quanta dúvida ela remove. Quando cada campo tem um dono, cada registro tem um identificador, e os relatórios saem de um warehouse em vez de uma chamada ao vivo na API, as discussões sobre de quem é o número certo simplesmente param de acontecer. Esse silêncio é o retorno da arquitetura.

Checklist de uma integração bem arquitetada

• Você definiu o sistema mestre para cada tipo de dado, e às vezes por campo?
• Você checou se o data sync nativo já cobre o app antes de construir qualquer coisa?
• Os registros são casados por uma propriedade de id único, usando idProperty na leitura e no upsert?
• A direção do fluxo está clara, evitando o laço de atualização?
• Você escolheu entre iPaaS e integração dedicada pelo volume e pela complexidade?
• Para BI, o dado passa antes por um data warehouse, com extração incremental somente de leitura?
• Existe um plano de reconciliação para quando os sistemas divergirem?
• O time foi treinado na nova integração, e existe monitoramento ativo para avisar quando algo falhar?

Perguntas frequentes

Preciso de um desenvolvedor para integrar a HubSpot?

Nem sempre. Se o outro app suporta o data sync nativo da HubSpot, você configura sem código. Casos simples além disso se resolvem com iPaaS visual como n8n ou Make. Volume alto, regras complexas ou integração nas duas vias pedem uma solução dedicada e mais controle de erro.

Como evito duplicar registros entre sistemas?

Defina um sistema mestre por tipo de dado e guarde o id externo numa propriedade marcada como identificador único. Depois use o upsert em lote com idProperty, para a HubSpot atualizar o registro se ele existir e criar se não existir, em vez de gerar duplicata.

Qual a melhor forma de levar dados da HubSpot para o BI?

Extração incremental para um data warehouse, e o BI lendo do warehouse. Apontar o BI direto para a API reprocessa a base a cada atualização, queima o limite de taxa e não guarda histórico.

O que é um sistema mestre?

É o sistema definido como fonte da verdade para um tipo de dado. Ele decide quem escreve e quem só lê aquele campo, o que evita que dois sistemas editem o mesmo registro e briguem. No sync nativo da HubSpot, isso aparece como a configuração de resolução de conflito.

Quando trocar o iPaaS por uma integração dedicada?

Quando o volume cresce muito ou as regras ficam complexas a ponto de o fluxo visual virar difícil de entender e manter. Aí uma integração dedicada oferece mais controle de erro, de concorrência e de escala.

Integração nas duas vias é sempre necessária?

Não. Para BI e análise, a leitura pura basta e é mais segura. As duas vias só se justificam quando os dois sistemas realmente precisam escrever, e nesse caso exigem sistema mestre por campo e cuidado com os laços.

Pronto para integrar sem bagunça?

Se o processo parece complexo demais ou está além da capacidade do seu time, você não precisa atravessar essa jornada sozinho. A Insight Sales tem mais de uma década de expertise em integrações com a HubSpot e muitas outras ferramentas, do data sync à construção dedicada. Fale com um especialista e descubra como podemos ajudar a sua operação a ter dados com dono, fluxo e confiança.