Documentação

API CNPJ Regular

REST, JSON e autenticação por chave. Um endpoint responde a pergunta inteira — federal, estadual e regime tributário — e você paga por esfera apurada.

Gerar minha chave Ver planos

Introdução

A API CNPJ Regular responde uma pergunta só: essa empresa está regular? A resposta consolida a esfera federal, as inscrições estaduais e o regime tributário num relatório único, com veredito, índice de 0 a 100 e a lista de pendências que justificam o resultado.

Item	Valor
URL base	https://api.conectaregular.com.br/v1
Formato	JSON em UTF-8, tanto na requisição quanto na resposta
Autenticação	Cabeçalho Authorization: Bearer cr_live_…
Versionamento	O prefixo /v1 é estável: campos são acrescentados, nunca removidos sem nova versão
Fuso	Todas as datas em ISO 8601, UTC

Autenticação

Toda requisição precisa da sua chave no cabeçalho Authorization. Chaves começam com cr_live_, pertencem a uma organização e são exibidas uma única vez, no momento da criação. Cada chave carrega escopos (consultas:ler, consultas:lote, conta:ler) — um endpoint fora do escopo devolve 403.

cabeçalho

Authorization: Bearer cr_live_sua_chave
Content-Type: application/json

Guarde a chave em segredo

A chave dá acesso ao saldo de créditos da organização. Use variável de ambiente e nunca a exponha no navegador ou no app. Se vazar, revogue pelo painel — a revogação é imediata.

Créditos e custo da consulta

O custo é somado por esfera apurada, e vem explicado em consulta.custo na própria resposta:

O que foi apurado	Custo	Observação
Esfera federal	1 crédito	Sempre cobrada — é a base do relatório.
Cada inscrição estadual	1 crédito por UF	Só as UFs efetivamente apuradas entram na conta.
Regime tributário	0	Vem junto da esfera federal, sem custo adicional.
Reconsulta em cache	0	Mesmo CNPJ, mesma organização, dentro da janela de validade.

Uma consulta completa a uma empresa com inscrição em SP e MG custa, portanto, 3 créditos: 1 federal + 2 estaduais. Para pagar só a federal, mande ?estadual=nao. Consulta que falha na origem não é cobrada — o débito é estornado automaticamente.

custo na resposta

"custo": {
  "creditos": 3,
  "centavos": 0,
  "itens": [
    { "esfera": "federal", "creditos": 1 },
    { "esfera": "estadual", "uf": "MG", "creditos": 1 },
    { "esfera": "estadual", "uf": "SP", "creditos": 1 }
  ]
}

Início rápido

Gere uma chave no painel, exporte-a como variável de ambiente e faça a primeira consulta. Os exemplos abaixo estão prontos para colar.

curl

curl -s "https://api.conectaregular.com.br/v1/cnpj/12345678000195" \
  -H "Authorization: Bearer $CONECTA_REGULAR_KEY"

Consulta individual

GET/v1/cnpj/{cnpj}

Apura a regularidade de um CNPJ e devolve o relatório completo. O envelope traz sempre dois objetos: consulta (identificador, custo, cache e avisos) e resultado (o relatório em si).

Parâmetro	Onde	Obrigatório	Descrição
cnpj	caminho	obrigatório	CNPJ com ou sem máscara. Os dígitos verificadores são validados antes de qualquer cobrança.
estadual	query	opcional	todas (padrão), nao para pular a esfera estadual, ou lista de UFs separadas por vírgula (SP,RJ).
atualizar	query	opcional	true ignora o cache e apura tudo de novo, cobrando normalmente.

resposta 200

