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

Catálogo da mini-loja

Como a mini-loja do WhatsApp lista, busca e abre produtos, o que muda para visitante e cliente e o mapa de todas as rotas do catálogo.

O catálogo da mini-loja é o mesmo catálogo da loja, filtrado para o canal WhatsApp e para o cliente do token: o que ele pode ver, a que preço e se o produto chega ao endereço dele. Estas rotas servem a home, as prateleiras, a busca, a ficha do produto (a "PDP", product detail page) e os favoritos. Todas usam o token da mini-loja no caminho (veja Mini-loja do WhatsApp).

Pontos-chave
  • O preço depende de quem pergunta. Preços de tabela, grupo de cliente e acordo com o representante só aparecem para o cliente identificado. Se a loja esconde preço até o login, o produto vem com price_redacted: true e todos os valores zerados.
  • Dinheiro em centavos (price_cents, list_price_cents) e ids UUID. list_price_cents é o preço "de" riscado; só existe quando é maior que o preço atual.
  • A área de entrega do seller conta. Na ficha, um produto que o seller não entrega no endereço do cliente vem com available: false e outside_delivery_area: true. Na lista, quando a loja filtra o catálogo pela área de entrega e nada chega ao endereço, a resposta traz delivery_blocked em vez de uma lista simplesmente vazia.
  • Recursos opcionais (avaliações, compre junto, frete na ficha, favoritos) dependem de funcionalidades da loja. Consulte store_caps em Aparência antes de chamar.
  • O visitante só vê o catálogo se a loja permitir (allow_shopping_unlogged). Senão toda rota daqui responde 403 account_required; com a porta de entrada por CNPJ fechada, 403 entry_required.

Como funciona

Listar ou buscar→Abrir o produto→Escolher variação e opções→Calcular frete→Adicionar à sacola
  1. Listar e buscar

    GET /catalog/{token} devolve produtos e a árvore de categorias; GET /search/{token} faz a busca por texto.

  2. Abrir a ficha

    GET /product/{token}/{productID} traz fotos, opções, especificações, faixas de preço por quantidade e outros vendedores.

  3. Resolver a variação

    Produtos com cor, tamanho ou caixa (grade) usam POST /product/.../configuration: você manda as escolhas e o servidor devolve o que ainda falta e a variação final.

  4. Adicionar à sacola

    Com a variação resolvida, vá para a sacola.

Conceitos-chave

Quem vê o quê

QuemVê
VisitanteO catálogo, se allow_shopping_unlogged. Preços só se allow_guest_view_price (e a loja não esconder até o login).
Cliente identificadoPreços do grupo de clientes, faixas de quantidade, acordo com representante (rep_agreement), crédito.
Qualquer umNada de outro seller quando o link é de um seller: a mini-loja de um número lista só os produtos daquele seller (a de marketplace lista todos).

Variações, opções e caixas

Um produto pode ser comprado por variação (a combinação de eixos como cor e tamanho vira outro SKU), por opções (escolhas do cliente como ponto da carne ou adicionais, que não mudam o SKU) e por caixa (grade de tamanhos). needs_choice: true na lista avisa que o cartão deve levar o cliente à ficha em vez de adicionar direto.

Estoque e disponibilidade

available junta estoque, venda sem estoque (backorder) e janela de lançamento (avail_since no futuro mostra "em breve"). stock_amount só vem quando a loja mostra o estoque. As listas põem os disponíveis antes dos indisponíveis dentro da mesma página.

O mapa de textos (copy)

Várias respostas trazem copy, um mapa de textos da loja já resolvidos por segmento. Trate como opaco e leia só as chaves que a sua tela usa.

Endpoints

MétodoRotaO que fazPágina
GET/api/v1/storefront/wa-coex/catalog/{token}Lista produtos e categoriasListar e buscar
GET/api/v1/storefront/wa-coex/search/{token}Busca produtos por textoListar e buscar
GET/api/v1/storefront/wa-coex/choose/{token}Resumo de produtos com opçõesListar e buscar
GET/api/v1/storefront/wa-coex/product/{token}/{productID}Ficha do produtoFicha do produto
GET/api/v1/storefront/wa-coex/product/{token}/{productID}/relatedProdutos relacionadosFicha do produto
GET/api/v1/storefront/wa-coex/product/{token}/{productID}/comboOferta "compre junto"Ficha do produto
POST/api/v1/storefront/wa-coex/product/{token}/{productID}/configurationResolve variação e caixaVariação e frete
POST/api/v1/storefront/wa-coex/product/{token}/{productID}/shippingFrete do produto para um CEPVariação e frete
GET/api/v1/storefront/wa-coex/product/{token}/{productID}/reviewsAvaliações do produtoAvaliações
POST/api/v1/storefront/wa-coex/product/{token}/{productID}/reviewsAposentada (410)Avaliações
POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/reviewAposentada (410)Avaliações
GET/api/v1/storefront/wa-coex/order/{token}/{orderID}/reviewableItens do pedido que podem ser avaliadosAvaliações
POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/items/{productID}/reviewAvalia um produto do pedidoAvaliações
GET/api/v1/storefront/wa-coex/favorites/{token}Lista os favoritosFavoritos
POST/api/v1/storefront/wa-coex/favorites/{token}/{productID}Favorita um produtoFavoritos
DELETE/api/v1/storefront/wa-coex/favorites/{token}/{productID}Remove dos favoritosFavoritos
POST/api/v1/storefront/wa-coex/cart/{token}/favoritesColoca os favoritos na sacolaFavoritos

Erros comuns

  • Passar o slug da categoria em category. O filtro só aceita o id (UUID) da categoria. Um slug como notebooks faz a rota falhar com 500 e uma mensagem técnica no corpo.
  • Mostrar o preço sem olhar price_redacted. Com true, price_cents é 0: não escreva "R$ 0,00", mostre "entre para ver o preço".
  • Ignorar outside_delivery_area. Na ficha o produto vem indisponível para aquele endereço, e tentar adicioná-lo à sacola responde 409 outside_delivery_area.
  • Chamar a rota aposentada de avaliação. POST .../reviews e POST /order/.../review respondem 410. A avaliação é feita por produto, a partir de um pedido entregue.
  • Esperar recursos opcionais em lojas que não os ligaram. Frete na ficha, avaliações e compre junto respondem vazio, 404 ou 403 quando a funcionalidade está desligada.
  • Pedir per_page acima do limite. A lista aceita até 200 itens por página e a busca até 100; valores maiores são trocados pelo limite ou pelo padrão.

Próximos passos

Listar e buscar
Catálogo, categorias, busca e prateleiras.
Ficha do produto
Abrir o produto, relacionados e combo.
Sacola e checkout
Adicionar à sacola e fechar o pedido.
Sessão da mini-loja
Token, login e aparência da loja.
Anterior
Aparência e utilidades
Próxima
Listar e buscar produtos
Nesta página
  • Como funciona
  • Conceitos-chave
  • Quem vê o quê
  • Variações, opções e caixas
  • Estoque e disponibilidade
  • O mapa de textos (copy)
  • Endpoints
  • Erros comuns
  • Próximos passos