Integrar ERP e HubSpot: as decisões de arquitetura que definem o projeto antes da primeira linha de código

A decisão que define um projeto de integração entre ERP e HubSpot não é a escolha da ferramenta de integração. É a definição, objeto por objeto, de qual sistema é fonte de verdade, qual chave reconcilia os registros entre os dois lados e em que direção cada campo pode ser escrito. Projetos que pulam essa etapa entregam sincronização funcionando na primeira semana e produzem divergência de cadastro no terceiro mês, quando os dois sistemas passam a disputar o mesmo campo.

Este artigo trata das decisões estruturais e dos limites técnicos concretos da plataforma, que precisam entrar no desenho antes do orçamento do projeto.

Decisão 1: fonte de verdade por objeto

A pergunta correta não é se o ERP ou o CRM manda. É quem manda em cada objeto e em cada campo. Um desenho típico de indústria ou distribuição no Brasil:

O critério que resolve quase todos os casos duvidosos: manda quem tem responsabilidade legal ou contábil sobre o dado. Cadastro fiscal, condição comercial e faturamento pertencem ao ERP. Relacionamento, intenção e etapa de negociação pertencem ao CRM.

Campos que aparecem nos dois lados sem dono definido são a causa raiz da maior parte das divergências. A regra prática é que todo campo sincronizado tenha exatamente um sistema com permissão de escrita, e que o outro lado seja explicitamente somente leitura, inclusive na interface, com a propriedade bloqueada para edição manual.

Decisão 2: chave de reconciliação e idempotência

Nome de empresa não é chave. Razão social muda, vem com abreviação diferente em cada sistema e não sobrevive a fusão de registros.

O desenho que se sustenta usa CNPJ como chave de negócio para empresas e e-mail para contatos, e mantém, em propriedade dedicada e imutável na HubSpot, o identificador interno do ERP. Essa propriedade é o que garante idempotência: reprocessar o mesmo evento duas vezes atualiza o mesmo registro em vez de criar um segundo.

Três cuidados que evitam retrabalho:

Normalização antes da comparação. CNPJ sem máscara, e-mail em minúsculas, sem espaços. A normalização precisa ser idêntica dos dois lados do fluxo.

Tratamento de matriz e filial. Empresas com várias inscrições exigem decisão prévia: um registro por CNPJ raiz com filiais como objeto associado, ou um registro por CNPJ completo. As duas soluções funcionam; a ausência de decisão não.

Deleção e fusão. Registro excluído ou fundido no ERP precisa de tratamento definido no CRM. Fusão de registros altera identificador, e integrações que ignoram esse evento passam a escrever em registro órfão.

Decisão 3: evento ou lote

Orientado a evento. O ERP dispara webhook a cada mudança relevante e a integração reage. Latência baixa, volume de chamadas proporcional à mudança. Exige que o ERP tenha webhook, o que nem sempre acontece nos sistemas brasileiros de porte médio.

Lote com marca d'água. A integração consulta periodicamente os registros alterados desde o último carimbo de tempo processado. Simples, tolerante a falha, e a marca d'água precisa ser persistida com cuidado para não reprocessar nem pular janela.

Captura de mudança no banco. Quando o ERP não expõe API adequada, a leitura acontece na camada de dados, com replicação ou trilha de alteração. Exige acordo com o fornecedor do ERP e atenção a contrato de suporte.

Na prática, a maioria dos cenários combina os três: evento para o que precisa de resposta imediata, lote noturno para reconciliação e conferência, e uma rotina de comparação semanal que aponta divergência antes que alguém a descubra em uma reunião comercial.

Decisão 4: os limites de aplicativos privados

Esses números precisam estar no desenho, não na descoberta durante a homologação. Para aplicativos de distribuição privada na HubSpot:

Detalhes que mudam o desenho:

• O limite de rajada é por app; o limite diário é compartilhado por toda a conta. Uma conta com integração de ERP, ferramenta de dados e app de assinatura eletrônica divide o mesmo teto diário. O orçamento de chamadas precisa ser feito no nível da conta.

• A API de busca tem limite próprio e mais restrito. Como a busca é o caminho natural para verificar se um registro já existe antes de criar, ela costuma ser o gargalo real, e não o limite de rajada. A alternativa é manter o identificador externo indexado e usar leitura direta ou endpoint em lote.