{
  "consulta": {
    "id": "6b1f0a2c-9d3e-4f77-8c21-0a5f2d1b7e40",
    "cache": false,
    "custo": {
      "creditos": 3,
      "centavos": 0,
      "itens": [
        { "esfera": "federal", "creditos": 1 },
        { "esfera": "estadual", "uf": "MG", "creditos": 1 },
        { "esfera": "estadual", "uf": "SP", "creditos": 1 }
      ]
    },
    "avisos": []
  },
  "resultado": {
    "cnpj": "12345678000195",
    "cnpjFormatado": "12.345.678/0001-95",
    "emitidoEm": "2026-02-10T13:22:04.000Z",
    "referenciaDados": "2026-02-09T00:00:00.000Z",
    "situacao": "parcial",
    "indice": 82,
    "resumo": "Situação federal ativa, porém com 1 ponto de atenção.",
    "identificacao": {
      "razaoSocial": "Distribuidora Modelo Comércio de Peças Ltda",
      "nomeFantasia": "Modelo Peças",
      "naturezaJuridica": "Sociedade Empresária Limitada",
      "porte": "Empresa de Pequeno Porte",
      "capitalSocial": 450000,
      "inicioAtividade": "2011-10-05",
      "tipoUnidade": "matriz"
    },
    "esferas": {
      "federal": {
        "veredito": "regular",
        "situacao": "Ativa",
        "desde": "2011-10-05",
        "motivo": null,
        "observacao": null
      },
      "estadual": {
        "veredito": "parcial",
        "escopo": "todas",
        "consultadas": ["MG", "SP"],
        "inscricoes": [
          {
            "uf": "SP",
            "inscricao": "111.222.333.444",
            "habilitada": true,
            "situacao": "Sem restrição",
            "regime": "IE Normal",
            "desde": "2011-11-01",
            "veredito": "regular"
          },
          {
            "uf": "MG",
            "inscricao": "001234567.00-89",
            "habilitada": false,
            "situacao": "Baixada",
            "regime": "IE Normal",
            "desde": "2024-06-18",
            "veredito": "irregular"
          }
        ]
      },
      "tributaria": {
        "veredito": "regular",
        "simplesNacional": { "optante": true, "desde": "2012-01-01", "ate": null },
        "mei": { "optante": false, "desde": null, "ate": null }
      }
    },
    "atuacao": {
      "principal": { "codigo": "4530-7/03", "descricao": "Comércio a varejo de peças e acessórios" },
      "secundarias": [
        { "codigo": "4520-0/01", "descricao": "Serviços de manutenção e reparação mecânica" }
      ]
    },
    "localizacao": {
      "logradouro": "Avenida das Indústrias",
      "numero": "1500",
      "complemento": "Galpão 3",
      "bairro": "Distrito Industrial",
      "municipio": "Campinas",
      "uf": "SP",
      "cep": "13052-000"
    },
    "contatos": {
      "telefones": ["(19) 3255-8800"],
      "emails": ["fiscal@modelopecas.com.br"]
    },
    "quadroSocietario": [
      {
        "nome": "Ana Ribeiro Martins",
        "qualificacao": "Sócio-Administrador",
        "desde": "2011-10-05",
        "faixaEtaria": "41 a 50"
      }
    ],
    "pendencias": [
      {
        "codigo": "estadual.mg.inabilitada",
        "esfera": "estadual",
        "severidade": "media",
        "mensagem": "Inscrição estadual 001234567.00-89 (MG) não habilitada: Baixada."
      }
    ],
    "fontes": [
      { "esfera": "federal", "base": "cadastro-federal", "referencia": "2026-02-09T00:00:00.000Z", "coletadoEm": "2026-02-10T13:22:04.000Z" },
      { "esfera": "estadual", "base": "cadastros-estaduais", "referencia": null, "coletadoEm": "2026-02-10T13:22:04.000Z" },
      { "esfera": "tributaria", "base": "regimes-tributarios", "referencia": null, "coletadoEm": "2026-02-10T13:22:04.000Z" }
    ]
  }
}

Escopo estadual

Você decide quais inscrições estaduais quer apurar — e paga só por elas. O relatório devolve em esferas.estadual.escopo como a consulta foi feita e em consultadas a lista exata de UFs cobradas.

Valor	Efeito	Custo estadual
estadual=todas	Apura toda UF em que a empresa tem inscrição (padrão).	1 crédito por UF encontrada
estadual=nao	Pula a esfera estadual: só federal e regime tributário.	0
estadual=SP,RJ	Apura apenas as UFs listadas.	1 crédito por UF listada

Com uma lista explícita, o custo é conhecido antes da chamada à base: se o saldo não cobrir o total, a API recusa com creditos_insuficientes sem gastar nada. Com todas, o número de UFs só aparece depois da apuração — se o saldo acabar no meio, entregamos as UFs cobertas e sinalizamos em consulta.avisos com o código estadual_parcial_por_credito.

