API atual/Referência completa/Mini-loja WhatsApp: catálogo

Favoritos

Lista, adiciona e remove favoritos da conta do cliente na mini-loja e coloca os favoritos na sacola de uma vez.

Os favoritos da mini-loja são a lista de desejos da conta do cliente: a mesma que o assistente do WhatsApp salva e a que o site mostra. Por isso só existem para cliente identificado; um visitante recebe logged_in: false na leitura e 401 login_required nas escritas.

Quando o cliente favorita um produto com opções ou variação já escolhidas (por exemplo "bem passado, com bacon", ou cor e tamanho), a escolha é guardada junto, e "Adicionar todos à sacola" a reaproveita.

Leitura, adição e remoção dependem de a loja ter a lista de desejos ligada; desligada, as três respondem 403 {"error":"feature_not_available","feature":"wishlist","detail":"switched off for this store"}.

Listar os favoritos

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

Produtos favoritos do cliente e as escolhas guardadas

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/favorites/$TOKEN"

Resposta

200Favoritos do cliente

json

{
  "logged_in": true,
  "products": [
    { "id": "68836206-cb76-4814-9811-335f02e4e956", "name": "Air Fryer Eco Branco", "price_cents": 7992, "available": true }
  ],
  "saved_options": {
    "68836206-cb76-4814-9811-335f02e4e956": { "label": "Ponto: Ao ponto", "options": [{ "option_id": "p1", "value": "Ao ponto" }] }
  }
}

Campos da resposta

logged_inboolean

O token tem conta identificada. Se false, products vem vazio.

productsarray

Produtos favoritados, com o preço do cliente (formato da ficha). [] quando não há.

saved_optionsobject

Mapa id do produto para a escolha guardada junto: label (texto das opções), options (as opções escolhidas), variation_label e selections (escolhas de variação). Só aparecem produtos que têm escolha guardada.

Erros

Status	Quando	Corpo
403	Lista de desejos desligada na loja.	`{"error":"feature_not_available","feature":"wishlist","detail":"switched off for this store"}`
403	Porta de entrada fechada, ou login exigido.	`{"error":"entry_required"}` ou `{"error":"account_required","message":"..."}`
502	Falha ao ler.	`{"error":"favorites_unavailable"}`

Favoritar um produto

POST/api/v1/storefront/wa-coex/favorites/{token}/{productID}Pública

Adiciona um produto aos favoritos, com as escolhas feitas

É idempotente: favoritar de novo um produto que já está na lista só atualiza a escolha guardada.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Corpo da requisição

optionsarray

Opções escolhidas (lista de option_id e value). Se alguma não existe mais no produto, a escolha é descartada, sem erro.

configurationobject

Escolhas de variação e caixa, no formato de configuration: selections, box_type, box_id. Só é guardada se resolver para um item completo.

O corpo é opcional.

200Favoritado

json

{ "status": "saved", "label": "" }

Campos da resposta

statusstring

savedalreadyupdated

saved: entrou agora. already: já estava, nada mudou. updated: já estava e a escolha guardada mudou.

labelstring

Texto da escolha guardada para exibir. Vazio sem escolha.

Erros

Status	Quando	Corpo
400	`productID` vazio ou corpo inválido.	`{"error":"product_required"}` ou `{"error":"invalid_body"}`
401	O token não tem conta identificada.	`{"error":"login_required"}`
404	O produto não existe mais.	`{"error":"product_gone"}`
502	Falha ao gravar.	`{"error":"favorites_unavailable"}`

Remover um favorito

DELETE/api/v1/storefront/wa-coex/favorites/{token}/{productID}Pública

Remove um produto dos favoritos

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Responde 204 No Content, sem corpo. Erros: 401 {"error":"login_required"} sem conta identificada; 400 {"error":"product_required"}; 502 {"error":"favorites_unavailable"}.

Colocar os favoritos na sacola

POST/api/v1/storefront/wa-coex/cart/{token}/favoritesPública

Adiciona favoritos à sacola, revalidando cada item

É o "Adicionar todos à sacola". Cada favorito é revalidado contra o catálogo de hoje: o que saiu do ar, está sem estoque ou exige uma escolha obrigatória que agora existe volta na lista skipped (ou pending) com o motivo, e o resto entra. O que já está na sacola não é duplicado. Usa as opções e a variação guardadas com o favorito. No máximo 200 favoritos por chamada.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_idsarray

Ids de produtos favoritos a adicionar. Vazio ou ausente: todos os favoritos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/favorites" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta

200Resultado da adição

json

{
  "added": 2,
  "skipped": [{ "name": "Mouse sem fio", "reason": "stock", "product_id": "3a872b9c-45e3-4307-85b2-e9a07ef7db06" }],
  "already_in_cart": 1,
  "cart": { "cart_id": "74481399-0286-4dd1-ac8e-13328e00b86d", "items": [], "subtotal_cents": 15984, "total_cents": 15984, "currency": "BRL", "item_count": 2 }
}

Campos da resposta

addedinteger

Quantos itens entraram.

skippedarray

Itens que não entraram: name, reason (unavailable saiu do catálogo, needs_choice exige uma opção obrigatória, stock sem estoque suficiente) e product_id.

already_in_cartinteger

Itens que a sacola já tinha na quantidade pedida.

