Como consultar um CNPJ por API sem quebrar sua integração
Os três erros que mais derrubam integração de consulta de CNPJ, e como evitar cada um antes de ir para produção.
Equipe Radar Data API CNPJ integração
Consultar um CNPJ por API parece a parte fácil do projeto: uma chamada HTTP, um JSON de volta. Na prática, o que derruba integração raramente é a chamada. É o que acontece ao redor dela.
Estes são os três tropeços que mais aparecem, na ordem em que costumam doer.
1. Tratar lentidão como falha
Consultas de CNPJ não têm todas o mesmo tempo de resposta. Um cadastro básico volta em cerca de um segundo. Uma consulta que precisa montar o quadro societário pode levar bem mais, porque o tempo cresce com o número de sócios.
O erro clássico é fixar um timeout curto, calibrado na consulta mais rápida, e descobrir em produção que empresas grandes estouram o limite. Pior: o pedido continua sendo processado do outro lado, então você paga por uma consulta cuja resposta jogou fora.
O que fazer: calibre o timeout pela consulta mais lenta que você usa, com folga. E o que não precisa aparecer na tela agora vai para fila.
2. Pedir mais dado do que o fluxo usa
É tentador começar pela consulta mais completa. Ela traz tudo, e tudo é melhor que pouco, certo?
Nem sempre. Se o seu fluxo só precisa saber se a empresa existe e está ativa, pagar pelo relatório completo é jogar dinheiro fora em toda chamada, e ainda deixa o fluxo mais lento, porque a consulta completa demora mais.
O que fazer: liste os campos que o seu código realmente lê. Se nenhum deles vem do quadro societário, você não precisa da consulta que traz o quadro societário.
Um padrão que funciona bem: comece barato e só aprofunde quando o resultado pedir. Cadastro básico em toda entrada, consulta completa só quando o cadastro indicar que vale a pena olhar mais fundo.
3. Confundir “não encontrado” com “deu erro”
Um CNPJ válido que não tem registro na fonte não é uma falha da integração. É uma resposta de negócio, e seu código precisa saber diferenciar.
Quem joga tudo no mesmo catch acaba com duas consequências ruins: o alerta
de erro dispara no meio da madrugada por um caso normal, e o usuário final
recebe “erro ao consultar” quando a mensagem certa seria “não encontramos
registro para este CNPJ”.
O que fazer: trate por código, não por exceção genérica. Documento inválido, falta de permissão e fonte indisponível são caminhos diferentes, e cada um pede uma reação diferente.
O resumo
Antes de ir para produção, responda três perguntas:
- Qual é o timeout, e ele foi calibrado pela consulta mais lenta?
- Todos os campos que eu pago são lidos pelo meu código?
- O que o usuário vê quando o documento é válido mas não há registro?
Se as três têm resposta, a integração vai bem.
Quer ver as opções de consulta de CNPJ e o preço de cada uma? Elas estão em consultas de Pessoa Jurídica.
Quer testar na prática?
A conta é gratuita e o ambiente de teste não consome crédito.