--- title: "API de CNPJ para onboarding de PJ" description: "Valide o CNPJ no cadastro em uma chamada: existência, situação cadastral e sua data, matriz ou filial, razão social e endereço. Aceita alfanumérico." canonical: "https://cnpj.ia.br/api-cnpj-para-onboarding" date_modified: 2026-09-03 source: "cnpj.ia.br" --- para quem cadastra clientes PJ · base agosto/2026 # API de CNPJ para onboarding de PJ Valide o CNPJ no cadastro em uma chamada: existência, situação cadastral e sua data, matriz ou filial, razão social e endereço. Aceita alfanumérico. [Criar chave grátis](https://app.cnpj.ia.br/signup) [CNPJ alfanumérico](https://cnpj.ia.br/docs/cnpj-alfanumerico) No cadastro de um cliente pessoa jurídica, a pergunta é simples: esse CNPJ existe, qual é a situação cadastral e quais dados estão registrados na Receita Federal? Uma consulta `basic` (1 crédito) responde com situação cadastral e sua data, matriz ou filial, razão social, nome fantasia, endereço e natureza jurídica, na base da Receita Federal de agosto/2026. CNPJ malformado ou inexistente custa 0. ## O fluxo em três passos 1. Normalize e consulte Envie o CNPJ como o usuário digitou, com ou sem pontuação, numérico ou alfanumérico. A API normaliza e valida o dígito verificador. ``` GET /v1/cnpjs/00.000.000/0001-91 ``` 2. Decida pela situação, não pelo 200 situacao_cadastral.codigo diz se a empresa está ativa; data_situacao_cadastral e matriz_filial contextualizam. Preencha razão social e endereço do cadastro. ``` data.situacao_cadastral.codigo == "02" → Ativa ``` 3. Trate os três resultados do cadastro 400 invalid_cnpj é formato ou dígito errado; 404 not_found é CNPJ válido que não existe; nenhum dos dois consome crédito. Só o 200 é cobrado, no peso do perfil. ``` 400 invalid_cnpj · 404 not_found · 200 → cobrado no peso do basic ``` ## Código pronto #### Python ```python import os, requests HEADERS = {"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"} def validar_cnpj(cnpj_digitado: str) -> dict: cnpj = "".join(ch for ch in cnpj_digitado if ch.isalnum()) # tira pontuação: "/" quebraria a rota r = requests.get(f"https://api.cnpj.ia.br/v1/cnpjs/{cnpj}", headers=HEADERS, timeout=10) if r.status_code == 400: return {"ok": False, "motivo": "CNPJ inválido"} if r.status_code == 404: return {"ok": False, "motivo": "CNPJ não encontrado na base"} r.raise_for_status() d = r.json()["data"] return { "ok": d["situacao_cadastral"]["codigo"] == "02", "situacao": d["situacao_cadastral"]["descricao"], "desde": d["data_situacao_cadastral"], "razao_social": d["razao_social"], "matriz": d["matriz_filial"]["descricao"], "cidade": f'{d["endereco"]["municipio"]}/{d["endereco"]["uf"]}', } ``` #### Node ```javascript const headers = { Authorization: `Bearer ${process.env.CNPJIA_KEY}` }; async function validarCnpj(cnpjDigitado) { const res = await fetch(`https://api.cnpj.ia.br/v1/cnpjs/${encodeURIComponent(cnpjDigitado)}`, { headers }); if (res.status === 400) return { ok: false, motivo: "CNPJ inválido" }; if (res.status === 404) return { ok: false, motivo: "CNPJ não encontrado na base" }; if (!res.ok) throw new Error(`HTTP ${res.status}`); const { data: d } = await res.json(); return { ok: d.situacao_cadastral.codigo === "02", situacao: d.situacao_cadastral.descricao, desde: d.data_situacao_cadastral, razaoSocial: d.razao_social, matriz: d.matriz_filial.descricao, cidade: `${d.endereco.municipio}/${d.endereco.uf}`, }; } ``` ## Campos mais usados | Campo | Perfil | Descrição | | --- | --- | --- | | [`cnpj`](https://cnpj.ia.br/docs/campos#campo-cnpj) | basic | CNPJ do estabelecimento, 14 caracteres sem pontuação, com zeros à esquerda. Vem da Receita Federal; aceita entrada numérica ou alfanumérica, com ou sem pontuação. | | [`razao_social`](https://cnpj.ia.br/docs/campos#campo-razao_social) | basic | Nome empresarial registrado na Receita Federal. É o único nome sempre presente. | | [`nome_fantasia`](https://cnpj.ia.br/docs/campos#campo-nome_fantasia) | basic | Nome fantasia declarado para o estabelecimento, na Receita Federal. `null` quando a empresa não declarou. | | [`situacao_cadastral.codigo`](https://cnpj.ia.br/docs/campos#campo-situacao_cadastral.codigo) | basic | Código da situação cadastral do estabelecimento na Receita Federal, com dois dígitos. É o campo que diz se a empresa está ativa. | | [`situacao_cadastral.descricao`](https://cnpj.ia.br/docs/campos#campo-situacao_cadastral.descricao) | basic | Descrição da situação cadastral, traduzida do código pela tabela de domínio da Receita Federal. | | [`data_situacao_cadastral`](https://cnpj.ia.br/docs/campos#campo-data_situacao_cadastral) | basic | Data do evento que gerou a situação cadastral atual, campo da Receita Federal. | | [`matriz_filial.descricao`](https://cnpj.ia.br/docs/campos#campo-matriz_filial.descricao) | basic | Descrição do código de matriz/filial, traduzida pela tabela de domínio da Receita Federal. | | [`data_inicio_atividade`](https://cnpj.ia.br/docs/campos#campo-data_inicio_atividade) | basic | Data de início de atividade do estabelecimento (abertura), campo da Receita Federal, em formato ISO `YYYY-MM-DD`. | | [`endereco.municipio`](https://cnpj.ia.br/docs/campos#campo-endereco.municipio) | basic | Nome do município de jurisdição do estabelecimento, traduzido pela tabela de municípios da Receita Federal. | | [`endereco.uf`](https://cnpj.ia.br/docs/campos#campo-endereco.uf) | basic | Sigla da unidade da federação do estabelecimento, campo da Receita Federal. | | [`natureza_juridica.descricao`](https://cnpj.ia.br/docs/campos#campo-natureza_juridica.descricao) | basic | Nome da natureza jurídica, traduzido do código pela tabela de domínio da Receita Federal. | | [`simples.optante`](https://cnpj.ia.br/docs/campos#campo-simples.optante) | basic | Indica opção pelo Simples Nacional, dos dados do Simples publicados pela Receita Federal. `null` quando o indicador vem em branco (caso ‘outros’ do layout). | ## O que muda com o CNPJ alfanumérico Desde 2026 a Receita Federal emite CNPJs com letras nas doze primeiras posições. A API aceita o formato antigo e o novo, com ou sem pontuação, e devolve `cnpj` sempre normalizado. No seu cadastro, guarde como texto, aceite letras na máscara e valide o dígito verificador pelo algoritmo novo, que continua correto para os numéricos. Detalhes em [CNPJ alfanumérico](https://cnpj.ia.br/docs/cnpj-alfanumerico). ## Decisões que o código deve tomar - **Ativa é `02`**: os demais códigos de `situacao_cadastral` (nula, suspensa, inapta, baixada) estão na tabela de [Campos da resposta](https://cnpj.ia.br/docs/campos#enum-situacao_cadastral); `motivo_situacao_cadastral` explica o porquê. - **Filial não é erro**: `matriz_filial` diz se o CNPJ é o estabelecimento principal; `raiz_cnpj` liga matriz e filiais. - **Data da base**: `meta.data_as_of` é a foto mensal que respondeu. Uma empresa aberta este mês pode ainda não constar; trate `404 not_found` como “não encontrada na base de agosto/2026”, não como inexistente. - **Sem CPF**: o cadastro PJ não recebe dado de pessoa física além do quadro societário público, no perfil `full`, se você precisar dele. ## Tier indicado **Free** é o plano indicado: este fluxo não usa a busca de empresas. - 60 créditos por mês - 3 requisições por minuto [Todos os planos, os pesos por operação e os pacotes avulsos](https://cnpj.ia.br/precos) ## Perguntas frequentes **A consulta valida o dígito verificador?** Sim. Formato ou dígito inválido responde `400 invalid_cnpj`, sem consumir crédito, tanto para CNPJ numérico quanto alfanumérico. Um `200` já significa que o CNPJ é válido e existe na base. **Um CNPJ que não existe consome crédito?** Não. `404 not_found` não consome crédito, como todo erro. Só respostas `200` são cobradas; validar cadastros com muitos CNPJs errados não gasta a franquia. **Como sei se a empresa está ativa?** Pelo código `02` em `situacao_cadastral.codigo`. Os demais códigos e o `motivo_situacao_cadastral` seguem as tabelas da Receita Federal publicadas em `/docs/campos`; `data_situacao_cadastral` diz desde quando. **Uma empresa aberta esta semana aparece?** Depende da carga mensal. A base é a foto dos dados abertos da Receita Federal com a data em `meta.data_as_of`; uma inscrição nova entra na próxima carga. Trate `404` como não encontrada na base dessa data. **O cadastro precisa aceitar CNPJ com letras?** Sim, para inscrições novas. A API aceita os dois formatos e normaliza; do seu lado, guarde o CNPJ como texto, aceite letras nas doze primeiras posições da máscara e use o algoritmo novo de dígito verificador, que continua válido para os numéricos. **Posso fazer a validação direto do formulário no navegador?** Não com a sua chave, que gastaria os seus créditos em nome de qualquer visitante. Chame a API do seu backend ou de uma função serverless. Os únicos endpoints sem chave são `GET /v1/status` e `GET /v1/demo`, e só eles aceitam CORS. ## Para continuar - [Consulta por CNPJ](https://cnpj.ia.br/docs/consulta-cnpj) - [CNPJ alfanumérico](https://cnpj.ia.br/docs/cnpj-alfanumerico) - [cnpj.ia.br vs ReceitaWS: qual escolher?](https://cnpj.ia.br/comparar/receitaws) [Criar chave grátis](https://app.cnpj.ia.br/signup)