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

Vitrine sem prefixo v1

O que é a superfície /api/storefront, quem pode chamá-la e o mapa de todas as rotas.

A vitrine é a parte da loja que o cliente final usa. A superfície /api/storefront/... (sem prefixo de versão) foi criada para integrações de terceiros que precisam de um caminho estável e de uma forma própria de autorização: chaves de API da vitrine (sfk_...) e tokens de app (vat_...), cada um com escopos. Os apps e conectores escritos para a Venddor 1.0 usam este caminho.

Esta seção documenta as 21 rotas dessa superfície: catálogo (produtos, categorias, busca), conteúdo (páginas, menus), checkout por sessão, cálculo de frete e a lista de pedidos do cliente logado.

Pontos-chave
  • Quem consome catálogo e páginas pode ser anônimo. Quem faz checkout é dono de uma sessão: o cliente logado (JWT) ou o visitante que criou o carrinho (cabeçalho X-Session-ID).
  • Chave sfk_... precisa dos escopos storefront:read (catálogo, menus) e storefront:write (checkout). Token vat_... usa read_content, write_orders, read_shipping e read_orders.
  • Dinheiro é inteiro em centavos (30000 é R$ 300,00). Os campos *_str repetem o valor em reais como texto.
  • Sessão de outra pessoa responde 404, nunca 403: a plataforma não confirma que a sessão existe.
  • Esta superfície não troca ids por números: os ids são UUID, diferente das rotas /api/... de compatibilidade com a 1.0.

Como funciona

O funil de compra

O cliente monta um carrinho na loja ou no app, e é a partir do cart_id dele que o checkout começa. A sessão de checkout guarda o endereço, o frete, a forma de pagamento e os descontos, e a cada passo recalcula o total.

Carrinho→Iniciar checkout→Endereço→Frete→Pagamento→Validar→Fechar pedido
  1. Criar a sessão

    POST /api/storefront/checkout com o cart_id. A resposta traz o id da sessão e o passo atual.

  2. Informar endereço, frete e pagamento

    Três PUT na ordem (passos do checkout). Cada um devolve a sessão com o total recalculado.

  3. Aplicar descontos (opcional)

    Cupom e vale-presente.

  4. Validar e fechar

    validate confere estoque, preço, cupom e pagamento sem criar nada; place cria o pedido.

Os passos da sessão (step) avançam sozinhos: address, shipping, payment, review.

Conceitos-chave

Quem pode chamar

CredencialCabeçalhoServe para
Nenhuma (anônimo)NenhumCatálogo, páginas, menus, frete. Checkout apenas com X-Session-ID do carrinho de visitante.
JWT do clienteAuthorization: Bearer <jwt>Tudo, e é obrigatório para a lista de pedidos.
Chave da vitrineX-API-Key: sfk_... ou Authorization: Bearer sfk_...Escopos storefront:read e storefront:write. Falta de escopo: 403 {"error":"missing_scope","required":"..."}.
Token de appAuthorization: Bearer vat_...Escopos read_content, write_orders, read_shipping, read_orders. Falta de escopo: 403 {"error":"missing_scope","required":"..."}.

Mais sobre chaves e tokens em Autenticação.

Catálogo fechado para visitantes

Se a loja exigir login para navegar, as rotas de produtos, categorias e busca respondem 401 {"error":"shopping_requires_login","message":"this storefront requires login to browse"} para quem não estiver logado. Páginas, menus, checkout e frete não passam por essa trava.

Sessão de checkout e dono

A sessão pertence a quem a criou. Usuário logado: a sessão é do user_id. Visitante: a sessão é do X-Session-ID do carrinho. Outro chamador recebe 404 {"error":"checkout session not found"}, igual a uma sessão que não existe.

Valores e datas

Dinheiro em centavos (int). Datas em RFC 3339 (UTC). Ids em UUID. O corpo de erro desta superfície é {"error": "..."}, sem status.

Endpoints

Método e caminhoPara que serveAutenticaçãoPágina
GET /api/storefront/productsLista produtosAnônimo, sfk_ storefront:readProdutos
GET /api/storefront/products/{id}Lê um produtoAnônimo, sfk_ storefront:readProdutos
GET /api/storefront/categoriesÁrvore de categoriasAnônimo, sfk_ storefront:readCategorias
GET /api/storefront/categories/{id}Lê uma categoriaAnônimo, sfk_ storefront:readCategorias
GET /api/storefront/searchBusca de produtosAnônimo, sfk_ storefront:readBusca
GET /api/storefront/pagesLista páginas de conteúdoAnônimoPáginas e menus
GET /api/storefront/pages/{slug}Lê uma páginaAnônimoPáginas e menus
GET /api/storefront/menusMenus de navegaçãoAnônimo, vat_ read_contentPáginas e menus
POST /api/storefront/checkoutAbre a sessão de checkoutDono do carrinhoIniciar checkout
GET /api/storefront/checkout/{sessionId}Resumo da sessão e opçõesDono da sessãoIniciar checkout
PUT /api/storefront/checkout/{sessionId}/addressDefine endereço e documentoDono da sessãoPassos do checkout
PUT /api/storefront/checkout/{sessionId}/shippingEscolhe o freteDono da sessãoPassos do checkout
PUT /api/storefront/checkout/{sessionId}/paymentEscolhe o pagamentoDono da sessãoPassos do checkout
POST e DELETE /api/storefront/checkout/{sessionId}/couponAplica e remove cupomDono da sessãoCupom e vale-presente
POST e DELETE /api/storefront/checkout/{sessionId}/gift-certificateAplica e remove vale-presenteDono da sessãoCupom e vale-presente
POST /api/storefront/checkout/{sessionId}/validateValida sem fecharDono da sessãoValidar e fechar
POST /api/storefront/checkout/{sessionId}/placeCria o pedidoDono da sessãoValidar e fechar
POST /api/storefront/shipping/calculateCotação de frete de uma sacolaAnônimo, vat_ read_shippingCalcular frete
GET /api/storefront/ordersPedidos do cliente logadoJWT do clientePedidos do cliente

Erros comuns

  • Chamar checkout sem guest_email como visitante. Quem não está logado precisa mandar guest_email ao abrir a sessão.
  • Mandar um X-Session-ID diferente do usado no carrinho. O carrinho do visitante "não é seu" e a resposta é 404 cart not found.
  • Ler valid: true em validate como "pode fechar". validate confere estoque, preço, cupom e pagamento, mas não exige endereço nem frete; o place sem endereço dá 400.
  • Tratar 409 do place como falha definitiva. Alguns 409 pedem apenas que o cliente revise (preço mudou) ou espere (pedido em processamento).
  • Usar chave sfk_ na lista de pedidos. Ela exige o JWT do cliente.
  • Esperar ids numéricos. Aqui os ids são UUID.

Próximos passos

Iniciar checkout
Abrir a sessão a partir do carrinho.
Produtos
Listar e ler produtos da vitrine.
Calcular frete
Cotar uma sacola por CEP.
Anterior
Idiomas
Próxima
Produtos
Nesta página
  • Como funciona
  • O funil de compra
  • Conceitos-chave
  • Quem pode chamar
  • Catálogo fechado para visitantes
  • Sessão de checkout e dono
  • Valores e datas
  • Endpoints
  • Erros comuns
  • Próximos passos