verCNPJ

DOCUMENTAÇÃO · VERSÃO 1.0.0

API do VerCNPJ

Mande o CNPJ com a sua chave e receba a empresa inteira em JSON. Funciona em qualquer linguagem que faça um GET — os exemplos abaixo estão prontos para copiar.

GET https://api.vercnpj.com.br/v1/cnpj/12ABC345000188?incluir=socios,simples
X-Api-Key: SUA_CHAVE

Criar conta e pegar a chave

Chave e formato da resposta

Consulta de CNPJ (Receita Federal, Simples Nacional, sócios e inscrição estadual) em JSON.

Autenticação: cabeçalho X-Api-Key: SUA_CHAVE (ou Authorization: Bearer SUA_CHAVE). Chave vc_test_... = ambiente de TESTE: não gasta crédito e responde com empresas fictícias (12ABC345000188 e 11222333000181).

Resposta: sempre {"success": true, "data": {...}} ou {"success": false, "error": {"code": "...", "message": "...", "request_id": "..."}}. Decida pelo error.code, nunca pelo texto. Guarde o request_id para falar com o suporte.

Cabeçalhos devolvidos: X-Request-Id, X-Creditos-Restantes, X-RateLimit-Limit, X-RateLimit-Remaining.

Rotas

GET/v1/cnpj/{cnpj}

Consulta um CNPJ

Empresa, situação, endereço, contato, atividades e regime tributário. Blocos extras em incluir (cada um tem o seu custo; consulta repetida do mesmo CNPJ dentro do prazo não cobra de novo).

ParâmetroOndeDescriçãoExemplo
cnpj *no endereçoCNPJ com ou sem máscara; aceita o CNPJ alfanumérico12ABC345000188
incluirna URL (?)Blocos extras separados por vírgula: socios, simples, iesocios,simples
GET/v1/cnpj/{cnpj}/inscricoes

Inscrições estaduais (SEFAZ, na hora)

ParâmetroOndeDescriçãoExemplo
cnpj *no endereçoCNPJ com ou sem máscara; aceita o CNPJ alfanumérico12ABC345000188
ufna URL (?)UF a consultar (padrão = UF do endereço do CNPJ)SP
GET/v1/conta

Plano, saldo de créditos e uso do mês (não gasta crédito)

GET/v1/statussem chave

Situação da API e mês da base da Receita (sem chave)

Campos do CNPJ

Resposta de GET /v1/cnpj/{cnpj} dentro de data. Todo código vem como texto (ex.: "02"), datas em AAAA-MM-DD e o que não existe vem null — nunca some do JSON.

CampoTipoObservação
cnpjtexto
cnpj_formatadotexto
cnpj_basicotexto
matrizverdadeiro/falso
razao_socialtexto ou null
nome_fantasiatexto ou null
situacaoobjeto
situacao.codigotexto
Valores: 01, 02, 03, 04, 08
situacao.descricaotexto
Valores: NULA, ATIVA, SUSPENSA, INAPTA, BAIXADA
situacao.datatexto (AAAA-MM-DD) ou null
situacao.motivoobjeto ou null
situacao.motivo.codigotexto
situacao.motivo.descricaotexto ou null
situacao_especialobjeto ou null
situacao_especial.descricaotexto
situacao_especial.datatexto (AAAA-MM-DD) ou null
data_aberturatexto (AAAA-MM-DD) ou null
natureza_juridicaobjeto ou null
natureza_juridica.codigotexto
natureza_juridica.descricaotexto ou null
porteobjeto ou null
porte.codigotexto
porte.descricaotexto ou null
capital_socialnúmero ou null
ente_federativotexto ou null
enderecoobjeto
endereco.tipo_logradourotexto ou null
endereco.logradourotexto ou null
endereco.numerotexto ou null
endereco.complementotexto ou null
endereco.bairrotexto ou null
endereco.ceptexto ou null
endereco.municipioobjeto
endereco.municipio.codigo_receitatexto ou null
endereco.municipio.codigo_ibgetexto ou null
endereco.municipio.nometexto ou null
endereco.uftexto ou null
endereco.paistexto ou null
endereco.cidade_exteriortexto ou null
contatoobjeto
contato.telefones[]lista de objetos
contato.telefones[].dddtexto ou null
contato.telefones[].numerotexto
contato.telefones[].completotexto
contato.telefones[].tipotexto
Valores: TELEFONE, FAX
contato.emailtexto ou null
atividade_principalobjeto ou null
atividade_principal.codigotexto
atividade_principal.descricaotexto ou null
atividades_secundarias[]lista de objetos
atividades_secundarias[].codigotexto
atividades_secundarias[].descricaotexto ou null
regime_tributarioobjeto
regime_tributario.codigotexto
Valores: MEI, SIMPLES_NACIONAL, LUCRO_REAL_OU_PRESUMIDO
regime_tributario.descricaotexto
removido_da_baseverdadeiro/falsotrue = o CNPJ saiu da base da Receita (dados do último mês em que apareceu)
simplesobjetoSó com incluir=simples
simples.optanteverdadeiro/falso
simples.data_opcaotexto (AAAA-MM-DD) ou null
simples.data_exclusaotexto (AAAA-MM-DD) ou null
simples.meiverdadeiro/falso
simples.data_opcao_meitexto (AAAA-MM-DD) ou null
simples.data_exclusao_meitexto (AAAA-MM-DD) ou null
socios[]lista de objetosSó com incluir=socios. O CPF já vem mascarado da Receita.
socios[].nometexto
socios[].tipotexto
Valores: PESSOA_JURIDICA, PESSOA_FISICA, ESTRANGEIRO
socios[].documentotexto ou null
socios[].qualificacaoobjeto ou null
socios[].qualificacao.codigotexto
socios[].qualificacao.descricaotexto ou null
socios[].data_entradatexto (AAAA-MM-DD) ou null
socios[].faixa_etariatexto ou null
socios[].paistexto ou null
socios[].representante_legalobjeto ou null
socios[].representante_legal.nometexto
socios[].representante_legal.documentotexto ou null
socios[].representante_legal.qualificacaotexto ou null
inscricoes_estaduais[]lista de objetosSó com incluir=ie
inscricoes_estaduais[].uftexto
inscricoes_estaduais[].numerotexto
inscricoes_estaduais[].situacaotexto
Valores: HABILITADA, NAO_HABILITADA
inscricoes_estaduais[].tipo_contribuintetexto ou null
inscricoes_estaduais[].regime_apuracaotexto ou null
inscricoes_estaduais[].credenciado_nfeinteiro ou null
inscricoes_estaduais[].data_situacaotexto (AAAA-MM-DD) ou null
inscricoes_estaduais[].data_baixatexto (AAAA-MM-DD) ou null
inscricoes_estaduais[].consultado_emtexto (data e hora) ou null
fontesobjeto
fontes.receitaobjeto
fontes.receita.mestexto
fontes.receita.atualizandoverdadeiro/falso
fontes.sefazobjeto ou null
fontes.sefaz.uftexto
fontes.sefaz.resultadotexto
fontes.sefaz.consultado_emtexto (data e hora)