apurando só duas UFs

curl -s "https://api.conectaregular.com.br/v1/cnpj/12345678000195?estadual=SP,RJ" \
  -H "Authorization: Bearer $CONECTA_REGULAR_KEY"

Consulta em lote

POST/v1/cnpj/lote

Até 100 CNPJs por chamada. Duplicados são removidos antes da cobrança, cada CNPJ é cobrado individualmente e falhas isoladas não interrompem o lote — só a falta de saldo encerra o processamento. O campo estadual aceita "todas", uma lista de UFs ou [] para pular a esfera estadual.

curl

curl -s "https://api.conectaregular.com.br/v1/cnpj/lote" \
  -H "Authorization: Bearer $CONECTA_REGULAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpjs": ["12345678000195", "98765432000110"],
    "estadual": ["SP", "RJ"]
  }'

resposta 200

{
  "resumo": {
    "solicitados": 2,
    "processados": 2,
    "sucessos": 1,
    "falhas": 1,
    "creditos": 3
  },
  "resultados": [
    {
      "cnpj": "12345678000195",
      "sucesso": true,
      "cache": false,
      "custo": { "creditos": 3, "centavos": 0, "itens": [] },
      "resultado": { "situacao": "parcial", "indice": 82 }
    },
    {
      "cnpj": "98765432000110",
      "sucesso": false,
      "erro": { "codigo": "nao_encontrado", "mensagem": "CNPJ não localizado nas bases oficiais." }
    }
  ]
}

Conta e consumo

GET/v1/conta

Devolve saldo de créditos, dados do plano e o consumo do mês corrente. Não consome crédito — use para montar alertas de saldo antes de disparar um lote grande.

resposta 200

{
  "organizacao": { "nome": "Minha Empresa Ltda", "saldoCreditos": 1245 },
  "plano": {
    "nome": "Pro",
    "creditosMensais": 1500,
    "precoExcedenteCentavos": 12,
    "payPerUseAtivo": true,
    "limitePorMinuto": 180
  },
  "consumoDoMes": { "consultas": 312, "creditosUsados": 421, "excedenteCentavos": 0 }
}

Objeto relatório

O mesmo objeto aparece em resultado na consulta individual, em cada item do lote e no histórico do painel.

Campo	Tipo	Descrição
cnpj / cnpjFormatado	string	Número apurado, sem e com máscara.
emitidoEm	ISO 8601	Quando este relatório foi emitido por nós.
referenciaDados	ISO 8601 \| null	Data de referência do dado cadastral apurado.
situacao	veredito	Veredito consolidado das três esferas.
indice	0–100	Índice de regularidade: 100 sem pendência, caindo conforme a severidade.
resumo	string	Frase pronta para exibir ao usuário final.
identificacao	objeto	Razão social, nome fantasia, natureza jurídica, porte, capital social, início da atividade e tipoUnidade (matriz/filial).
esferas.federal	objeto	Situação cadastral, desde quando, motivo e observação, com veredito próprio.
esferas.estadual	objeto	escopo, consultadas (UFs cobradas) e a lista de inscricoes, cada uma com seu veredito.
esferas.tributaria	objeto	Simples Nacional e MEI, com data de início e fim de opção.
atuacao	objeto	Atividade principal e secundárias (código e descrição).
localizacao	objeto	Endereço completo do estabelecimento apurado.
contatos	objeto	Telefones e e-mails declarados no cadastro.
quadroSocietario	lista	Sócios e administradores com qualificação e data de entrada.
pendencias	lista	O que impede a regularidade, com código estável, esfera e severidade.
fontes	lista	Rastro por esfera: base consultada, referência do dado e momento da coleta.

Vereditos

Cada esfera tem seu veredito e o campo situacao consolida os três — o pior veredito prevalece.

Valor	Significado
regular	Ativa na esfera federal e sem inscrição estadual inabilitada.
parcial	Ativa na esfera federal, mas com ao menos uma pendência estadual.
irregular	Situação cadastral federal suspensa, inapta, baixada ou nula.
indeterminado	Não foi possível confirmar a situação com as bases disponíveis.

Pendências

