cnpj.ia.br
docs · base agosto/2026Atualizado em

CNPJ alfanumérico na API

O CNPJ passou a admitir letras nas doze primeiras posições. A API aceita os dois formatos, com ou sem pontuação, e devolve sempre a forma normalizada de 14 caracteres.

Desde 2026 a Receita Federal emite CNPJs alfanuméricos: as oito posições da raiz e as quatro da ordem podem conter letras e dígitos, e os dois dígitos verificadores continuam numéricos. A API aceita o formato antigo e o novo, com ou sem pontuação, normaliza para 14 caracteres e devolve cnpj sempre nessa forma. Nada muda nos endpoints nem nos créditos.

O formato

Parte Posições Conteúdo
Raiz 1 a 8 Letras maiúsculas ou dígitos; identifica a empresa, comum a matriz e filiais (raiz_cnpj)
Ordem 9 a 12 Letras maiúsculas ou dígitos; identifica o estabelecimento
Dígitos verificadores 13 e 14 Sempre numéricos, calculados por módulo 11 sobre o valor ASCII menos 48 de cada uma das doze primeiras posições

Um CNPJ numérico é um caso particular do alfanumérico: os que já existem não mudam. A validação é a do contrato: o campo Cnpj aceita ^[A-Za-z0-9.\-/]{14,18}$ antes da normalização, e os exemplos declarados são 00000000000191, 00.000.000/0001-91, 12.ABC.345/01DE-35.

O que a API faz

  • Aceita letras minúsculas na entrada e as converte para maiúsculas.
  • Remove pontos, barra e hífen antes de validar.
  • Valida os dígitos verificadores pelo algoritmo alfanumérico, que coincide com o antigo quando só há dígitos.
  • Devolve data.cnpj e data.raiz_cnpj normalizados, sem pontuação e em maiúsculas.
  • Formato ou dígito inválido responde 400 invalid_cnpj, sem custo; CNPJ válido inexistente responde 404 not_found.
curl 
# numérico, com e sem pontuação: a mesma empresa
curl "https://api.cnpj.ia.br/v1/cnpjs/00000000000191" -H "Authorization: Bearer $CNPJIA_KEY"
curl "https://api.cnpj.ia.br/v1/cnpjs/00.000.000/0001-91" -H "Authorization: Bearer $CNPJIA_KEY"

# alfanumérico (exemplo de formato do contrato)
curl "https://api.cnpj.ia.br/v1/cnpjs/12.ABC.345/01DE-35" -H "Authorization: Bearer $CNPJIA_KEY"

O que muda no seu sistema

  • Colunas e validações que assumem 14 dígitos numéricos passam a aceitar letras nas doze primeiras posições. Guarde como texto, não como número.
  • Máscaras de entrada com ##.###.###/####-## precisam aceitar letras nas posições da raiz e da ordem.
  • Comparações devem ser feitas na forma normalizada que a API devolve: maiúsculas, sem pontuação.
  • O dígito verificador calculado por módulo 11 sobre dígitos continua correto para CNPJs numéricos, mas rejeita os alfanuméricos; atualize a rotina para usar o valor ASCII menos 48 de cada caractere.

Relacionados

Perguntas frequentes

Os CNPJs que já existem vão mudar?

Não. O formato alfanumérico vale para inscrições novas; as existentes continuam numéricas e válidas. Um CNPJ só com dígitos é um caso particular do formato novo.

Posso mandar o CNPJ em minúsculas?

Sim. A API converte para maiúsculas e remove a pontuação antes de validar. A resposta traz sempre a forma normalizada: 14 caracteres, maiúsculas, sem pontuação.

Minha validação antiga de dígito verificador vai quebrar?

Para CNPJs numéricos continua certa. Para os alfanuméricos ela rejeita entradas válidas, porque letras não entram na soma. O algoritmo novo usa o valor ASCII de cada caractere menos 48, o que reproduz o cálculo antigo quando só há dígitos.

A busca e o MCP aceitam o formato novo?

Sim. A normalização é a mesma em toda a API, e o servidor MCP usa a mesma API. Filtros da busca não recebem CNPJ; a paginação ordena pela forma normalizada.