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

Ficha do produto

Abre um produto com preço do cliente, fotos, opções e disponibilidade, e lê os produtos relacionados e a oferta de compre junto.

A ficha é a tela de decisão de compra. GET /product traz tudo que ela precisa numa chamada só; related e combo são leituras separadas para as faixas "Você também pode gostar" e "Compre junto", que só aparecem se a loja as usa.

Todas as três reaproveitam o preço do cliente do token: preço de tabela, faixas por quantidade e acordo com o representante só vêm para o cliente identificado, e com o preço escondido até o login o produto sai com price_redacted: true e valores zerados.

Abrir o produto

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

Ficha completa do produto para o cliente do token

Um produto que o seller não entrega no endereço do cliente não dá 404: vem com available: false e outside_delivery_area: true, para a tela explicar por que não pode comprar. Produto inexistente, inativo ou escondido deste canal dá 404.

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.
productIDuuidobrigatório
Id do produto.

Exemplo de requisição

Resposta

200Produto simples

Campos da resposta

iduuid
Id do produto.
namestring
Nome.
short_descriptionstring
Descrição curta.
descriptionstring
Descrição completa.
image_urlstring
Foto principal.
galleryarray
Caminhos de todas as fotos.
videosarray
Vídeos da galeria: url, poster, youtube_id, vimeo_id, kind (upload, youtube, vimeo ou live_clip), title.
slugstring
Slug do produto.
urlstring
Caminho público da página do produto na loja.
price_centsinteger
Preço atual para este cliente, em centavos, já com promoção. 0 se price_redacted.
list_price_centsinteger
Preço "de", maior que price_cents. Ausente quando não há desconto.
price_redactedboolean
true quando a loja esconde preço até o login e o cliente não está identificado.
tier_base_centsinteger
Preço-base do produto, referência da coluna "Desconto" da tabela de faixas.
qty_tiersarray
Faixas de preço por quantidade: min_qty, price_cents, percentage_discount, value_per_kg_cents, value_per_unit_cents. A primeira linha é a quantidade 1.
availableboolean
Pode ser comprado agora (estoque, venda sem estoque, janela de lançamento e área de entrega).
backorderboolean
Sem estoque, mas vendido sob encomenda; available fica true.
backorder_noticestring
Texto do aviso de encomenda da loja. Vazio significa o texto padrão.
backorder_notice_offboolean
A loja desligou o aviso de encomenda para este produto.
avail_sincestring
Data RFC 3339 de início das vendas, quando ainda no futuro ("em breve").
outside_delivery_areaboolean
O seller não entrega no destino do cliente.
delivery_destinationstring
Destino considerado (cidade/UF ou CEP).
sale_unitstring
Unidade de venda (por exemplo un, kg).
sale_unit_labelstring
Rótulo da unidade para exibir.
allow_fractionalboolean
Aceita quantidade fracionada (1,5 kg).
quantity_stepnumber
Passo da quantidade.
min_quantitynumber
Quantidade mínima por pedido.
max_quantitynumber
Quantidade máxima por pedido, a menor entre o limite do produto e o da loja. 0 ou ausente: sem limite.
vendor_namestring
Seller que vende ("Vendido por"). Vazio para produtos do vendedor padrão da loja.
seller_offersarray
"Outros vendedores" do mesmo produto em loja marketplace: product_id, vendor_name, price_cents, list_price_cents, available, current.
category_iduuid
Categoria principal.
category_idsarray
Todas as categorias do produto, a principal primeiro.
breadcrumbarray
Caminho da categoria principal, da raiz à folha: id e name.
skustring
Código SKU.
barcodestring
Código de barras.
brandstring
Marca.
promo_textstring
Texto promocional.
weight_kgnumber
Peso, em kg.
unit_weight_kgnumber
Peso de cada unidade, em kg.
units_per_boxinteger
Unidades por caixa.
sell_unitstring
Unidade de venda B2B do catálogo (KG, CX, PC).
price_per_kg_centsinteger
Preço por kg, em centavos, quando a unidade é peso.
price_per_unit_centsinteger
Preço por unidade dentro da caixa, em centavos.
rep_agreementobject
Preço combinado com o representante, só para o cliente identificado que tem um acordo vigente: price_cents, min_qty, rep_name, valid_until.
stock_amountinteger
Quantidade em estoque, quando a loja mostra o estoque.
stock_originsarray
Estoque por depósito, quando a loja deixa escolher a origem: warehouse_id, label, qty, available, is_default.
specsarray
Características do catálogo: name e value.
optionsarray
Opções que o cliente escolhe antes de comprar. Cada uma tem id, name, type, required, values, choices (id, value, label, modifier em centavos) e, para múltipla escolha, min_select e max_select.
needs_choiceboolean
O produto exige uma escolha (variação, grade, caixa ou opção obrigatória) antes de ir à sacola.
color_swatchesarray
Bolinhas de cor das variações: label, color.
fiscalobject
Linha de impostos, quando a loja mostra o detalhamento fiscal.
rating_avgnumber
Nota média das avaliações, quando a loja as mostra.
rating_countinteger
Número de avaliações.
stickersarray
Selos do produto: id, name_admin, name_desktop, name_mobile, style, appearance, display_on.
tagsarray
Nomes das etiquetas do produto.
delivery_forecast_daysinteger
Dias até a previsão de entrega do seller. 0 quando desligada.
attachmentsarray
Documentos da aba "Anexos": id, name, url, mime_type, size_bytes, description.
required_productsarray
Produtos obrigatórios que acompanham este: id, name, image_url, price_cents, price_redacted, available, mandatory.
look_tryonboolean
A categoria do produto habilita a prova virtual de look.
min_ageinteger
Idade mínima do comprador. 0 ou ausente: sem restrição.
requires_vehicle_fitmentboolean
Exige conferir a compatibilidade com o veículo.
requires_quoteboolean
Só vende sob cotação.
cold_chainboolean
Exige cadeia fria.
controlled_schedulestring
Classe de controle especial do produto, quando houver.
max_qty_per_orderinteger
Limite de quantidade por pedido de uma regra de conformidade.
requires_cnpjboolean
Só vende para empresa (CNPJ).

