Como ler e sincronizar dados do CRM com a API da HubSpot

Se existe um ponto de partida para quase toda integração com a HubSpot, é a leitura de dados do CRM. Antes de automatizar qualquer coisa, antes de escrever um único registro, você precisa ler: levar contatos para um data warehouse, espelhar negócios num sistema interno, disparar um processo a partir de uma mudança de estágio. Tudo começa em ler bem.

E ler bem na HubSpot é mais do que fazer um GET. É escolher a forma certa de leitura para cada caso, entender o esquema do objeto antes de mapear campos, e manter tudo sincronizado sem perder nem duplicar registros ao longo do tempo. Neste guia, vou te levar pelo caminho completo: ler registros, buscar recortes, entender propriedades, sincronizar de forma incremental e tratar as associações que conectam tudo.

Ler registros de um objeto

O caso mais básico é listar registros de um objeto, seja ele padrão, como contatos e negócios, ou personalizado. A regra de ouro aqui é pedir só as propriedades que você vai usar de fato, com o parâmetro properties, para reduzir o tamanho da resposta e a pressão sobre os limites de taxa. O limite é de 100 registros por página, e a paginação é por cursor, então você repete a chamada com o cursor até percorrer tudo.

Buscar um subconjunto com a Search API

Quando você não quer tudo, mas um recorte, por data, por estágio, por valor, a ferramenta certa é a Search API. Ela aceita filtros agrupados, ordenação e seleção de propriedades, e devolve só o que casa com a sua condição. O cuidado central é o teto de 10.000 resultados por conjunto de filtros: se o seu recorte é maior que isso, quebre-o em faixas que não se sobrepõem, normalmente por janelas de data de criação, e pagine cada faixa separadamente. Usar a busca quando deveria listar, ou vice-versa, é uma das causas mais comuns de extrações incompletas.

Entenda o esquema antes de mapear campos

Um passo que muita gente pula e depois se arrepende é ler as propriedades do objeto antes de sincronizar. Antes de decidir quais campos levar para o outro sistema, consulte o esquema. A resposta traz, para cada propriedade, o nome interno, o tipo, o grupo a que pertence e se ela é somente leitura. Esse último ponto é crucial: campos calculados, os chamados rollups, não podem ser preenchidos por API. Tentar gravar neles só gera erro. Conhecer o esquema de antemão evita mapear um campo que você nunca conseguiria escrever.

Sincronização incremental: só o que mudou

Manter o destino atualizado não significa extrair a base inteira toda vez, o que seria lento e caro. Significa trazer só o que mudou desde a última sincronização. O padrão é buscar por hs_lastmodifieddate maior que o instante da última rodada, com uma janela de sobreposição de alguns minutos para não perder registros alterados bem na virada do corte, porque a Search API lê de um índice com consistência eventual e um registro recém-alterado pode levar alguns instantes, às vezes minutos, para aparecer, então a sobreposição deve cobrir esse atraso. Você pagina a busca por cursor e deduplica por id ao gravar, para que a sobreposição atualize em vez de duplicar. Esse padrão incremental é o que transforma uma extração de horas numa rotina de minutos. Uma ressalva para contatos: eles têm dois campos de modificação, lastmodifieddate e hs_lastmodifieddate, então escolha conscientemente, já que o hs_lastmodifieddate também sobe por atividade de engajamento como abertura de email.

Empresas, negócios e o papel das associações

Empresas e negócios seguem exatamente o mesmo padrão de leitura dos contatos: lista, busca, propriedades, sincronização incremental. O que muda, e o que torna o CRM realmente um CRM, é a associação. Um negócio não vive sozinho, ele está ligado a contatos e a uma empresa. Um contato pertence a uma empresa. Essas conexões são dados de primeira classe, e você precisa lê-las para reconstruir a teia de relacionamentos no outro sistema.

Associações também paginam

O detalhe que pega muita gente é que a lista de registros associados a um registro também é paginada. Uma empresa âncora pode ter dezenas de contatos ligados a ela, espalhados por várias páginas. Se você lê só a primeira página de associações, perde os vínculos do restante, justamente dos registros mais conectados e importantes. Trate a leitura de associações com o mesmo laço de cursor das leituras normais, sem exceção, ou a teia de relacionamentos chega incompleta no destino.

Batch read: quando você já tem os ids

Existe um terceiro jeito de ler que resolve um caso específico muito comum: você já tem uma lista de ids e quer os dados completos de cada um. Para isso, em vez de fazer cem chamadas individuais, use o endpoint de batch read, que aceita até 100 ids por requisição e devolve todos de uma vez. Isso reduz drasticamente o número de chamadas e, com ele, a pressão sobre os limites de taxa. É a forma certa, por exemplo, de enriquecer uma lista de contatos que veio de outro sistema com os dados atuais da HubSpot.

O batch read não tem cursor, porque você não está descobrindo registros, está pedindo registros que já conhece. A paginação ali é a sua própria divisão da lista de ids em blocos de até 100. O cuidado é não repetir o mesmo id dentro de um lote e tratar a resposta para separar os que vieram dos que, por acaso, não existem mais. Combinado com leitura e busca, o batch read completa o conjunto de ferramentas de extração.

Erros comuns na leitura do CRM

