Como integrar dados cadastrais empresariais ao seu sistema

A integração de dados cadastrais de empresas em um sistema existente envolve passos bem definidos: autenticação, chamada ao endpoint, processamento da resposta e tratamento de erros. Com uma API de consulta CNPJ bem documentada, esse processo costuma levar horas, não dias.

Este guia cobre o fluxo técnico básico de integração, com exemplos práticos.

1. Autenticação

A maioria das APIs de consulta CNPJ usa autenticação por Bearer token no header Authorization. O token é fornecido após a criação de conta ou contratação do plano.

curl -X GET "https://api.exemplo.com/api/v1/cnpj/00000000000100" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Guarde o token em variáveis de ambiente, nunca no código-fonte. Use process.env.CNPJ_API_KEY (Node.js) ou o equivalente na sua stack.

2. Chamada ao endpoint

O endpoint padrão recebe o CNPJ como parâmetro de URL. O formato esperado é 14 dígitos numéricos:

GET /api/v1/cnpj/{cnpj}

Passe sempre o CNPJ sem máscara (apenas dígitos) e faça a formatação visual no frontend quando necessário.

3. Processamento da resposta JSON

A resposta retorna um objeto JSON com os campos disponíveis para o CNPJ consultado:

{
  "cnpj": "00.000.000/0001-00",
  "razao_social": "EMPRESA EXEMPLO LTDA",
  "situacao_cadastral": "ATIVA",
  "data_abertura": "2010-01-01",
  "cnae_principal": {
    "codigo": "6201-5/01",
    "descricao": "Desenvolvimento de programas de computador sob encomenda"
  },
  "endereco": {
    "municipio": "São Paulo",
    "uf": "SP"
  }
}

Trabalhe sempre com chaves nomeadas, não com a ordem dos campos. Isso garante compatibilidade mesmo que a ordem do JSON mude.

4. Mapeamento para o modelo interno

Crie uma função de mapeamento que converta o retorno da API para o modelo do seu sistema:

function mapCnpjApiToCompany(apiResponse) {
  return {
    nome: apiResponse.razao_social,
    nomeFantasia: apiResponse.nome_fantasia,
    situacaoCadastral: apiResponse.situacao_cadastral,
    cnaeCode: apiResponse.cnae_principal?.codigo,
    municipio: apiResponse.endereco?.municipio,
    uf: apiResponse.endereco?.uf,
    validadoEm: new Date().toISOString(),
  };
}

5. Tratamento de erros

Preveja ao menos estes cenários de erro:

• CNPJ inválido: valide o formato antes de chamar a API (14 dígitos numéricos)
• CNPJ não encontrado: a empresa pode não existir na base; trate com mensagem adequada ao usuário
• Timeout: defina um timeout razoável (3-10s) e trate como erro temporário com retry
• Erro 429 (rate limit): implemente retry com backoff exponencial
• Erro 5xx: trate como indisponibilidade temporária; use fallback se houver

6. Cache para otimização

Para dados que não mudam com frequência, implemente cache com TTL adequado:

• Razão social, data de abertura, natureza jurídica: dados estáveis, cache de horas ou dias
• Situação cadastral: pode mudar; cache mais curto ou sem cache para casos críticos

7. Log e auditoria

Registre cada consulta realizada:

await auditLog.record({
  cnpj: cnpj,
  status: response.status,
  timestamp: new Date().toISOString(),
  source: "onboarding-form",
});

Isso facilita debugging, auditoria de compliance e controle do volume de uso por mês.

Próximos passos

Para referência completa dos campos, códigos de status e exemplos de resposta, consulte a documentação técnica da API. Para avaliar planos e volume mensal, veja as opções disponíveis em preços.