VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Mini-loja WhatsApp: catálogo

Listar e buscar produtos

Lista o catálogo com categorias, monta prateleiras por regra, busca produtos por texto e resume produtos que exigem uma escolha.

Estas três rotas montam as telas de descoberta da mini-loja: a home e as categorias (/catalog), a busca (/search) e o resumo de produtos que pedem uma escolha antes de ir à sacola (/choose). Todas devolvem produtos já com o preço do cliente do token e com os produtos disponíveis antes dos indisponíveis na mesma página.

Se a loja só permite navegar com login, ou a porta de entrada por documento está fechada, as três respondem 403 (veja os erros no fim de cada seção).

Listar o catálogo

GET/api/v1/storefront/wa-coex/catalog/{token}Pública

Lista produtos e a árvore de categorias, ou uma prateleira por regra

Tem dois modos. Modo lista (sem filling): produtos paginados, opcionalmente de uma categoria ou com filtros de características, mais a árvore de categorias. Modo prateleira (com filling): uma única prateleira da home, com um número pequeno de produtos escolhidos por regra, sem categorias.

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.

Parâmetros de consulta

categoryuuid
Id da categoria (inclui as subcategorias). Atenção: só o id serve; o slug causa erro 500.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 100
Itens por página, até 200. Valores maiores viram 200.
features[ID]string
Filtro por característica do produto. ID é o id da característica e o valor é uma lista, separada por vírgula, de ids de valores (features[7c1e...]=a1,b2). Vale no máximo 8 características por requisição.
features_hashstring
Filtro de características no formato compacto que o menu do site gera, no lugar de features[ID].
fillingstring
manualcategorybestsellersnewestmost_popularon_sale
Liga o modo prateleira. manual: os produtos de product_ids. category: os de category_ids. bestsellers: mais vendidos. newest: lançamentos. most_popular: mais populares. on_sale: só com desconto. Qualquer outro valor é 400 invalid_filling.
product_idsstring
Só no modo prateleira. Ids de produtos separados por vírgula (até 48). Define os itens de manual.
category_idsstring
Só no modo prateleira. Ids de categoria (UUID) separados por vírgula. Ids malformados são descartados.
exclude_product_idsstring
Só no modo prateleira. Ids que não podem aparecer.
countintegerpadrão: 8
Só no modo prateleira. Quantidade de produtos, de 1 a 24.
min_priceinteger
Só no modo prateleira. Preço mínimo em centavos. Ignorado quando o cliente não pode ver preços.
max_priceinteger
Só no modo prateleira. Preço máximo em centavos. Ignorado quando o cliente não pode ver preços.
stock_filterstring
in_stock
Só no modo prateleira. in_stock esconde os indisponíveis.

Exemplo de requisição

bash
# lista, 20 por página
curl "$BASE_URL/api/v1/storefront/wa-coex/catalog/$TOKEN?per_page=20&page=1"

# prateleira "em oferta" com 6 produtos
curl "$BASE_URL/api/v1/storefront/wa-coex/catalog/$TOKEN?filling=on_sale&count=6"

Resposta

200Modo lista (resumida)
json
{
  "products": [
    {
      "id": "68836206-cb76-4814-9811-335f02e4e956",
      "name": "Air Fryer Eco Branco",
      "image_url": "/uploads/.../air-fryer.png",
      "slug": "air-fryer-eco-branco-2431",
      "url": "/p/air-fryer-eco-branco-2431",
      "price_cents": 7992,
      "list_price_cents": 9990,
      "available": true,
      "sale_unit": "un",
      "quantity_step": 1,
      "min_quantity": 1,
      "vendor_name": "Loja Seller Teste",
      "stock_amount": 3
    }
  ],
  "categories": [
    { "id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9", "name": "Informática", "slug": "informatica", "product_count": 642 },
    { "id": "ae6f8f8b-7cbe-4725-84fa-247cce138143", "name": "Notebooks", "slug": "notebooks", "parent_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9", "product_count": 162 }
  ],
  "page": 1,
  "products_total": 4976,
  "commerce_profile": { "segment": "general", "config": {}, "labels": {}, "capabilities": ["catalog", "cart", "checkout", "campaigns"] },
  "copy": {}
}

Campos da resposta

productsarray
Produtos da página, no formato descrito em Ficha do produto. Na lista vêm menos campos (sem opções, galeria completa, especificações).
categoriesarray

Árvore de categorias, em lista plana com parent_id. Vazia no modo prateleira.

iduuid
Id da categoria.
namestring
Nome.
slugstring
Slug, para montar URLs.
parent_iduuid
Categoria pai. Ausente nas raízes.
product_countinteger
Quantos produtos a categoria lista para este cliente. Só vem na primeira página sem filtro; nas demais, ausente.
pageinteger
Página devolvida.
products_totalinteger
Total de produtos do catálogo para este cliente. Só na primeira página sem categoria nem filtro de característica.
commerce_profileobject
Perfil comercial da loja (segment, config, labels, capabilities).
copyobject
Mapa de textos da loja. Trate como opaco.
delivery_blockedobject
Presente quando a lista veio vazia porque nenhum seller entrega no destino do cliente. Tem destination (cidade/UF ou CEP).

