Quase todo projeto de integração começa pela pergunta técnica: o CRM tem API? Quase sempre tem. A pergunta que decide se a integração vai aguentar o volume da empresa é outra, e ela não aparece na tela de integrações nem na proposta do fornecedor: quantas chamadas por dia o plano contratado permite, e quem mais está gastando essa mesma cota.
Este guia mostra, com os números da documentação oficial de dois CRMs muito usados no Brasil, como o limite de requisições funciona por plano, como estimar o consumo antes de assinar e como desenhar a integração para que o erro de limite não vire lead perdido. Não é um tutorial de programação: é a conta que gestor, TI e fornecedor precisam fazer juntos.
O que é integração via API?
Integração via API é a ligação entre dois sistemas feita por uma interface de programação: um sistema envia uma requisição padronizada (buscar um contato, criar um negócio, atualizar um status) e o outro responde com dados ou com uma confirmação. É assim que o formulário do site cria o lead no CRM, que o ERP recebe o pedido fechado pelo vendedor e que a ferramenta de e-mail sabe quem já virou cliente.
A diferença em relação a exportar e importar planilhas é que a troca acontece sozinha, registro a registro, no momento em que o dado muda ou em intervalos definidos. Por isso a API é o caminho padrão quando o objetivo é evitar retrabalho e divergência de cadastro, o problema que já tratamos ao falar sobre o custo do dado partido entre sistemas.
Cada uma dessas trocas é uma chamada (ou requisição). E é aqui que entra o ponto que os guias sobre o tema costumam pular: o fornecedor do CRM não deixa ninguém fazer chamadas à vontade. Ele mede, limita e, em alguns casos, cobra por elas conforme o plano.
Qual a diferença entre integração nativa e integração via API?
Integração nativa é a conexão pronta que o próprio CRM (ou o outro sistema) oferece: você autoriza, escolhe alguns campos e ela começa a funcionar. Integração via API é a conexão construída sob medida, por um desenvolvedor, uma plataforma de automação ou um middleware, usando a interface que o CRM expõe. As duas usam API por baixo. A diferença é quem decide o que trafega, com que frequência e o que acontece quando dá erro.
| Integração nativa | Integração via API sob medida | |
|---|---|---|
| Quem constrói | O fornecedor do CRM ou do outro sistema | Equipe interna, agência, plataforma de automação ou middleware |
| Campos e regras | Os que o conector já prevê | Os que o processo da empresa exige |
| Consumo de cota | Pouco visível: o conector gasta, mas raramente mostra quanto | Visível e controlável: dá para medir e otimizar cada chamada |
| Tratamento de erro | Padrão do conector, às vezes silencioso | Desenhado: fila, nova tentativa, alerta |
| Quando faz sentido | Fluxo simples e volume baixo | Volume alto, regra específica ou vários sistemas |
| Risco típico | Parar de sincronizar sem avisar | Gastar a cota com chamadas desnecessárias |
Comparativo elaborado pela Alliance Comunicação a partir de projetos de integração de CRM.
Um detalhe que pesa na conta: nos dois CRMs usados como exemplo neste guia, o conector nativo e a integração sob medida gastam a mesma cota diária. Instalar mais um aplicativo do marketplace não é neutro. Ele passa a disputar o mesmo orçamento de chamadas com a integração que leva os pedidos ao ERP.
O que é rate limit e por que ele está no contrato, não no código?
Rate limit é o limite de requisições que uma API aceita num intervalo de tempo. Normalmente existem dois: o limite de rajada, que controla quantas chamadas cabem em poucos segundos, e o limite diário, que controla o total de um dia. O primeiro protege o servidor de picos; o segundo, na prática, é uma régua comercial.
É uma régua comercial porque quem define o tamanho do limite é o plano contratado. O mesmo código, rodando contra a mesma API, aguenta um volume num plano de entrada e um volume várias vezes maior num plano superior. Ou seja: antes de escrever qualquer linha de integração, a capacidade dela já foi decidida na assinatura do CRM.
Isso muda a ordem da conversa. O normal é escolher o CRM pela tela de vendas, contratar o plano que cabe no orçamento e só depois chamar alguém para integrar. Quando o volume não cabe, a descoberta acontece em produção, com lead que não chegou e pedido que não sincronizou.
Quanto a API do CRM aguenta em cada plano?
Os números abaixo vêm da documentação oficial dos dois fornecedores. Eles mudam com o tempo, por isso a regra prática é conferir a página oficial no dia da contratação. Ainda assim, mostram com clareza a lógica: o limite cresce com o plano e, em um dos casos, com o número de usuários pagos.
O HubSpot vende ainda um complemento de aumento de limite: com ele, segundo a mesma página, a rajada sobe para 250 requisições a cada 10 segundos por app e a conta ganha 1 milhão de chamadas diárias a mais por complemento, com no máximo dois. É um custo a colocar na planilha quando a estimativa passa do teto do plano.
No Pipedrive, além do orçamento diário, há limites de rajada em janela móvel de 2 segundos. Com token de API, são 20 requisições no Lite, 40 no Growth, 100 no Premium e 120 no Ultimate; a API de busca fica em 10 requisições a cada 2 segundos em qualquer plano. E o orçamento é da empresa inteira: a documentação diz que ele é dividido entre todos os usuários da conta.
Repare que o Pipedrive não conta requisições, e sim tokens. Cada tipo de chamada custa um valor diferente. Na tabela de exemplos da documentação, ler um registro pelo identificador custa 2 tokens, listar registros custa 20, atualizar um registro custa 10 e uma busca custa 40. A própria documentação informa que os endpoints da versão 2 da API custam menos tokens que os da versão 1.
Por que a cota diária é dividida entre todas as integrações?
Porque o limite é da conta, não do aplicativo. No HubSpot, a documentação afirma que o limite diário é compartilhado por todos os apps da mesma conta. No Pipedrive, o orçamento de tokens é da empresa e dividido entre todos os usuários. Na prática, a integração com o ERP, o conector da ferramenta de e-mail, o painel de BI que puxa dados toda hora e a planilha automatizada de alguém do comercial bebem da mesma fonte.
É por isso que integrações que funcionaram bem por meses param de repente. Ninguém mexeu nelas. Alguém instalou um conector novo, ou o BI passou a atualizar a cada cinco minutos, e a soma estourou o teto às três da tarde. O sintoma aparece longe da causa: quem sente é o vendedor que não recebe o lead, não quem instalou o aplicativo.
A integração não tem cota própria. Ela divide o orçamento do CRM com todo aplicativo que alguém da empresa já conectou.
A primeira tarefa de qualquer projeto, então, é o inventário: listar tudo o que está conectado à conta do CRM hoje, quem é o dono de cada conexão e quanto cada uma consome. No Pipedrive, a documentação aponta um painel de uso da API dentro das configurações da empresa; em qualquer CRM, vale pedir ao fornecedor onde esse consumo aparece.
Como calcular quantas chamadas a integração vai fazer por dia?
A conta é simples e quase ninguém faz. Ela multiplica eventos por chamadas e soma o que já está ligado. Os passos abaixo valem para qualquer CRM; o que muda é a unidade (requisições ou tokens).
1. Liste os eventos e o volume diário
Quantos leads entram por dia? Quantos pedidos o ERP fatura? Quantas vezes por dia um vendedor muda a etapa de um negócio? Use o pico, não a média: a segunda-feira depois de uma campanha, o fim de mês, a Black Friday.
2. Conte as chamadas de cada evento
Um lead novo raramente é uma chamada só. Normalmente a integração busca se o contato já existe, cria ou atualiza o contato, associa à empresa e cria o negócio. Quatro ou cinco chamadas por evento é comum. Se o CRM cobra por tipo de chamada, a busca costuma ser a mais cara.
3. Some as consultas periódicas
Toda integração que pergunta ao CRM de tempos em tempos se algo mudou gasta cota mesmo quando nada mudou. Uma consulta a cada 5 minutos são 288 chamadas por dia, por tipo de objeto, antes de qualquer dado útil.
4. Some as outras integrações da conta
Entre no painel de uso, ou peça ao fornecedor, e anote o consumo atual. É sobre ele que a nova integração vai se somar.
5. Compare com a cota e deixe folga
Compare o total com a cota do plano e reserve margem para pico, para a carga inicial e para as novas tentativas depois de erro. Integração dimensionada no limite falha justamente no dia em que mais importa.
Um exemplo hipotético, só para mostrar a ordem de grandeza, com os custos em tokens publicados pelo Pipedrive. Uma empresa no plano Growth com 5 assentos tem 30.000 × 2 × 5 = 300 mil tokens por dia. Se a integração com o ERP processa 1.000 atualizações de pedido por dia e, para cada uma, faz uma busca (40 tokens) e uma atualização (10 tokens), são 50 mil tokens. Uma consulta periódica de lista a cada 5 minutos em três tipos de registro soma 288 × 3 × 20 = 17.280 tokens. Cabe com folga.
Agora a mesma integração numa conta Lite com 3 assentos: o orçamento é de 30.000 × 1 × 3 = 90 mil tokens. Os pedidos e as consultas já levam quase 70 mil. Basta somar os leads do site, um conector de e-mail e um painel de BI para o dia acabar antes do expediente.
Webhook ou consulta periódica: qual gasta menos cota?
Na consulta periódica (o chamado polling), a integração pergunta ao CRM a cada intervalo se há algo novo. No webhook, o próprio sistema avisa a integração quando algo acontece. A consulta gasta cota o tempo todo, inclusive nas horas em que nada muda; o webhook só dispara quando há evento.
No HubSpot a diferença é explícita: a documentação informa que chamadas de webhook disparadas por workflows não contam para o limite de requisições. A documentação do Pipedrive, por sua vez, recomenda reestruturar a arquitetura da integração e usar webhooks quando o consumo está alto. Nos dois casos, trocar consulta por aviso é a forma mais barata de liberar cota.
As outras duas alavancas são os endpoints em lote, que gravam ou leem vários registros numa chamada só, e o cache, que evita perguntar de novo o que não mudou. O HubSpot recomenda as duas coisas na mesma página dos limites. E há uma terceira, menos óbvia: guardar no ERP o identificador do registro no CRM. Ler pelo identificador é a operação mais barata da tabela do Pipedrive (2 tokens); buscar pelo e-mail ou pelo CNPJ é a mais cara (40). Definir esse identificador comum é parte de decidir qual sistema manda em cada dado.
O que acontece quando a API devolve o erro 429?
O código 429 (Too Many Requests) é a resposta padrão de uma API quando o limite foi atingido. No HubSpot, a resposta indica qual limite foi rompido: o diário ou o de rajada. No Pipedrive, esgotado o orçamento do dia, todas as requisições seguintes são recusadas com 429 até a renovação, à meia-noite no fuso do servidor, que pode não coincidir com o horário de Brasília.
O erro em si não perde dado. Quem perde dado é a integração que recebeu o 429 e seguiu em frente. Se o formulário do site chamou o CRM, levou um 429 e não guardou o lead em lugar nenhum, aquele contato sumiu. Por isso o desenho correto tem quatro peças: uma fila que guarda o evento, uma nova tentativa com espera crescente, um alerta que avisa antes do teto e uma reconciliação que confere, no dia seguinte, o que ficou para trás.
Há ainda uma regra de qualidade que pouca gente conhece. Para aplicativos certificados no marketplace do HubSpot, as requisições que terminam em erro não devem passar de 5% do total diário. Mesmo fora do marketplace, o número é um bom termômetro: integração que erra muito está gastando cota em chamadas que não produzem nada, e repetindo-as.
Quais os erros mais comuns ao dimensionar uma integração via API?
- Escolher o plano do CRM sem a conta de chamadas. A capacidade da integração é decidida na assinatura, não no código.
- Esquecer a carga inicial. Migrar a base histórica pode consumir dias de cota. Com a busca do Pipedrive a 40 tokens e 10 requisições a cada 2 segundos, deduplicar 20 mil contatos por busca exige 800 mil tokens e, no mínimo, cerca de uma hora só de espera de rajada.
- Consultar de minuto em minuto o que poderia vir por webhook. É a forma mais comum de gastar cota sem trazer dado novo.
- Buscar o registro toda vez em vez de guardar o identificador. A busca é a chamada mais cara e a mais limitada.
- Ignorar o erro 429. Sem fila e sem nova tentativa, cada pico vira registro perdido, e ninguém fica sabendo.
- Instalar conectores sem dono. Cada aplicativo do marketplace divide a mesma cota diária.
- Medir pela média. O teto é rompido no pico, e o pico costuma coincidir com campanha, fechamento de mês ou data comercial.
Nenhum desses erros aparece no teste. Em homologação, com poucos registros, tudo funciona. Eles aparecem em produção, no volume real, que é exatamente o momento em que o dado mais importa.
O que muda por porte de empresa?
O raciocínio é o mesmo para todos; o que muda é onde o limite aperta primeiro.
| Porte | Onde o limite aperta | O que priorizar |
|---|---|---|
| Pequena, plano de entrada | Cota diária baixa e poucos assentos para multiplicar | Webhook no lugar de consulta, poucos conectores, conta feita antes de contratar |
| Média, várias integrações | Soma de conectores dividindo a mesma cota | Inventário das conexões, dono para cada uma, painel de consumo |
| Grande, ERP e alto volume | Rajada em picos e carga de grandes lotes | Endpoints em lote, fila com nova tentativa, complemento de limite no orçamento |
| Qualquer porte em migração | Carga inicial da base histórica | Migrar em etapas, fora do horário comercial, com reconciliação ao fim |
Quadro elaborado pela Alliance Comunicação a partir das documentações oficiais de limites do HubSpot e do Pipedrive.
Para a empresa pequena, vale um alerta extra: os planos de entrada são justamente os de menor cota nas duas documentações citadas. Antes de apostar a operação num deles, vale entender o que o plano gratuito de CRM limita.
O que perguntar ao fornecedor antes de contratar?
A integração via API costuma ser orçada por horas de desenvolvimento ou por assinatura de uma plataforma de automação. Esse é o custo visível. O custo que muda a decisão é o do plano do CRM necessário para aguentar o volume, e ele só aparece quando alguém faz as perguntas certas:
- Qual é o limite de rajada e o limite diário do plano que estamos contratando, e onde isso está documentado?
- O limite é por aplicativo, por usuário ou da conta inteira?
- Quais chamadas custam mais, e os webhooks entram na conta?
- Existe endpoint em lote para os objetos que vamos sincronizar?
- Quanto custa subir o limite: troca de plano, mais assentos ou complemento?
- Onde acompanhamos o consumo, e existe alerta antes do teto?
- O que acontece com o dado quando a cota acaba no meio do dia?
A última pergunta é a que ninguém faz e a que mais diz sobre a integração. Se a resposta for "a API devolve erro", o fornecedor está descrevendo o CRM. A resposta que interessa é a do projeto de integração: onde o dado espera, quem é avisado e como ele chega depois.
Por onde começar hoje
Comece pelo inventário: tudo o que está conectado ao CRM, quem responde por cada conexão e quanto ela consome. Depois faça a conta do pico para a integração nova, com as unidades do seu fornecedor, e compare com a cota do plano atual. Se não couber, a decisão é comercial antes de ser técnica: subir de plano, comprar complemento ou redesenhar a integração para gastar menos.
Se a dúvida é onde o funil da empresa perde informação entre marketing, vendas e atendimento, o diagnóstico gratuito de marketing avalia dados, tecnologia e relacionamento junto com as demais dimensões. E quando o passo for desenhar e implantar a integração do CRM com site, ERP e demais sistemas, com fila, alertas e consumo medido, esse é o trabalho de integração de CRM e dados da Alliance: do diagnóstico à ação.