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

bash

curl "$BASE_URL/api/v1/storefront/suggested-lists" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Listas

json

{
  "lists": [
    {
      "id": "0d3b7c8e-5a1f-4c52-8f0e-2b6c1f4a9d11",
      "name": "Kit Churrasco",
      "description": "Tudo para o fim de semana.",
      "card_name": "Para a família",
      "group_name": "Churrasco",
      "image_url": "/uploads/kits/churrasco.png",
      "kit_price": 18900,
      "status": "A",
      "position": 1,
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-09-01T12:00:00Z",
      "items": [
        {
          "id": "9a8d7c6b-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
          "list_id": "0d3b7c8e-5a1f-4c52-8f0e-2b6c1f4a9d11",
          "product_id": "db033935-75ea-4b6f-abbb-13d0fcd6386d",
          "quantity": 2,
          "position": 0,
          "product_name": "Camiseta Lite Verde 00146",
          "product_slug": "camiseta-lite-verde-00146-146",
          "product_price": 9990,
          "product_image": "/uploads/dfe2555e/foto.png",
          "product_sku": "CAM-00146",
          "in_stock": true
        }
      ],
      "total_price": 19980,
      "final_price": 18900,
      "discount_pct": 5
    }
  ],
  "clear_cart_on_add": false
}

200Uma lista

json

{
  "list": { "id": "0d3b7c8e-5a1f-4c52-8f0e-2b6c1f4a9d11", "name": "Kit Churrasco", "final_price": 18900, "items": [] },
  "clear_cart_on_add": false
}

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

bash

curl "$BASE_URL/api/v1/storefront/suggested-lists" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Listas

json

{
  "lists": [
    {
      "id": "0d3b7c8e-5a1f-4c52-8f0e-2b6c1f4a9d11",
      "name": "Kit Churrasco",
      "description": "Tudo para o fim de semana.",
      "card_name": "Para a família",
      "group_name": "Churrasco",
      "image_url": "/uploads/kits/churrasco.png",
      "kit_price": 18900,
      "status": "A",
      "position": 1,
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-09-01T12:00:00Z",
      "items": [
        {
          "id": "9a8d7c6b-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
          "list_id": "0d3b7c8e-5a1f-4c52-8f0e-2b6c1f4a9d11",
          "product_id": "db033935-75ea-4b6f-abbb-13d0fcd6386d",
          "quantity": 2,
          "position": 0,
          "product_name": "Camiseta Lite Verde 00146",
          "product_slug": "camiseta-lite-verde-00146-146",
          "product_price": 9990,
          "product_image": "/uploads/dfe2555e/foto.png",
          "product_sku": "CAM-00146",
          "in_stock": true
        }
      ],
      "total_price": 19980,
      "final_price": 18900,
      "discount_pct": 5
    }
  ],
  "clear_cart_on_add": false
}

200Uma lista

json

{
  "list": { "id": "0d3b7c8e-5a1f-4c52-8f0e-2b6c1f4a9d11", "name": "Kit Churrasco", "final_price": 18900, "items": [] },
  "clear_cart_on_add": false
}

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":"..."}`