VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Catálogo: kits, mix e compartilhamento

Listas sugeridas

Cria e gerencia kits prontos, com produtos e quantidades prescritas e um preço combinado opcional, exibidos na vitrine.

Uma lista sugerida é um kit fixo: um conjunto de produtos, cada um com uma quantidade prescrita, mais um preço de kit opcional. É a ferramenta para vender "o enxoval completo" ou "o kit da reposição do mês" de uma vez. A vitrine mostra as listas agrupadas por card_name (cartão) e group_name (subgrupo), com o total, o preço final e o selo de "% OFF".

Diferente do mix, o cliente não monta nem troca itens: a lista é o que está definida aqui. As rotas exigem o módulo suggested-lists ligado e o privilégio manage_promotions.

O preço do kit é só exibido, não aplicado sozinho

A plataforma calcula e mostra total_price, final_price e discount_pct, mas criar ou alterar a lista não cria a promoção que aplica o desconto no carrinho. Se o kit tem preço combinado, uma promoção de carrinho equivalente precisa existir à parte. Sem ela, o carrinho cobra o preço normal dos itens.

Listar kits

GET/api/v1/admin/suggested-listsAdmin

Listar as listas sugeridas

Devolve as listas com os totais calculados, em páginas.

Parâmetros de consulta

pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
De 1 a 100. Fora disso vale 20.
statusstring
ADH
Filtra por status. Aceita a letra ou a palavra.
searchstring
Busca por texto no nome.
bash
curl "$BASE_URL/api/v1/admin/suggested-lists?status=A" \
  -H "Authorization: Bearer $TOKEN"
