O que aprendi rodando consultas de CNPJ em produção por 8 meses

Verissimo Ribeiro — Wed, 22 Apr 2026 23:42:43 +0000

Faz 8 meses que coloquei consulta de CNPJ no caminho crítico de um produto. Escrevo isso pra passar pra frente o que ninguém te conta antes de subir pra produção.

Contexto rápido

Uso: fluxo de onboarding B2B, consulta no cadastro e em re-validações periódicas
Volume: cerca de 150 mil consultas/mês, com picos de 3x nas segundas
Latência: parte da experiência depende disso, então acima de 2s começa a machucar conversão

O que eu achei que ia funcionar

Comecei do jeito óbvio: bati direto numa API pública gratuita. Funciona muito bem até não funcionar. O que vi, na ordem em que fui descobrindo:

Rate limit é o menor dos problemas. Dá pra contornar com fila e cache. O problema de verdade é o provider ficar instável por 20 minutos no meio do dia útil, sem status page, sem aviso.
Dados "completos" não são iguais entre providers. QSA (sócios) vem em um, Simples vem em outro, CNAE secundário vem só em metade deles. Acabei precisando compor resposta de mais de uma fonte.
Frescor dos dados varia MUITO. Uma mesma consulta retorna situações cadastrais diferentes dependendo de quando o provider atualizou a base da Receita. Isso vira bug silencioso.

O que eu implementaria de novo desde o dia 1

1. Cache com TTL por tipo de dado

Nome e endereço mudam raramente. Situação cadastral muda sem avisar. Tratei tudo com o mesmo TTL no começo e paguei o preço. Hoje uso 30 dias pra dados "estáveis" e 24h pra situação cadastral.

2. Fallback entre providers, não failover

Failover (troca quando cai) chega atrasado. Fallback (race entre dois providers, fica com o primeiro que responde ok) deu latência muito melhor no p95. Custo extra foi pequeno perto da dor que evitou.

3. Normalização na camada de integração

Cada provider tem schema próprio. Construí um tipo interno único, com todos os campos opcionais, e um adapter por provider. Isso isolou o resto do código de qualquer troca posterior.

4. Logar o provider que atendeu cada consulta

Sem isso, você não consegue debugar "por que esse cadastro ficou com razão social diferente semana passada?".

Erros que custaram caro

Assumir que CNPJ inválido é erro 4xx uniforme. Não é. Cada provider trata de um jeito. Teve provider devolvendo 200 com body vazio.
Confiar na situação cadastral sem timestamp. Hoje eu guardo consultado_em junto com o registro.
Não ter rate limit do meu lado. Um bug de retry em loop torrou cota em 15 minutos.

Observações sobre as opções que testei

Sem ranquear, só o que senti:

Gratuitas públicas: ótimas pra começar, ruins pra volume. Se o produto depende de CNPJ, você vai sair delas.
Pagas: pagou, funcionou na maioria dos casos. Olha contrato, SLA real (não o anunciado) e suporte técnico antes de fechar.
Base local da Receita: é uma opção legítima se você aceita o custo operacional de manter ETL mensal. Não era o meu caso.

Se eu pudesse voltar no tempo

Colocaria cache + fallback desde a primeira linha. Todo o resto foi consequência de não ter feito isso no dia 1.

Se você tá começando agora, escolhe dois providers diferentes, põe cache na frente, e começa a logar o que cada um devolve. O resto você aprende na dor, ou pula essa parte usando algo como cnpj-api.com, que foi o que acabei construindo depois dessa jornada.

DEV Community: Verissimo Ribeiro