cartobject

A sacola depois da operação, no formato de Ler a sacola.

pendingarray

Itens que entraram mas ainda esperam uma escolha obrigatória (mesmo formato de skipped). O checkout recusa a sacola até cada um ser resolvido.

Erros

Status	Quando	Corpo
400	Corpo ilegível.	`{"error":"invalid_body"}`
401	O token não tem conta identificada.	`{"error":"login_required"}`
403	A loja exige conta para mexer na sacola.	`{"error":"account_required","message":"Entre ou crie sua conta para adicionar produtos."}`
502	Falha ao ler os favoritos.	`{"error":"favorites_unavailable"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: catálogo

Favoritos

Lista, adiciona e remove favoritos da conta do cliente na mini-loja e coloca os favoritos na sacola de uma vez.

Listar os favoritos

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

Produtos favoritos do cliente e as escolhas guardadas

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/favorites/$TOKEN"

Resposta

200Favoritos do cliente

json

{
  "logged_in": true,
  "products": [
    { "id": "68836206-cb76-4814-9811-335f02e4e956", "name": "Air Fryer Eco Branco", "price_cents": 7992, "available": true }
  ],
  "saved_options": {
    "68836206-cb76-4814-9811-335f02e4e956": { "label": "Ponto: Ao ponto", "options": [{ "option_id": "p1", "value": "Ao ponto" }] }
  }
}

Campos da resposta

logged_inboolean

O token tem conta identificada. Se false, products vem vazio.

productsarray

Produtos favoritados, com o preço do cliente (formato da ficha). [] quando não há.

saved_optionsobject

Erros

Status	Quando	Corpo
403	Lista de desejos desligada na loja.	`{"error":"feature_not_available","feature":"wishlist","detail":"switched off for this store"}`
403	Porta de entrada fechada, ou login exigido.	`{"error":"entry_required"}` ou `{"error":"account_required","message":"..."}`
502	Falha ao ler.	`{"error":"favorites_unavailable"}`

Favoritar um produto

POST/api/v1/storefront/wa-coex/favorites/{token}/{productID}Pública

Adiciona um produto aos favoritos, com as escolhas feitas

É idempotente: favoritar de novo um produto que já está na lista só atualiza a escolha guardada.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Corpo da requisição

optionsarray

Opções escolhidas (lista de option_id e value). Se alguma não existe mais no produto, a escolha é descartada, sem erro.

configurationobject

Escolhas de variação e caixa, no formato de configuration: selections, box_type, box_id. Só é guardada se resolver para um item completo.

O corpo é opcional.

200Favoritado

json

{ "status": "saved", "label": "" }

Campos da resposta

statusstring

savedalreadyupdated

saved: entrou agora. already: já estava, nada mudou. updated: já estava e a escolha guardada mudou.

labelstring

Texto da escolha guardada para exibir. Vazio sem escolha.

Erros

Status	Quando	Corpo
400	`productID` vazio ou corpo inválido.	`{"error":"product_required"}` ou `{"error":"invalid_body"}`
401	O token não tem conta identificada.	`{"error":"login_required"}`
404	O produto não existe mais.	`{"error":"product_gone"}`
502	Falha ao gravar.	`{"error":"favorites_unavailable"}`

Remover um favorito

DELETE/api/v1/storefront/wa-coex/favorites/{token}/{productID}Pública

Remove um produto dos favoritos

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Responde 204 No Content, sem corpo. Erros: 401 {"error":"login_required"} sem conta identificada; 400 {"error":"product_required"}; 502 {"error":"favorites_unavailable"}.

Colocar os favoritos na sacola

POST/api/v1/storefront/wa-coex/cart/{token}/favoritesPública

Adiciona favoritos à sacola, revalidando cada item

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_idsarray

Ids de produtos favoritos a adicionar. Vazio ou ausente: todos os favoritos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/favorites" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta

200Resultado da adição

json

{
  "added": 2,
  "skipped": [{ "name": "Mouse sem fio", "reason": "stock", "product_id": "3a872b9c-45e3-4307-85b2-e9a07ef7db06" }],
  "already_in_cart": 1,
  "cart": { "cart_id": "74481399-0286-4dd1-ac8e-13328e00b86d", "items": [], "subtotal_cents": 15984, "total_cents": 15984, "currency": "BRL", "item_count": 2 }
}

Campos da resposta

addedinteger

Quantos itens entraram.

skippedarray

Itens que não entraram: name, reason (unavailable saiu do catálogo, needs_choice exige uma opção obrigatória, stock sem estoque suficiente) e product_id.

already_in_cartinteger

Itens que a sacola já tinha na quantidade pedida.

cartobject

A sacola depois da operação, no formato de Ler a sacola.

pendingarray

Itens que entraram mas ainda esperam uma escolha obrigatória (mesmo formato de skipped). O checkout recusa a sacola até cada um ser resolvido.

Erros

Status	Quando	Corpo
400	Corpo ilegível.	`{"error":"invalid_body"}`
401	O token não tem conta identificada.	`{"error":"login_required"}`
403	A loja exige conta para mexer na sacola.	`{"error":"account_required","message":"Entre ou crie sua conta para adicionar produtos."}`
502	Falha ao ler os favoritos.	`{"error":"favorites_unavailable"}`