200Página de listas
json
{
  "lists": [
    {
      "id": "3d8f6a21-7c40-4b19-8e05-91a2c4d7b6f3",
      "name": "Kit Reposição Verão",
      "description": "Os 3 itens mais vendidos do mês",
      "card_name": "Reposição",
      "group_name": "Verão",
      "image_url": "",
      "kit_price": 8990,
      "status": "A",
      "position": 0,
      "total_price": 10970,
      "final_price": 8990,
      "discount_pct": 18,
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10,
  "total_pages": 1
}

Criar um kit

POST/api/v1/admin/suggested-listsAdmin

Criar uma lista sugerida

Cria a lista com seus itens e devolve o kit completo (201).

Corpo da requisição

namestringobrigatório
Nome do kit.
descriptionstring
Descrição.
card_namestring
Cartão de agrupamento na página de listas da vitrine.
group_namestring
Subgrupo dentro do cartão.
image_urlstring
Imagem do kit.
kit_priceinteger
Preço combinado, em centavos. Ausente ou null significa "soma dos itens". Se for maior que a soma, vale a soma.
statusstringpadrão: A
ADH
Status. A API aceita a letra ou a palavra (active, disabled). Vazio vira A.
positionintegerpadrão: 0
Ordem de exibição.
itemsarray

Produtos do kit.

product_iduuidobrigatório
Produto.
quantityinteger
Quantidade prescrita. Menos de 1 conta como 1 no total.
positioninteger
Ordem do item no kit.
bash
curl -X POST "$BASE_URL/api/v1/admin/suggested-lists" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kit Reposição Verão",
    "card_name": "Reposição",
    "kit_price": 8990,
    "items": [{"product_id": "ab3f1a07-2ae2-45b7-a4be-bcb67314d601", "quantity": 2}]
  }'

Ler um kit

GET/api/v1/admin/suggested-lists/{id}Admin

Ler uma lista sugerida com seus itens

Parâmetros de caminho

iduuidobrigatório
Id da lista.
bash
curl "$BASE_URL/api/v1/admin/suggested-lists/3d8f6a21-7c40-4b19-8e05-91a2c4d7b6f3" \
  -H "Authorization: Bearer $TOKEN"

Resposta (criar, ler e alterar)

200Kit completo

A criação responde 201 com o mesmo corpo.

json
{
  "id": "3d8f6a21-7c40-4b19-8e05-91a2c4d7b6f3",
  "name": "Kit Reposição Verão",
  "description": "",
  "card_name": "Reposição",
  "group_name": "",
  "image_url": "",
  "kit_price": 8990,
  "status": "A",
  "position": 0,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-01T12:00:00Z",
  "items": [
    {
      "id": "e5a1c7d3-92b4-4f60-8a1d-3c7e9b2f4a68",
      "list_id": "3d8f6a21-7c40-4b19-8e05-91a2c4d7b6f3",
      "product_id": "ab3f1a07-2ae2-45b7-a4be-bcb67314d601",
      "quantity": 2,
      "position": 0,
      "product_name": "Chinelo Clássico",
      "product_slug": "chinelo-classico",
      "product_price": 5485,
      "product_image": "/uploads/chinelo.png",
      "product_sku": "CHI-001",
      "in_stock": true
    }
  ],
  "total_price": 10970,
  "final_price": 8990,
  "discount_pct": 18
}

Campos da resposta

iduuid
Id da lista.
namestring
Nome.
descriptionstring
Descrição.
card_namestring
Cartão de agrupamento.
group_namestring
Subgrupo.
image_urlstring
Imagem.
kit_priceinteger
Preço combinado em centavos. null quando não há.
statusstring
ADH
Status em letra.
positioninteger
Ordem de exibição.
itemsarray
Itens, só na leitura e na criação de um kit. Cada um traz id, list_id, product_id, quantity, position, e do produto product_name, product_slug, product_price (centavos por unidade), product_image, product_sku e in_stock.
items[].in_stockboolean
false quando o produto está inativo ou sem estoque.
total_priceinteger
Soma de preço unitário vezes quantidade de todos os itens, em centavos. O estoque não entra na conta.
final_priceinteger
kit_price quando existe e é menor que total_price; senão, total_price.
discount_pctinteger
Percentual de desconto arredondado. 0 sem desconto efetivo.
created_atstring
RFC 3339, UTC.
updated_atstring
RFC 3339, UTC.

Alterar um kit

PUT/api/v1/admin/suggested-lists/{id}Admin

Alterar uma lista sugerida

Atualização parcial. Para limpar o preço do kit (voltar a "soma dos itens"), envie kit_price_set: true com kit_price: null; só enviar kit_price: null é ignorado. Se enviar items, substitui todos os itens. Devolve o kit completo.

Parâmetros de caminho

iduuidobrigatório
Id da lista.

Corpo da requisição

namestring
Nome.
descriptionstring
Descrição.
card_namestring
Cartão.
group_namestring
Subgrupo.
image_urlstring
Imagem.
kit_price_setboolean
true indica que kit_price deve ser aplicado, inclusive quando null.
kit_priceinteger
Novo preço combinado em centavos. Só vale com kit_price_set: true.
statusstring
ADH
Status.
positioninteger
Ordem de exibição.
itemsarray
Lista completa de itens (product_id, quantity, position). Substitui a atual.
bash
curl -X PUT "$BASE_URL/api/v1/admin/suggested-lists/3d8f6a21-7c40-4b19-8e05-91a2c4d7b6f3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kit_price_set": true, "kit_price": null}'

Apagar um kit

DELETE/api/v1/admin/suggested-lists/{id}Admin

Apagar uma lista sugerida

Remove a lista e seus itens. É idempotente: apagar um id que não existe também responde 200.

Parâmetros de caminho

iduuidobrigatório
Id da lista.
bash
curl -X DELETE "$BASE_URL/api/v1/admin/suggested-lists/3d8f6a21-7c40-4b19-8e05-91a2c4d7b6f3" \
  -H "Authorization: Bearer $TOKEN"
200Lista apagada
json
{ "message": "suggested list deleted" }

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid request body","detail":"..."}
400Criação sem name.{"error":"name is required"}
401Sem token ou token expirado.{"error":"invalid or expired token"}
403Módulo desligado.{"error":"module_disabled","module":"suggested-lists"}
403Sem manage_promotions.{"error":"insufficient privileges","required":"manage_promotions"}
404Lista inexistente em GET ou PUT.{"error":"suggested list not found"}
500Falha ao gravar, {id} que não é UUID ou produto inexistente num item.{"error":"failed to create suggested list","detail":"..."}
Total mostra preço cheio mesmo sem estoque

total_price soma todos os itens, inclusive os sem estoque. Use items[].in_stock para avisar o cliente.

Veja também

  • Mix de produtos
  • Kits, mix e compartilhamento
Anterior
Mix de produtos
Próxima
Modo catálogo
Nesta página
  • Listar kits
  • Criar um kit
  • Ler um kit
  • Resposta (criar, ler e alterar)
  • Alterar um kit
  • Apagar um kit
  • Erros
  • Veja também