Pular para o conteúdo
Uso: API de CNPJ alfanumérico

API de CNPJ alfanumérico: o novo formato aceito desde o primeiro dia

O CNPJ alfanumérico mantém os 14 caracteres, mas as 12 primeiras posições passam a aceitar letras e números. O ProCNPJ nasceu com esse formato: o campo cnpj aceita os dois, com ou sem máscara, sem versão nova da API.

Criar conta Ver a documentação

O cadastro está em piloto, por convite: para participar, fale com a gente.

Como encaixar

A consulta no seu fluxo, em três momentos

Entenda a regra

As 12 primeiras posições aceitam letras de A a Z e números. Os 2 dígitos verificadores continuam numéricos. No cálculo, cada caractere vale o seu código ASCII menos 48: 0 a 9 valem 0 a 9, A vale 17, B vale 18, até Z, que vale 42. Os pesos e o módulo 11 são os de sempre.

Prepare o seu sistema

Guarde o CNPJ como texto de 14 caracteres, e não como número. Troque a validação que só aceita dígitos por uma que aceite letras nas 12 primeiras posições.

Teste no sandbox

Com uma chave de teste, envie 12.ABC.345/01DE-35, um CNPJ alfanumérico sintético e válido. O décimo segundo caractere é uma letra, então a consulta volta como situação ativa.

Sem exagero

O que a consulta resolve e o que ela não resolve

A consulta de CNPJ é uma etapa de validação cadastral. Saber onde ela termina evita apoiar uma decisão em algo que ela não prova.

O que resolve

  • Aceita CNPJ alfanumérico e numérico no mesmo campo, com ou sem máscara.
  • Valida os dígitos verificadores pela regra nova antes de a consulta entrar na fila: CNPJ mal formado volta como erro 400, sem custo.
  • Converte letras minúsculas em maiúsculas na entrada.
  • Devolve o CNPJ formatado na resposta, no padrão 00.000.000/0000-00, também quando há letras.
  • Traz CNPJs de teste prontos no sandbox, numéricos e alfanumérico, com dígitos verificadores corretos.

O que não resolve

  • Não converte CNPJ numérico em alfanumérico: os CNPJs que já existem continuam valendo como são.
  • Não adapta o seu banco de dados nem as suas telas: a coluna numérica e a máscara só de dígitos precisam ser ajustadas no seu sistema.
  • Não faz consulta em lote: cada chamada consulta um CNPJ.
Na prática

Uma chamada para criar, dois desfechos possíveis

Você envia só o CNPJ. A consulta é assíncrona e o aviso chega por webhook assinado, sem dado cadastral no corpo.

found
CNPJ encontrado. O CNPJ existe no cadastro. O resultado vem completo, com a situação cadastral.
not_found
CNPJ não encontrado. O número passa na conta dos dígitos verificadores, mas não existe no cadastro.
cURLPOST /v1/consultations
curl -X POST https://api.procnpj.com.br/v1/consultations \
  -H "Authorization: Bearer pcnpj_test_..." \
  -H "Content-Type: application/json" \
  -d '{"cnpj": "12.ABC.345/01DE-35",
       "external_reference": "cadastro-8841"}'

# Resultado, no sandbox (GET /v1/consultations/{id})
{"status": "done",
 "outcome": "found",
 "cnpj": "12.ABC.345/01DE-35",
 "result": {
   "legal_name": "EMPRESA DE EXEMPLO LTDA",
   "registration_status": "ativa",
   "opening_date": "2010-05-03",
   "main_activity": "62.01-5-01 - Desenvolvimento de programas...",
   "address": {"city": "SAO PAULO", "state": "SP", ...}, ...
 }
}
Perguntas frequentes

Dúvidas sobre este uso

O que é o CNPJ alfanumérico?
É o formato de CNPJ que usa letras e números. Ele continua com 14 caracteres: as 12 primeiras posições aceitam letras de A a Z e números, e os 2 dígitos verificadores continuam numéricos. Os CNPJs numéricos que já existem não mudam.
Como calcular o dígito verificador do CNPJ alfanumérico?
Cada caractere vale o seu código ASCII menos 48. Assim, os números de 0 a 9 valem de 0 a 9, a letra A vale 17, B vale 18, e assim até Z, que vale 42. O restante do cálculo é o mesmo do CNPJ numérico: os mesmos pesos e o módulo 11.
A API do ProCNPJ aceita CNPJ alfanumérico?
Sim, desde o primeiro dia. O campo cnpj de POST /v1/consultations aceita CNPJ numérico e alfanumérico, com ou sem máscara. Os dígitos verificadores são validados antes de a consulta entrar na fila.
Quais CNPJs posso usar para testar?
No sandbox, use 12.ABC.345/01DE-35 para o formato alfanumérico e 11.222.333/0006-96 para o numérico: os dois voltam como situação ativa. Para os outros cenários, o décimo segundo caractere escolhe o resultado: 11.222.333/0000-09 não é encontrado, 11.222.333/0002-62 volta baixada, 11.222.333/0003-43 suspensa, 11.222.333/0004-24 inapta, 11.222.333/0005-05 nula e 11.222.333/0009-39 simula uma falha.
Preciso mudar a minha integração para o CNPJ alfanumérico?
Na chamada ao ProCNPJ, não: o campo e o endpoint são os mesmos. No seu sistema, confira se o CNPJ é guardado como texto e se a validação e as máscaras aceitam letras.
Outros usos

A mesma consulta em outros fluxos

Onboarding de pessoa jurídica (KYB)

A primeira pergunta do cadastro de uma empresa respondida por API: o CNPJ existe, está ativo e a razão social bate?

Ver este uso

Emissão de nota fiscal e validação fiscal

Situação cadastral, razão social e endereço do cliente conferidos antes de a nota ser emitida.

Ver este uso

Homologação de fornecedores

Situação cadastral, tempo de empresa, atividade e endereço do fornecedor antes de fechar o contrato.

Ver este uso

Autopreenchimento de cadastro

O cliente digita o CNPJ e o formulário recebe razão social, nome fantasia, endereço e atividade.

Ver este uso

Teste este fluxo no sandbox

Crie a conta, gere uma chave de teste e simule cada cenário pelo décimo segundo caractere do CNPJ. Sem custo e sem consumir cota.

Criar conta Falar com a gente