Toda pendência tem um codigo estável — dá para criar regra em cima dele sem depender do texto. O índice de regularidade cai conforme a severidade acumulada.

Severidade	Quando aparece
alta	Impede a operação: empresa baixada, inapta, suspensa ou nula.
media	Exige atenção: inscrição estadual inabilitada ou situação não informada.
baixa	Informativo: divergência menor que não bloqueia o cadastro.

pendência

{
  "codigo": "estadual.mg.inabilitada",
  "esfera": "estadual",
  "severidade": "media",
  "mensagem": "Inscrição estadual 001234567.00-89 (MG) não habilitada: Baixada."
}

Erros

Toda falha devolve o mesmo envelope: um objeto erro com codigo, mensagem e, quando fizer sentido, detalhes por campo. Trate sempre pelo código, nunca pelo texto.

resposta 402

{
  "erro": {
    "codigo": "creditos_insuficientes",
    "mensagem": "Esta consulta custa 3 crédito(s) e o saldo disponível não cobre o total.",
    "detalhes": []
  }
}

Código	HTTP	Quando acontece
credencial_ausente	401	A requisição chegou sem chave de API.
credencial_invalida	401	Chave inexistente, revogada ou de conta suspensa.
escopo_negado	403	A chave não tem o escopo exigido pelo endpoint.
limite_excedido	429	Limite de requisições por minuto do plano atingido.
creditos_insuficientes	402	Saldo (e excedente, se ativo) não cobre o custo da consulta.
teto_excedente_atingido	402	O teto mensal de gasto com excedente foi alcançado.
consulta_ao_vivo_indisponivel	402	O plano responde apenas pela base oficial e pelo cache.
parametro_invalido	400	Um parâmetro de query não foi reconhecido — por exemplo, uma UF inexistente.
cnpj_invalido	400	O CNPJ informado não passa na validação de dígitos.
corpo_invalido	400	O corpo do POST não é JSON válido ou está fora do formato.
nao_encontrado	404	CNPJ não localizado nas bases oficiais.
fonte_limitada	503	Volume momentaneamente acima do permitido. Tente novamente.
fonte_indisponivel	503	Base de dados indisponível no momento.
tempo_esgotado	504	A base demorou além do tempo limite para responder.

Limites e cache

Cada resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
O limite por minuto vem do plano. Ao estourar, a API responde 429 com Retry-After em segundos.
Reconsultar o mesmo CNPJ dentro da janela de validade devolve o resultado em cache, marcado com consulta.cache = true, sem consumir crédito. O cache só é reaproveitado quando cobre o escopo estadual pedido.
?atualizar=true ignora o cache e apura de novo, cobrando normalmente.
Consultas que falham na origem não consomem crédito — a cobrança é estornada automaticamente.

Fluxo de cadastro

O caso mais comum: bloquear a entrada de um fornecedor ou cliente irregular antes de gravar o cadastro.

node.js

async function podeCadastrar(cnpj) {
  const resposta = await fetch(`https://api.conectaregular.com.br/v1/cnpj/${cnpj}?estadual=SP`, {
    headers: { Authorization: `Bearer ${process.env.CONECTA_REGULAR_KEY}` },
  });

  if (resposta.status === 402) return { permitido: false, motivo: "sem_saldo" };
  if (!resposta.ok) throw new Error(`consulta falhou: ${resposta.status}`);

  const { resultado } = await resposta.json();
  const graves = resultado.pendencias.filter((p) => p.severidade === "alta");

  return {
    permitido: resultado.situacao === "regular" || graves.length === 0,
    indice: resultado.indice,
    pendencias: resultado.pendencias.map((p) => p.mensagem),
  };
}

ERPs e webhooks

Além da API, o painel conecta direto no seu ERP: a integração com o Omie sincroniza clientes e fornecedores e devolve a regularidade de cada CNPJ sem nenhuma linha de código. Monitores acompanham CNPJs escolhidos e disparam evento quando o veredito muda; o webhook recebe o mesmo objeto resultado da API.

webhook — corpo enviado

{
  "evento": "monitor.mudou",
  "ocorridoEm": "2026-02-10T13:22:04.000Z",
  "monitorId": "9f2c…",
  "anterior": "regular",
  "atual": "parcial",
  "resultado": { "cnpj": "12345678000195", "situacao": "parcial", "indice": 82 }
}

