API atual/Referência completa/Recomendações e compartilhamento

Listas sugeridas

Lista os kits de produtos montados pelo lojista (por exemplo "kit churrasco") e devolve o detalhe de um kit, com itens, quantidades e preço final.

Uma lista sugerida é um kit curado pelo lojista: um conjunto de produtos com a quantidade recomendada de cada um e, opcionalmente, um preço fechado para o kit todo. A vitrine mostra as listas em uma página própria e deixa o cliente adicionar todos os itens ao carrinho de uma vez. Quem cria e edita as listas é o lojista, no painel; estas rotas são só de leitura.

Duas regras de loja mudam o comportamento:

O recurso é um módulo: em lojas onde ele está desligado, as duas rotas respondem 403 module_disabled.
O módulo tem a opção "exigir login" (ligada por padrão). Ligada, um visitante sem token recebe 401 login_required; a vitrine costuma mostrar um convite "Entre para comprar". Desligada, a lista é pública e, se a loja esconde preço de visitante, os valores vêm zerados com price_redacted: true.

Só listas ativas aparecem, ordenadas pela posição que o lojista definiu.

GET/api/v1/storefront/suggested-listsAutenticada

Listar as listas sugeridas ativas

Cabeçalhos

Authorizationstring

Bearer $TOKEN de um cliente logado. Obrigatório quando a loja exige login para ver as listas.

GET/api/v1/storefront/suggested-lists/{id}Autenticada

Consultar uma lista sugerida

Parâmetros de caminho

iduuidobrigatório

Id da lista.

Exemplo de requisição

Resposta

200Listas

200Uma lista

A loja de teste usada na documentação não tem o módulo ligado, então os exemplos de resposta acima são ilustrativos e seguem o contrato do código. O exemplo da lista única está resumido.

Campos da resposta

listsarray

Em GET /suggested-lists: listas ativas, por posição.

listobject

Em GET /suggested-lists/{id}: a lista pedida.

clear_cart_on_addboolean

Opção do módulo: quando true, a vitrine deve esvaziar o carrinho antes de adicionar os itens do kit. Quem adiciona os itens é a sua vitrine, um a um; as rotas de lista não mexem no carrinho.

iduuid

Id da lista (campo de cada lista).

namestring

Nome da lista.

descriptionstring

Descrição.

card_namestring

Nome do cartão de agrupamento de nível mais alto na página "ver todas". Agrupar é com a vitrine.

group_namestring

Subgrupo dentro do cartão.

image_urlstring

Imagem do kit.

kit_priceinteger

Preço fechado do kit em centavos; null quando o kit não tem preço próprio (o total é a soma dos itens).

statusstring

Sempre A (ativa) na vitrine.

positioninteger

Posição de exibição, do menor para o maior.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

itemsarray

Produtos do kit.

items[].iduuid

Id da linha do kit.

items[].list_iduuid

Id da lista.

items[].product_iduuid

Id do produto, para adicionar ao carrinho.

items[].quantityinteger

Quantidade recomendada de cada produto.

items[].positioninteger

Posição do item no kit.

items[].product_namestring

Nome do produto.

items[].product_slugstring

Trecho do endereço da página do produto.

items[].product_priceinteger

Preço unitário em centavos.

items[].product_imagestring

Caminho da imagem.

items[].product_skustring

SKU.

items[].in_stockboolean

false para item indisponível: mostre "indisponível" e sem botão de compra.

items[].price_redactedboolean

true quando o preço foi zerado para o visitante.

total_priceinteger

Soma de preço unitário vezes quantidade de todos os itens, em centavos.

final_priceinteger

kit_price quando existe e é menor que total_price; senão total_price. Em centavos.

discount_pctinteger

Percentual de desconto do kit para o selo "% OFF". 0 quando não há desconto.

price_redactedboolean

true quando os valores da lista foram zerados para o visitante.

Erros