Os campos de texto vazios e os zeros que não significam nada são omitidos da resposta, então trate qualquer campo opcional como "pode faltar".

Erros

StatusQuandoCorpo
403Porta de entrada fechada, ou a loja exige login para ver produtos.{"error":"entry_required"} ou {"error":"account_required","message":"..."}
404Produto inexistente, inativo ou fora deste canal.{"error":"not_found"}
503Catálogo indisponível.{"error":"catalog unavailable"}
Nem tudo vem preenchido

Fiscal, origem do estoque, avaliações, selos e anexos dependem de funcionalidades da loja (store_caps). Se a funcionalidade está desligada, o campo simplesmente não existe na resposta.

Ler produtos relacionados

GET/api/v1/storefront/wa-coex/product/{token}/{productID}/relatedPública

Produtos relacionados à ficha aberta

Devolve até 12 produtos. A base é a curadoria do lojista; sem ela, os mais vendidos da mesma categoria. Cada item passa pelas mesmas regras de visibilidade e preço do catálogo. Sempre responde 200: se o produto de origem não está visível neste canal, a lista vem vazia.

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.
productIDuuidobrigatório
Produto de origem.
200Relacionados

Campos da resposta

productsarray
Até 12 produtos, no formato da ficha (sem os campos que só a ficha preenche). [] quando não há.

Os erros possíveis são o 403 de porta de entrada ou de login.

Ler a oferta de compre junto

GET/api/v1/storefront/wa-coex/product/{token}/{productID}/comboPública

Combo 'compre junto' do produto, com o desconto do combo

O "compre junto" é um combo de produtos com desconto, cadastrado pelo lojista. A rota só devolve oferta se a loja ligou o recurso (wa.pdp.buy_together) e todos os produtos do combo estão disponíveis, são vendidos neste canal, têm preço visível para o cliente e não exigem escolha de opção. Em qualquer outro caso, combo: null.

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.
productIDuuidobrigatório
Produto de origem do combo.
200Combo oferecido

Campos da resposta

comboobject

A oferta, ou null.

bundle_iduuid
Id do combo. Envie em POST /cart/{token}/combo.
anchor_iduuid
O produto da ficha aberta.
itemsarray
Produtos do combo, cada um com product (formato da ficha) e qty.
total_centsinteger
Soma dos preços avulsos, em centavos.
combo_centsinteger
Preço do combo, em centavos.
savings_centsinteger
Economia (total_cents - combo_cents).

Veja também

  • Variação e frete
  • Listar e buscar produtos
  • Sacola
Anterior
Listar e buscar produtos
Próxima
Variação e frete na ficha
Nesta página
  • Abrir o produto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler produtos relacionados
  • Ler a oferta de compre junto
  • Veja também
bash
curl "$BASE_URL/api/v1/storefront/wa-coex/product/$TOKEN/$PRODUCT_ID"
json
{
  "id": "68836206-cb76-4814-9811-335f02e4e956",
  "name": "Air Fryer Eco Branco",
  "short_description": "Air Fryer Eco Branco, qualidade premium com envio rápido.",
  "image_url": "/uploads/.../air-fryer.png",
  "gallery": ["/uploads/.../air-fryer.png"],
  "slug": "air-fryer-eco-branco-2431",
  "url": "/p/air-fryer-eco-branco-2431",
  "price_cents": 7992,
  "list_price_cents": 9990,
  "tier_base_cents": 9990,
  "available": true,
  "sale_unit": "un",
  "sale_unit_label": "un",
  "quantity_step": 1,
  "min_quantity": 1,
  "vendor_name": "Loja Seller Teste",
  "category_id": "0d209d61-abda-4424-945f-8bd538e9bb5a",
  "breadcrumb": [
    { "id": "759fe1cf-af87-420f-9f8e-b5d73f8ee029", "name": "Eletrodomésticos" },
    { "id": "0d209d61-abda-4424-945f-8bd538e9bb5a", "name": "Air Fryers" }
  ],
  "sku": "SD-002431",
  "stock_amount": 3,
  "specs": [{ "name": "Cor", "value": "Branco" }]
}
json
{ "products": [{ "id": "b6c4...", "name": "Fritadeira Digital 4L", "price_cents": 28900, "available": true }] }
json
{
  "combo": {
    "bundle_id": "0f6a1b2c-3d4e-4f50-8a9b-1c2d3e4f5a6b",
    "anchor_id": "68836206-cb76-4814-9811-335f02e4e956",
    "items": [
      { "product": { "id": "68836206-cb76-4814-9811-335f02e4e956", "name": "Air Fryer Eco Branco", "price_cents": 7992 }, "qty": 1 },
      { "product": { "id": "9d8c...", "name": "Forma antiaderente", "price_cents": 2990 }, "qty": 1 }
    ],
    "total_cents": 10982,
    "combo_cents": 9900,
    "savings_cents": 1082
  }
}