Responda 2xx em até 10 segundos. Falhas são reenviadas com backoff; o histórico de entregas fica no painel.

MCP para assistentes de IA

POSThttps://api.conectaregular.com.br/mcp

O mesmo serviço também fala MCP (Model Context Protocol). Ligue o endpoint acima ao Claude Desktop, ao Claude Code ou a qualquer cliente compatível e o assistente passa a consultar regularidade sozinho, com a sua chave de API e o seu saldo — sem você escrever integração nenhuma.

Item	Valor
URL do servidor	https://api.conectaregular.com.br/mcp
Transporte	HTTP streamable (JSON-RPC 2.0 por POST), sem sessão
Autenticação	Cabeçalho Authorization: Bearer cr_live_… — a mesma chave da API
Cobrança	Idêntica à da API: 1 crédito federal + 1 por UF apurada
Histórico	Toda consulta feita pela IA aparece no painel, como qualquer outra

Ferramentas expostas

Ferramenta	Argumentos	O que faz
consultar_regularidade	cnpj, ufs?, atualizar?	Apura um CNPJ e devolve o relatório completo. 1 crédito federal + 1 por UF apurada.
consultar_em_lote	cnpjs[], ufs?	Apura até 20 CNPJs numa chamada. Duplicados são removidos e cada CNPJ é cobrado separadamente.
saldo_de_creditos	—	Saldo da organização, franquia do plano e consumo do mês. Não consome crédito.

O argumento ufs segue a mesma regra do parâmetro estadual da API: omita para apurar todas as inscrições, mande [] para pular a esfera estadual ou liste as siglas (["SP", "RJ"]) para pagar só por elas.

Claude Code

Um comando basta — a chave vai no cabeçalho, como em qualquer chamada da API.

terminal

claude mcp add --transport http conecta-regular \
  https://api.conectaregular.com.br/mcp \
  --header "Authorization: Bearer $CONECTA_REGULAR_KEY"

Claude Desktop e outros clientes

Em clientes com suporte nativo a servidores MCP remotos, declare o servidor no bloco mcpServers da configuração:

claude_desktop_config.json

{
  "mcpServers": {
    "conecta-regular": {
      "type": "http",
      "url": "https://api.conectaregular.com.br/mcp",
      "headers": {
        "Authorization": "Bearer cr_live_sua_chave"
      }
    }
  }
}

Se o seu cliente ainda só aceita servidores locais, use a ponte mcp-remote, que fala HTTP do lado de cá e stdio do lado de lá:

claude_desktop_config.json — via mcp-remote

{
  "mcpServers": {
    "conecta-regular": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.conectaregular.com.br/mcp",
        "--header", "Authorization: Bearer cr_live_sua_chave"
      ]
    }
  }
}

Reinicie o cliente e peça algo como "confira se o CNPJ 12.345.678/0001-95 está regular". Erros de negócio — saldo insuficiente, CNPJ inválido, limite por minuto — voltam como resultado de ferramenta em português, com o mesmo código da API, para o assistente explicar o que aconteceu em vez de travar.

A chave dá acesso ao seu saldo

Um assistente conectado pode consultar por conta própria e consumir créditos. Gere uma chave só para essa finalidade no painel — assim dá para acompanhar o consumo em separado e revogar quando quiser.

Boas práticas

Peça só o que vai usar. Se a sua regra olha apenas a inscrição de SP, mande estadual=SP e pague 2 créditos em vez de apurar o país inteiro.
Guarde o relatório. A resposta é o documento da decisão — armazene o JSON junto do cadastro para auditoria.
Trate 402 e 429 com calma. Ambos são temporários: 402 pede saldo, 429 pede espera. Nenhum dos dois deve derrubar seu fluxo.
Use lote para carga inicial e monitores para o dia a dia — reconsultar a base inteira toda semana desperdiça crédito.
Consulte /v1/conta antes de lotes grandes e derive o custo: 1 crédito por CNPJ mais 1 por UF que você pedir.

Ficou faltando alguma coisa?

A gente escreve o exemplo na sua linguagem e ajuda no primeiro cadastro.

Falar com a equipe