Alguns tropeços aparecem com frequência e custam horas de depuração. O mais comum é usar a busca para extrair tudo e bater no teto de 10.000 sem perceber, achando que a extração foi completa quando faltou metade. Outro é pedir todas as propriedades por preguiça de listar as necessárias, o que infla a resposta e aproxima do 429. Um terceiro, mais sutil, é mapear um campo calculado para escrita, descobrindo só na hora de gravar que aquele rollup é somente leitura.

O antídoto para todos eles é o mesmo: conhecer o esquema e as regras antes de rodar em volume. Leia as propriedades, decida quais campos importam, escolha entre listar e buscar com critério, e teste uma chamada de cada tipo antes de processar milhares de registros. Esse cuidado prévio, que leva minutos, evita os erros que custam um dia inteiro de investigação no lugar errado.

Por que isso importa para a sua operação

Ler e sincronizar bem o CRM é a fundação de quase tudo o que vem depois. Um BI confiável depende de a extração para o seu data warehouse não perder registros. Uma integração com ERP depende de uma sincronização que reflete cada mudança. Uma régua de relacionamento depende de saber, de verdade, quem está associado a quê. Quando a leitura falha, o efeito não fica no técnico: o painel mente, a decisão se apoia em dado velho, o cliente recebe a mensagem errada. Investir em ler direito é investir na confiança que toda a operação deposita no dado.

Na prática: o espelho do CRM que não batia

Uma operação espelhava o CRM da HubSpot num data warehouse para alimentar relatórios, e os números nunca fechavam com o que se via na HubSpot. Investigando, apareceram duas causas. A extração de negócios usava busca e parava no teto de 10.000, e a leitura de associações trazia só a primeira página, perdendo os vínculos das contas maiores, que eram exatamente as mais relevantes para a análise.

A correção foi quebrar a busca em faixas de data e paginar as associações com o mesmo laço de cursor das leituras de registro. Depois disso, o espelho passou a refletir a HubSpot fielmente, e os relatórios voltaram a ser confiáveis. O dado não estava errado na origem; ele estava chegando pela metade por causa de duas leituras mal feitas.

Objetos personalizados seguem o mesmo padrão

Um receio comum de quem começa é achar que objetos personalizados exigem uma lógica totalmente diferente. Não exigem. Listagem, busca, leitura de propriedades, sincronização incremental e associações funcionam exatamente igual para objetos personalizados e para os padrão. O que muda é apenas o tipo na URL, que passa a usar o identificador do objeto personalizado em vez de contatos ou negócios. Toda a disciplina de paginação por cursor, teto de 10.000 na busca e deduplicação por id continua valendo do mesmo jeito.

Isso é uma boa notícia para a manutenção. Uma vez que o seu time domina o padrão de leitura para os objetos padrão, ele já sabe ler qualquer objeto personalizado que a operação criar no futuro, sem reaprender nada. O conhecimento se reaproveita, e a integração cresce sem virar uma coleção de exceções. Padrões consistentes são o que mantém uma integração sustentável conforme o CRM evolui.

Checklist da leitura e sincronização do CRM

1. A leitura pede só as propriedades necessárias em properties?
2. Você usa listagem para extração total e busca para recortes?
3. As buscas grandes estão quebradas em faixas para não bater no teto de 10.000?
4. Você leu o esquema do objeto e sabe quais campos são somente leitura?
5. A sincronização é incremental, por hs_lastmodifieddate, com sobreposição e deduplicação por id?
6. As leituras de associação usam o mesmo laço de cursor das leituras de registro?
7. Existe um ponteiro persistido com o maior hs_lastmodifieddate processado?

Perguntas frequentes

Como faço a primeira carga e depois só o que mudou?

Carga inicial listando o objeto inteiro, que não tem teto de 10.000, ou por Search em faixas de createdate para fatiar. Depois, sincronização incremental por hs_lastmodifieddate maior que o último corte, com janela de sobreposição e deduplicação por id ao gravar.

Posso gravar em campos calculados?

Não. Rollups e campos de cálculo são somente leitura na API. Para derivar valores, use um workflow no lugar de tentar escrever via API.

Qual a diferença entre ler propriedades e ler registros?

Ler propriedades traz o esquema do objeto: campos, tipos e grupos. Ler registros traz os dados em si. Você lê o esquema uma vez para mapear, e os registros sempre que sincroniza.

Listagem ou busca para extrair tudo?

Para extração completa de um objeto, prefira a listagem, que não tem o teto de 10.000. Reserve a busca para recortes filtrados, quebrando-a em faixas quando passar do teto.

Preciso paginar a leitura de associações?

Sim. A lista de registros associados a um registro também é paginada. Use o mesmo laço de cursor, ou vai perder vínculos das contas mais conectadas.

O mesmo padrão vale para objetos personalizados?

Sim. Listagem, busca, leitura de propriedades e sincronização incremental funcionam igual para objetos padrão e personalizados. Muda só o tipo na URL.

Precisa espelhar o CRM da HubSpot em um data warehouse, banco ou sistema interno que o seu BI consome, atualizado e confiável? Na Insight Sales construímos as rotinas de leitura e sincronização que sustentam relatórios em que você pode confiar. Fale com a gente e descubra como podemos ajudar.