Status	Quando	Corpo
401	A loja exige login para ver as listas e a chamada não tem token	`{"error":"login_required","detail":"sign in to view suggested lists"}`
401	A loja exige login para navegar	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	O módulo de listas sugeridas está desligado na loja	`{"error":"module_disabled","module":"suggested-lists"}`
404	`GET /suggested-lists/{id}`: lista inexistente ou inativa	`{"error":"suggested list not found"}`
500	Falha ao ler as listas	`{"error":"failed to list suggested lists","detail":"..."}`

Veja também

Listas sugeridas

Lista os kits de produtos montados pelo lojista (por exemplo "kit churrasco") e devolve o detalhe de um kit, com itens, quantidades e preço final.

Duas regras de loja mudam o comportamento:

O recurso é um módulo: em lojas onde ele está desligado, as duas rotas respondem 403 module_disabled.
O módulo tem a opção "exigir login" (ligada por padrão). Ligada, um visitante sem token recebe 401 login_required; a vitrine costuma mostrar um convite "Entre para comprar". Desligada, a lista é pública e, se a loja esconde preço de visitante, os valores vêm zerados com price_redacted: true.

Só listas ativas aparecem, ordenadas pela posição que o lojista definiu.

GET/api/v1/storefront/suggested-listsAutenticada

Listar as listas sugeridas ativas

Cabeçalhos

Authorizationstring

Bearer $TOKEN de um cliente logado. Obrigatório quando a loja exige login para ver as listas.

GET/api/v1/storefront/suggested-lists/{id}Autenticada

Consultar uma lista sugerida

Parâmetros de caminho

iduuidobrigatório

Id da lista.

Exemplo de requisição

Resposta

200Listas

200Uma lista

A loja de teste usada na documentação não tem o módulo ligado, então os exemplos de resposta acima são ilustrativos e seguem o contrato do código. O exemplo da lista única está resumido.

Campos da resposta

listsarray

Em GET /suggested-lists: listas ativas, por posição.

listobject

Em GET /suggested-lists/{id}: a lista pedida.

clear_cart_on_addboolean

iduuid

Id da lista (campo de cada lista).

namestring

Nome da lista.

descriptionstring

Descrição.

card_namestring

Nome do cartão de agrupamento de nível mais alto na página "ver todas". Agrupar é com a vitrine.

group_namestring

Subgrupo dentro do cartão.

image_urlstring

Imagem do kit.

kit_priceinteger

Preço fechado do kit em centavos; null quando o kit não tem preço próprio (o total é a soma dos itens).

statusstring

Sempre A (ativa) na vitrine.

positioninteger

Posição de exibição, do menor para o maior.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

itemsarray

Produtos do kit.

items[].iduuid

Id da linha do kit.

items[].list_iduuid

Id da lista.

items[].product_iduuid

Id do produto, para adicionar ao carrinho.

items[].quantityinteger

Quantidade recomendada de cada produto.

items[].positioninteger

Posição do item no kit.

items[].product_namestring

Nome do produto.

items[].product_slugstring

Trecho do endereço da página do produto.

items[].product_priceinteger

Preço unitário em centavos.

items[].product_imagestring

Caminho da imagem.

items[].product_skustring

SKU.

items[].in_stockboolean

false para item indisponível: mostre "indisponível" e sem botão de compra.

items[].price_redactedboolean

true quando o preço foi zerado para o visitante.

total_priceinteger

Soma de preço unitário vezes quantidade de todos os itens, em centavos.

final_priceinteger

kit_price quando existe e é menor que total_price; senão total_price. Em centavos.

discount_pctinteger

Percentual de desconto do kit para o selo "% OFF". 0 quando não há desconto.

price_redactedboolean

true quando os valores da lista foram zerados para o visitante.

Erros

Status	Quando	Corpo
401	A loja exige login para ver as listas e a chamada não tem token	`{"error":"login_required","detail":"sign in to view suggested lists"}`
401	A loja exige login para navegar	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	O módulo de listas sugeridas está desligado na loja	`{"error":"module_disabled","module":"suggested-lists"}`
404	`GET /suggested-lists/{id}`: lista inexistente ou inativa	`{"error":"suggested list not found"}`
500	Falha ao ler as listas	`{"error":"failed to list suggested lists","detail":"..."}`