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

Rotas públicas que ajudam a preencher formulários e a formatar valores na vitrine.

Algumas informações não pertencem a nenhum pedido: o endereço de um CEP, os dados públicos de uma empresa, as moedas que a loja aceita, os planos oferecidos a quem quer vender. Esta seção reúne essas consultas, todas públicas (sem token) e só de leitura, exceto a escolha de moeda, que grava um cookie.

Pontos-chave
  • Nenhuma rota desta seção exige token.
  • CEP e CNPJ dependem de módulos (cep-lookup; cpf-cnpj-validation ou cnpj-login). Sem eles, 403 module_disabled.
  • CEP e CNPJ vêm de provedores externos: podem demorar, ter limite de uso e cair.
  • A moeda do visitante fica em um cookie, não em um cabeçalho.
  • Preços continuam em centavos da moeda principal.

Como funciona

Uso típico na vitrine:

  1. Formulário de endereço

    O cliente digita o CEP; chame Buscar endereço por CEP ao completar 8 dígitos e preencha o formulário.

  2. Cadastro de empresa

    Ao digitar o CNPJ, chame Consultar CNPJ para preencher razão social e endereço e avisar se a situação não é ATIVA.

  3. Seletor de moeda

    Leia as moedas ao carregar a página; quando o visitante escolher outra, chame select e recarregue.

Conceitos-chave

CEP e CNPJ

O CEP (código de endereçamento postal) tem 8 dígitos e identifica um logradouro ou uma cidade. O CNPJ (Cadastro Nacional da Pessoa Jurídica) identifica uma empresa. Os dois aceitam a versão com ou sem máscara.

Provedores externos

As duas consultas dependem de serviços externos. A de CEP guarda respostas em cache e tem contingência (só a UF). A de CNPJ valida o dígito verificador antes de consultar e tem limite de uso global (429).

Moeda do visitante

A moeda ativa é lida do cookie venddor_currency. Sem cookie, vale a moeda principal. Quem integra por servidor deve guardar e reenviar o cookie.

Planos de seller

Um plano combina mensalidade, comissão e limites. commission_bps usa pontos-base (1 bps = 0,01%).

Endpoints

Método e caminhoPara quêAutenticaçãoPágina
GET /api/v1/storefront/cep/{cep}Busca o endereço de um CEPPúblicaBusca de CEP e CNPJ
GET /api/v1/storefront/cnpj/{cnpj}Dados públicos de uma empresa pelo CNPJPúblicaBusca de CEP e CNPJ
GET /api/v1/storefront/currenciesLista as moedas habilitadas e a ativaPúblicaMoedas
GET /api/v1/storefront/currencies/activeDevolve a moeda ativa do visitantePúblicaMoedas
POST /api/v1/storefront/currencies/selectGrava a moeda escolhida em um cookiePúblicaMoedas
GET /api/v1/storefront/vendor-plansLista os planos que um seller pode contratarPúblicaPlanos para sellers

Erros comuns

O que costuma dar errado
  1. Chamar o CEP a cada tecla. Espere os 8 dígitos.
  2. Ignorar fallback: true: a resposta só tem a UF e o resto do endereço vem vazio.
  3. Tratar 404 do CEP como erro do servidor. Alguns CEPs não existem na base; deixe o cliente digitar.
  4. Confiar em capital_social do CNPJ: vários provedores devolvem 0.
  5. Chamar currencies/select de um servidor e esperar que valha para o navegador do cliente. O cookie é por navegador.
  6. Exibir o preço de um plano price_on_request.

Próximos passos

Busca de CEP e CNPJ
CEP e CNPJ para formulários.
Moedas
Moedas habilitadas e escolha do visitante.
Planos para sellers
Planos para quem quer vender.
Anterior
Mercado ativo
Próxima
Busca de CEP e CNPJ
Nesta página
  • Como funciona
  • Conceitos-chave
  • CEP e CNPJ
  • Provedores externos
  • Moeda do visitante
  • Planos de seller
  • Endpoints
  • Erros comuns
  • Próximos passos