Autenticação

Todas as chamadas utilizam autenticação por token no header Authorization. O token é informado no formato Bearer e varia conforme ambiente e plano contratado.

Authorization: Bearer SUA_CHAVE_API

Endpoint de consulta

O endpoint abaixo representa a rota principal para consulta individual de CNPJ:

GET /api/v1/cnpj/{cnpj}

Formato esperado do parâmetro: 14 dígitos numéricos, com ou sem máscara no processamento de entrada do cliente.

Parâmetros

• cnpj: identificador da empresa consultada.
• Authorization: token de autenticação do ambiente.
• X-Correlation-Id: cabeçalho opcional recomendado para rastreamento.

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

Exemplo de resposta

{
  "cnpj": "00.000.000/0001-00",
  "razao_social": "EMPRESA EXEMPLO LTDA",
  "nome_fantasia": "EMPRESA EXEMPLO",
  "situacao_cadastral": "ATIVA",
  "data_abertura": "2010-01-01",
  "natureza_juridica": "206-2 - Sociedade Empresária Limitada",
  "porte": "DEMAIS",
  "cnae_principal": {
    "codigo": "6201-5/01",
    "descricao": "Desenvolvimento de programas de computador sob encomenda"
  },
  "endereco": {
    "logradouro": "Avenida Exemplo",
    "numero": "100",
    "municipio": "São Paulo",
    "uf": "SP"
  }
}

Os campos retornados podem variar conforme disponibilidade da fonte de dados e modalidade contratada.

Códigos de status

• 200: consulta processada com retorno disponível.
• 400: requisição inválida, como CNPJ mal formatado.
• 401: token ausente, inválido ou expirado.
• 404: consulta sem retorno disponível para o identificador informado.
• 429: limite de taxa temporariamente excedido.
• 500: falha interna ou indisponibilidade transitória.

Erros comuns

• Enviar o CNPJ com caracteres inesperados e sem normalização adequada.
• Usar token de sandbox em produção ou vice-versa.
• Não tratar respostas parciais quando um campo específico estiver indisponível.
• Ignorar retentativas controladas em cenários de instabilidade transitória.

Boas práticas

• Persistir apenas os campos necessários para o processo de negócio.
• Registrar correlação das chamadas para auditoria operacional.
• Aplicar cache ou reconsulta conforme a criticidade do dado no fluxo.
• Separar claramente ambientes de sandbox e produção.

Ambientes e rate limit

Sandbox: ambiente para validação de integração, payloads de exemplo e testes iniciais.

Produção: ambiente voltado para operação real, sujeito às condições comerciais contratadas.

Rate limit fictício: 60 requisições por minuto no sandbox e limites customizados em produção conforme plano.