• Endpoints em lote contam como uma requisição. Substituir um laço que lê cem registros individualmente por uma leitura em lote reduz o custo de cem chamadas para uma. É a otimização de maior efeito e a mais frequentemente esquecida.

• Erros 429 exigem recuo exponencial. A HubSpot orienta que respostas de erro não ultrapassem 5% do total diário de requisições, e esse é o patamar exigido para certificação de app no Marketplace. Uma integração sem política de repetição atinge esse percentual com facilidade em dia de carga.

• Webhooks disparados por workflow não contam para o limite de API. É uma saída de arquitetura relevante para notificar sistemas externos sem consumir cota.

• Há tetos estruturais. Até 20 aplicativos privados legados por conta e até 1.000 assinaturas de webhook por app.

O que costuma quebrar em produção

Fila sem tratamento de falha. Toda integração precisa de destino para a mensagem que falhou repetidamente, com registro do payload original e alerta. Sem isso, a perda de dado não deixa rastro.

Ordem de eventos. Atualização e criação chegando fora de ordem produzem registro incompleto. O tratamento é comparar carimbo de tempo do evento com o do registro, e descartar o que for mais antigo.

Automação disparando durante carga. Importação em massa aciona workflows de nutrição e alertas de proprietário. A rotina de carga precisa prever suspensão de automação e critério de reativação.

Ausência de ambiente de teste. Homologar em portal de produção é a origem de boa parte dos incidentes de dado. A HubSpot oferece ambientes de teste e o desenho do projeto precisa contemplá-los.

Falta de observabilidade. O consumo de API é visível na própria conta, em Development, Monitoring, API call usage. Monitorar isso semanalmente antecipa o problema em vez de reagir a ele.

Objetos customizados e o modelo de dados

Pedido, contrato, nota fiscal, apólice, ordem de serviço e equipamento instalado raramente cabem bem em propriedades de negócio. Objetos customizados, disponíveis no plano Enterprise, permitem representar essas entidades com propriedades e associações próprias, o que preserva a granularidade do ERP dentro do CRM sem inflar o registro de empresa com dezenas de campos.

Essa é uma das razões pelas quais a decisão de plano precisa ser tomada com o desenho de integração na mesa, e não depois. Quando o requisito envolve orquestração com muitos ramos, reprocessamento controlado ou volume alto, a construção sai do que se resolve por configuração e entra em engenharia sobre a plataforma, com aplicativos privados, ações de código customizado e controle de fila.

Continue lendo

• Migrar de CRM: o que levar, o que arquivar, o que reconstruir

• O editor de agentes da HubSpot por dentro

• Conheça os Hubs e as ofertas da Reevia

Perguntas frequentes

Qual o limite de chamadas de API da HubSpot?
Para aplicativos de distribuição privada: 100 requisições por 10 segundos e 250.000 por dia em Free e Starter; 190 por 10 segundos e 625.000 por dia em Professional; 190 por 10 segundos e 1.000.000 por dia em Enterprise. O limite de rajada é por app e o diário é compartilhado por toda a conta. A API de busca e a de associações têm limites próprios e mais restritos.

É possível integrar a HubSpot com um ERP que não tem webhook?
Sim. O padrão nesse caso é consulta periódica por marca d'água de data de alteração, ou captura de mudança na camada de dados quando o ERP permite. A latência é maior e o desenho precisa tratar reprocessamento e janela de leitura.

Qual campo usar como chave entre ERP e CRM?
CNPJ normalizado para empresas e e-mail para contatos, sempre com o identificador interno do ERP armazenado em propriedade dedicada e imutável na HubSpot. Nome de empresa não serve como chave.

Sincronização bidirecional é sempre melhor?
Não. Bidirecional só faz sentido quando cada campo tem dono único definido. Sem essa definição, a bidirecionalidade produz sobrescrita cruzada e divergência crescente. Muitos cenários se resolvem melhor com fluxo unidirecional por objeto.

Quanto tempo leva uma integração entre ERP e HubSpot?
Depende quase inteiramente de duas variáveis: a qualidade da API do ERP e o grau de decisão prévia sobre modelo de dados. O levantamento e o desenho costumam consumir mais tempo que a construção, e projetos que tentam encurtar essa etapa a pagam depois em manutenção.

Fontes

• HubSpot Developers: diretrizes e limites de uso da API

• HubSpot Legal Center: catálogo de produtos e serviços

Limites e recursos de plataforma mudam. Confirme na documentação oficial na data do desenho do projeto.