VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Utilidades da vitrine

Visão geral das rotas de apoio da vitrine: módulos, validação de documentos, estatísticas e mercado.

Esta seção reúne pequenas rotas de apoio da vitrine (a loja que o cliente vê). Elas não formam um fluxo de compra: são consultas que um front-end faz ao carregar a página, como "quais recursos esta loja tem ligados?", "este CPF é válido?" ou "em qual mercado (país e moeda) o visitante está?".

Pontos-chave
  • Quase tudo aqui é público: sem token. Só as estatísticas do cliente (/stats) exigem um cliente logado.
  • A loja é identificada pelo domínio da chamada (veja Multi-loja). Em testes, o cabeçalho X-Tenant-ID faz o mesmo papel.
  • Módulo é um recurso opcional que o administrador liga por loja. Rota de módulo desligado responde 403 com module_disabled.
  • Valores monetários ficam em centavos inteiros e datas em RFC 3339 (UTC), como no restante da API.

Como funciona

Um front-end típico usa estas rotas nesta ordem:

  1. Descobrir o que a loja tem ligado

    Chame Módulos da loja uma vez por carga de página. A lista enabled_modules decide quais telas e botões aparecem (avaliações, chat de WhatsApp, validação de documento).

  2. Escolher o mercado

    Em lojas com vários países, Mercado ativo diz qual mercado vale para o visitante e sugere outro quando a localização indica isso.

  3. Validar documentos no cadastro

    Nos formulários, Validar CPF e CNPJ confere os dígitos verificadores antes de enviar o cadastro.

  4. Mostrar o resumo da conta

    Na área do cliente, Estatísticas do cliente devolve o total de pedidos e o gasto.

Conceitos-chave

Módulo

A plataforma é uma só para todas as lojas, e cada loja liga os recursos de que precisa. Cada recurso é um módulo com um identificador curto (slug), como whatsapp-chat ou cpf-cnpj-validation. O módulo pode estar ligado e ainda assim ficar oculto, se o operador da plataforma o desativou para a loja.

Mercado

Um mercado agrupa países que compartilham idioma, moeda e regra de preço. A loja pode ter vários; um deles é o padrão. O visitante pode escolher o seu, e a escolha fica num cookie por 90 dias.

Endpoints

MétodoRotaO que fazAuthPágina
GET/api/v1/storefront/modules/statusLista os módulos ligadosPúblicaMódulos da loja
GET/api/v1/storefront/modules/{slug}/settingsConfiguração pública de um móduloPúblicaMódulos da loja
GET/api/v1/storefront/modules/extensions/{point}Componentes que módulos acoplam a um ponto da telaPúblicaMódulos da loja
POST/api/v1/storefront/validate/cpfValida um CPFPúblicaValidar CPF e CNPJ
POST/api/v1/storefront/validate/cnpjValida um CNPJPúblicaValidar CPF e CNPJ
GET/api/v1/storefront/statsResumo de pedidos do cliente logadoClienteEstatísticas do cliente
GET/api/v1/storefront/marketMercado ativo do visitantePúblicaMercado ativo
POST/api/v1/storefront/market/selectEscolhe o mercadoPúblicaMercado ativo

Erros comuns

  1. Tratar valid: false como erro HTTP. A validação de CPF e CNPJ responde 200 mesmo quando o número é inválido; leia o campo valid.
  2. Chamar a validação numa loja sem o módulo cpf-cnpj-validation. A resposta é 403 module_disabled. Confira antes em Módulos da loja.
  3. Esperar segredos nas configurações de módulo. A rota pública devolve só chaves liberadas e, para a maioria dos módulos, um objeto vazio.
  4. Mandar um market_id que não é UUID. A rota de escolha responde 500 em vez de 400 (veja Mercado ativo).
  5. Chamar /stats sem token de cliente. Responde 401 com o texto missing authorization header.

Próximos passos

Módulos da loja
O que a loja tem ligado.
Validar CPF e CNPJ
Confira documentos antes do cadastro.
Mercado ativo
País, idioma e moeda do visitante.
Anterior
Calendário de publicação
Próxima
Módulos da loja
Nesta página
  • Como funciona
  • Conceitos-chave
  • Módulo
  • Mercado
  • Endpoints
  • Erros comuns
  • Próximos passos