API CNPJ Regular

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.

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.

Authorization: Bearer cr_live_sua_chave
Content-Type: application/json

Créditos e custo da consulta

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

Sem parâmetro nenhum a consulta custa 1 crédito: a esfera estadual é o único item cujo preço depende de quantas inscrições a empresa tem, então ela só é apurada quando você pede. Com ?estadual=todas, uma empresa com inscrição em SP e MG custa 3 créditos: 1 federal + 2 estaduais. Para pagar só as inscrições estaduais, mande ?federal=false. Consulta que falha na origem não é cobrada — o débito é estornado automaticamente.

"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 -s "https://api.conectaregular.com.br/v1/cnpj/12345678000195" \
  -H "Authorization: Bearer $CONECTA_REGULAR_KEY"

Consulta individual

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).

{
  "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.

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.

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

Escopo e frescor do dado

Cada esfera é opcional e cobrada à parte, e o relatório sempre diz de onde veio cada informação: o campo fontes[].emCache marca o que foi reaproveitado em vez de apurado na hora, e fontes[].referencia diz de quando é o retrato. Dado vindo da base oficial em disco vem sempre marcado como reaproveitado.

Sem idade_maxima_dias, a consulta é apurada ao vivo na origem: nenhum retrato guardado responde por ela, nem o nosso nem o da fonte. Aceitar dado guardado é uma escolha explícita — é ela que reduz o custo, e é ela que abre mão do agora.

Com federal=false, a identificação da empresa vem da base oficial que carregamos todo mês. Se o CNPJ ainda não constar dela, a consulta segue mesmo assim: as inscrições estaduais são apuradas normalmente, os campos de identificação saem vazios e a resposta traz o aviso identificacao_nao_apurada — preferimos declarar o que não foi apurado a inventar razão social a partir do cadastro estadual, e a cobrança continua sendo só das UFs pedidas.

curl -s "https://api.conectaregular.com.br/v1/cnpj/12345678000195?federal=false&estadual=SP&idade_maxima_dias=7" \
  -H "Authorization: Bearer $CONECTA_REGULAR_KEY"

Consulta em 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. Os mesmos extras da consulta individual valem aqui, no corpo: federal, simples, suframa e idadeMaximaDias.

Mande os 100 de uma vez: o ritmo contra as bases oficiais é controlado do nosso lado, e você não precisa dividir em blocos nem espaçar chamadas. Em compensação um lote cheio de dados ainda não apurados leva minutos, não segundos — configure o timeout do seu cliente com folga (5 minutos cobrem o pior caso). Se a conexão cair antes do fim, os CNPJs que ainda não tinham começado não são consultados nem cobrados.

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"]
  }'

{
  "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

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.

{
  "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.

Vereditos

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

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.

{
  "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.

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

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.
• A entrada é sempre um CNPJ. Não existe busca reversa por CPF, por nome de sócio ou por endereço — nem na API, nem no painel, nem no MCP.

Fluxo de cadastro

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

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.

O monitor federal é mensal e não custa crédito. Ele compara o retrato da Receita Federal que já está na nossa base e lê as mudanças detectadas pela carga — que acontece quando a Receita publica, uma vez por mês. Escolher intervalo de 6 h não torna a fonte mais frequente: adianta apenas a leitura de uma publicação que ainda não saiu. Para apuração no instante da decisão, use a consulta — ela vai à fonte e cobra o crédito correspondente.

{
  "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

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.

Ferramentas expostas

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.

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:

{
  "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á:

{
  "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.

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.