Códigos de erro

Em erro, a resposta é {"success": false, "error": {"code", "message", "request_id"}}. Trate pelo code (fixo), nunca pelo texto.

codeHTTPQuando acontece
CHAVE_AUSENTE401Informe a chave de acesso no cabeçalho X-Api-Key.
CHAVE_INVALIDA401Chave de acesso inválida.
CHAVE_REVOGADA401Esta chave de acesso foi revogada.
CHAVE_EXPIRADA401Esta chave de acesso venceu.
IP_NAO_PERMITIDO403Este IP não está liberado para esta chave.
CONTA_BLOQUEADA403A conta está bloqueada. Fale com o suporte.
SEM_ASSINATURA403A conta não tem um plano ativo.
RECURSO_NAO_INCLUIDO403O seu plano não inclui este recurso.
SALDO_INSUFICIENTE402Os créditos acabaram. Compre mais créditos ou mude de plano.
LIMITE_MINUTO429Muitas consultas por minuto. Aguarde alguns segundos.
LIMITE_DIA429O limite de consultas do dia foi atingido.
CNPJ_INVALIDO400O CNPJ informado não é válido.
PARAMETRO_INVALIDO400Parâmetro inválido.
CNPJ_NAO_ENCONTRADO404CNPJ não encontrado na base da Receita Federal.
ROTA_NAO_ENCONTRADA404Endereço não encontrado. Veja a documentação da API em https://vercnpj.com.br/api.
METODO_NAO_PERMITIDO405Método não permitido para este endereço.
BASE_INDISPONIVEL503A base de dados está em manutenção. Tente de novo em instantes.
ERRO_INTERNO500Erro interno. Informe o request_id ao suporte.

Exemplos de código

uses System.SysUtils, System.Net.HttpClient, System.JSON;

// Lê um campo pelo caminho ("data.endereco.cep"); null ou ausente = ''.
function Campo(AJson: TJSONValue; const ACaminho: string): string;
var V: TJSONValue;
begin
  V := AJson.FindValue(ACaminho);
  if (V = nil) or (V is TJSONNull) then Result := '' else Result := V.Value;
end;

function ConsultarCNPJ(const ACNPJ, AChave: string): TJSONValue;
var
  Http: THTTPClient;
  Resp: IHTTPResponse;
begin
  Http := THTTPClient.Create;
  try
    Http.CustomHeaders['X-Api-Key'] := AChave;
    Resp := Http.Get('https://api.vercnpj.com.br/v1/cnpj/' + ACNPJ + '?incluir=socios,simples');
    Result := TJSONObject.ParseJSONValue(Resp.ContentAsString(TEncoding.UTF8));
    if Campo(Result, 'success') <> 'true' then
    try
      raise Exception.CreateFmt('%s: %s', [Campo(Result, 'error.code'), Campo(Result, 'error.message')]);
    finally
      Result.Free;
    end;
  finally
    Http.Free;
  end;
end;

// Uso:
var Dados: TJSONValue;
begin
  Dados := ConsultarCNPJ('12ABC345000188', 'vc_test_SUA_CHAVE_DE_TESTE');
  try
    EdtRazao.Text    := Campo(Dados, 'data.razao_social');
    EdtFantasia.Text := Campo(Dados, 'data.nome_fantasia');
    EdtCEP.Text      := Campo(Dados, 'data.endereco.cep');
    EdtIBGE.Text     := Campo(Dados, 'data.endereco.municipio.codigo_ibge');
    EdtSituacao.Text := Campo(Dados, 'data.situacao.descricao');
  finally
    Dados.Free;
  end;
end;

Delphi (10.3 ou mais novo, sem componente nenhum)

Testar agora

Use a chave de teste: não gasta crédito.