VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Dados da loja: CEP, CNPJ, moedas e planos

Busca de CEP e CNPJ

Preenche endereço pelo CEP e dados da empresa pelo CNPJ.

Dois atalhos de formulário para o mercado brasileiro: o CEP completa o endereço de entrega e o CNPJ completa o cadastro de uma empresa. Ambas as rotas são públicas e dependem de módulos da loja.

Buscar endereço por CEP

O CEP é o código postal brasileiro, com 8 dígitos. Esta rota devolve o endereço dele para pré-preencher formulários de entrega e cobrança: o cliente digita o CEP e a rua, o bairro, a cidade e a UF aparecem sozinhos. Exige o módulo cep-lookup. Respostas ficam em cache no servidor.

GET/api/v1/storefront/cep/{cep}Pública

Preenche rua, bairro, cidade e UF a partir do CEP

Parâmetros de caminho

cepstringobrigatório
CEP, com ou sem hífen (01310-100 ou 01310100). Só os dígitos contam: precisam ser exatamente 8.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/cep/01310-100"

Resposta

200Endereço encontrado
json
{
  "cep": "01310-100",
  "logradouro": "Avenida Paulista",
  "complemento": "",
  "bairro": "Bela Vista",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "",
  "ddd": ""
}
200Provedor fora do ar (contingência)
json
{
  "cep": "01310-100",
  "uf": "SP",
  "localidade": "",
  "logradouro": "",
  "bairro": "",
  "fallback": true,
  "source": "local_cep_range"
}

Campos da resposta

cepstring
CEP formatado (00000-000).
logradourostring
Rua, avenida etc. Pode vir vazio.
complementostring
Complemento do endereço, quando o CEP tem.
bairrostring
Bairro.
localidadestring
Cidade.
ufstring
Sigla do estado (SP).
ibgestring
Código IBGE do município. Pode vir vazio.
dddstring
DDD telefônico. Pode vir vazio.
fallbackboolean
Só na contingência: true quer dizer que só a UF foi deduzida pela faixa do CEP; rua, bairro e cidade vêm vazios.
sourcestring
Só na contingência: local_cep_range.

Erros

StatusQuandoCorpo de exemplo
400O CEP não tem exatamente 8 dígitos.{"error":"CEP must contain exactly 8 digits"}
403O módulo cep-lookup está desligado nesta loja.{"error":"module_disabled","module":"cep-lookup"}
404CEP não encontrado.{"error":"CEP not found"}
503Provedor de CEP indisponível e sem como deduzir a UF. Tente de novo depois de retry_after segundos (cabeçalho Retry-After).{"error":"provider_unavailable","provider":"geocoding","retry_after":30}
Trate `fallback: true` como 'preencha à mão'

Quando o provedor externo cai, a rota ainda responde 200, mas só com a UF. Preencha a UF, deixe os outros campos editáveis e peça ao cliente para completar. A resposta de contingência não entra no cache, então a próxima consulta tenta o provedor de novo.

Consultar CNPJ

O CNPJ é o cadastro nacional de empresas. Esta rota consulta fontes públicas (BrasilAPI e, na falta dela, outras) e devolve razão social, endereço, atividade principal e situação cadastral. Serve para o cadastro B2B preencher o formulário sozinho e para conferir se a empresa está ATIVA. Exige o módulo cpf-cnpj-validation ou cnpj-login. O dígito verificador é conferido antes da consulta.

GET/api/v1/storefront/cnpj/{cnpj}Pública

Dados públicos de uma empresa pelo CNPJ

Parâmetros de caminho

cnpjstringobrigatório
CNPJ com 14 caracteres, com ou sem máscara (12.345.678/0001-95 ou 12345678000195). Aceita o CNPJ alfanumérico da Receita Federal.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/cnpj/12345678000195"

Resposta

200Empresa encontrada
json
{
  "cnpj": "12.345.678/0001-95",
  "razao_social": "DISTRIBUIDORA AURORA LTDA",
  "nome_fantasia": "AURORA DISTRIBUIDORA",
  "cnae": "46.49-4-99",
  "cnae_descricao": "Comércio atacadista de outros equipamentos e artigos de uso pessoal e doméstico",
  "endereco": "AVENIDA PAULISTA",
  "numero": "1000",
  "complemento": "SALA 12",
  "bairro": "BELA VISTA",
  "cidade": "SAO PAULO",
  "uf": "SP",
  "cep": "01310-100",
  "telefone": "1130000000",
  "email": "contato@aurora.example.com",
  "situacao": "ATIVA",
  "data_abertura": "2012-04-18",
  "capital_social": 0,
  "porte": "DEMAIS",
  "natureza": "Sociedade Empresária Limitada",
  "atividade_principal": "4649499 - Comércio atacadista de outros equipamentos e artigos de uso pessoal e doméstico",
  "source": "brasilapi"
}

Campos da resposta

cnpjstring
CNPJ formatado.
razao_socialstring
Razão social (nome legal).
nome_fantasiastring
Nome fantasia (nome comercial).
cnae, cnae_descricaostring
Código e descrição da atividade principal (CNAE).
endereco, numero, complemento, bairro, cidade, uf, cepstring
Endereço da sede. endereco é o logradouro.
telefone, emailstring
Contatos do cadastro. Podem vir vazios.
situacaostring
Situação cadastral: ATIVA, BAIXADA, SUSPENSA, INAPTA...
data_aberturastring
Abertura da empresa (YYYY-MM-DD).
capital_socialinteger
Capital social. Em muitos provedores vem 0; não use como dado confiável.
portestring
Porte: MEI, ME, EPP ou DEMAIS.
naturezastring
Natureza jurídica.
atividade_principalstring
código - descrição da atividade principal.
cnae_secundarios, secondary_cnaesarray
Atividades secundárias, quando o provedor as traz.
state_registrationstring
Inscrição estadual, quando o provedor a traz.
sourcestring
Provedor que respondeu (netrin, brasilapi, receitaws).

Erros

StatusQuandoCorpo de exemplo
400O CNPJ não tem 14 caracteres.{"error":"CNPJ must contain exactly 14 characters"}
400O dígito verificador não fecha.{"error":"invalid CNPJ","detail":"invalid CNPJ checksum: 11.222.333/0001-82"}
403Nenhum dos módulos cpf-cnpj-validation e cnpj-login está ligado.{"error":"module_disabled","modules":"cpf-cnpj-validation,cnpj-login"}
404CNPJ não encontrado nas fontes.{"error":"CNPJ not found","detail":"..."}
429Limite de consultas externas atingido; tente depois.{"error":"CNPJ lookup rate limited, try again later"}
502Nenhuma fonte respondeu.{"error":"CNPJ lookup service unavailable","detail":"..."}
Cadastro B2B completo

Para o fluxo de cadastro (unicidade do CNPJ, checagem de CNAE aceito pela loja), existe outra rota, GET /api/v1/storefront/register/cnpj/{cnpj}, descrita em Sessão e cadastro do cliente.

Veja também

  • Moedas
  • Visão geral
Anterior
Dados da loja: CEP, CNPJ, moedas e planos
Próxima
Moedas
Nesta página
  • Buscar endereço por CEP
  • Consultar CNPJ
  • Veja também