Erros

StatusQuandoCorpo
400filling não é um dos valores aceitos.{"error":"invalid_filling"}
403Porta de entrada por documento fechada.{"error":"entry_required"}
403A loja exige login para navegar e o token é de visitante.{"error":"account_required","message":"Entre ou crie sua conta para ver os produtos e fazer seu pedido."}
500Falha ao ler o catálogo, ou category que não é UUID. O corpo traz a mensagem técnica.{"error":"..."}
503Catálogo indisponível.{"error":"catalog unavailable"} ou {"error":"catalog_unavailable"}
category aceita só UUID

Passar o slug (?category=notebooks) não devolve lista vazia: a rota responde 500 com a mensagem de erro do banco no corpo. Pegue o id na árvore categories e use-o em category.

Buscar produtos

GET/api/v1/storefront/wa-coex/search/{token}Pública

Busca produtos por texto, com sugestões quando nada casa

Usa a mesma busca da loja, com os mesmos resultados, ordem e total que o site para esse cliente. Quando nada casa com as palavras, a resposta traz sugestões (suggestions: true, total: 0).

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.

Parâmetros de consulta

qstring
Texto da busca. Vazio devolve a primeira página do catálogo.
idsstring
Ids de produtos separados por vírgula (os "Ver todas" de links antigos). Sem q, abrem exatamente esses produtos, nessa ordem. Com q, só aparecem como sugestões quando a busca não achou nada.
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora dessa faixa volta para 20.

Exemplo de requisição

bash
curl -G "$BASE_URL/api/v1/storefront/wa-coex/search/$TOKEN" \
  --data-urlencode "q=air fryer" \
  --data-urlencode "per_page=20"

Resposta

200Busca com resultados
json
{
  "products": [{ "id": "68836206-cb76-4814-9811-335f02e4e956", "name": "Air Fryer Eco Branco", "price_cents": 7992, "available": true }],
  "total": 71,
  "page": 1,
  "per_page": 20,
  "has_more": true,
  "suggestions": false,
  "description_only": false
}

Campos da resposta

productsarray
Produtos da página.
totalinteger
Total de resultados para as palavras. 0 quando são sugestões.
pageinteger
Página devolvida.
per_pageinteger
Itens por página aplicados.
has_moreboolean
Há próxima página (para rolagem infinita).
suggestionsboolean
Nada casou com as palavras e a lista são produtos próximos. Mostre sob um rótulo como "Sugestões".
description_onlyboolean
As palavras aparecem só na descrição dos produtos, não no nome, seller ou categoria. Só a primeira página é avaliada.

Erros

StatusQuandoCorpo
403Porta de entrada fechada, ou login exigido.{"error":"entry_required"} ou {"error":"account_required","message":"..."}
500Falha na busca.{"error":"..."}
503Catálogo indisponível.{"error":"catalog unavailable"}

Resumir produtos com opções

GET/api/v1/storefront/wa-coex/choose/{token}Pública

Resumo de produtos para a escolha de opções obrigatórias

Para uma lista de ids, devolve o essencial de cada produto mais as opções que o cliente precisa escolher (por exemplo, ponto da carne e adicionais). Serve para a tela de "escolha antes de adicionar", quando você já tem os ids e não quer abrir a ficha completa de cada um.

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.

Parâmetros de consulta

idsstring
Ids de produtos separados por vírgula. Vazio devolve lista vazia; ids inexistentes ou inacessíveis são omitidos.
200Produtos com opções
json
{
  "products": [
    {
      "id": "68836206-cb76-4814-9811-335f02e4e956",
      "name": "Air Fryer Eco Branco",
      "price_cents": 7992,
      "price_redacted": false,
      "image_url": "/uploads/.../air-fryer.png",
      "available": true,
      "options": null
    }
  ]
}

Campos da resposta

productsarray

Um item por id encontrado.

iduuid
Id do produto.
namestring
Nome.
price_centsinteger
Preço do cliente, em centavos. 0 se price_redacted.
price_redactedboolean
true quando o preço está escondido até o login.
image_urlstring
Foto principal.
availableboolean
Pode ser comprado agora.
optionsarray
Opções a escolher (id, name, type, required, values, choices, min_select, max_select). null quando o produto não tem opções.

Os erros são os mesmos de GET /catalog (403 de porta de entrada ou de login, 503 de catálogo).

Veja também

  • Ficha do produto
  • Variação e frete
  • Sacola
Anterior
Catálogo da mini-loja
Próxima
Ficha do produto
Nesta página
  • Listar o catálogo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Buscar produtos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Resumir produtos com opções
  • Veja também