VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Kits, mestres e caixas

Kits

Lista os kits ativos da loja e abre um kit pelo slug, com os produtos, o preço calculado e o preço final com desconto.

Um kit (bundle) é uma lista fixa de produtos vendidos juntos, com um preço próprio: a soma dos itens, um preço fixo ou a soma com desconto. É útil para a página "Kits e combos" e para o destaque de combos em páginas de produto.

Só aparecem kits ativos e da loja (sem seller dono). Kits criados por um seller e os kits automáticos de "compre junto" (slug começando em fbt-) não saem na lista.

GET/api/v1/storefront/bundlesPública

Listar kits ativos

Mais novos primeiro. Responde 401 shopping_requires_login a visitante quando a loja só permite navegar logado.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1. Valor inválido ou menor que 1 volta à página 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora desse intervalo (inclusive 0) volta ao padrão 20, não ao máximo.

Exemplo de requisição

Resposta

200Kits retornados

Campos da resposta

bundlesarray
Kits da página, do mais novo ao mais antigo.
totalinteger
Total de kits que atendem ao filtro, em todas as páginas.
pageinteger
Página devolvida.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Total de páginas.

Os campos de cada kit são os mesmos do detalhe, descritos abaixo.

GET/api/v1/storefront/bundles/{slug}Pública

Detalhe de um kit pelo slug

Devolve um kit ativo e da loja, com os itens e os preços calculados. Um kit inativo, de seller ou inexistente responde 404.

Parâmetros de caminho

slugstringobrigatório
Slug do kit (texto), por exemplo kit-cozinha.

Exemplo de requisição (detalhe)

Resposta (detalhe)

200Kit com preço fixo e desconto percentual

Campos da resposta

iduuid
Id do kit.
namestring
Nome.
slugstring
Identificador textual usado na URL do detalhe.
descriptionstring
Descrição, pode ser vazia.
price_bpsinteger
Preço fixo do kit em centavos (apesar do nome). 0 significa "sem preço fixo".
price_overrideinteger
Espelho de price_bps, mesmo valor.
discount_typestring
nonepercentagefixed
Como interpretar discount_bps.
discount_bpsinteger
Desconto: basis points quando percentage (1000 = 10%), centavos quando fixed.
discount_valueinteger
Espelho de discount_bps, mesmo valor.
statusstring
Sempre A (ativo) nesta rota.
image_urlstring
Imagem do kit, pode ser vazia.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).
itemsarray
Produtos do kit.
items[].iduuid
Id do item.
items[].bundle_iduuid
Id do kit.
items[].product_iduuid
Id do produto.
items[].quantityinteger
Unidades do produto no kit.
items[].sort_orderinteger
Posição de exibição.
items[].product_namestring
Nome do produto. Ausente se o produto não existe mais.
items[].slugstring
Slug do produto, para o link da página dele. Ausente se o produto não existe mais.
items[].product_priceinteger
Preço unitário do produto em centavos. Ausente se o produto não existe mais.
items[].product_imagestring
Imagem principal do produto.
items[].product_skustring
SKU do produto.
calculated_priceinteger
Soma de product_price x quantity dos itens, em centavos. Ausente quando o total é zero.
final_priceinteger
Preço do kit em centavos: price_bps se maior que zero; senão calculated_price menos o desconto; nunca negativo. Ausente quando o resultado é zero.

Erros

StatusQuandoCorpo
401A loja exige login para navegar e a chamada é anônima.{"error":"shopping_requires_login","message":"this storefront requires login to browse"}
404Kit inexistente, inativo ou de seller (detalhe).{"error":"bundle not found"}
500Falha interna.{"error":"failed to get bundle","detail":"..."}
O preço do kit não confere estoque nem status dos produtos

final_price vem só dos preços e quantidades cadastrados. Um item cujo produto foi apagado aparece sem nome e sem preço, e entra na conta com valor zero. Um item de produto inativo ou sem estoque continua listado. Antes de oferecer o kit, confira cada produto pela API de produtos e esconda o kit se algum não puder ser vendido.

Preços para visitante

Diferente de produtos, mixes e ofertas, a leitura pública de kits não esconde preços de visitantes quando a loja os oculta. Se a sua loja esconde preço de quem não está logado, não exiba final_price e product_price para visitantes.

Veja também

  • Produtos mestres e ofertas
  • Caixas de produto
  • Kits e conjuntos: visão geral
Anterior
Kits, mestres e caixas
Próxima
Produtos mestres e ofertas
Nesta página
  • Exemplo de requisição
  • Resposta
  • Exemplo de requisição (detalhe)
  • Resposta (detalhe)
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/storefront/bundles?per_page=10"
bash
curl "$BASE_URL/api/v1/storefront/bundles/kit-cozinha"
json
{
  "bundles": [
    {
      "id": "9a84247d-4909-44bf-a519-6fb34d11b236",
      "name": "Kit Cozinha",
      "slug": "kit-cozinha",
      "description": "Cafeteira e jarra térmica.",
      "price_bps": 0,
      "discount_bps": 0,
      "discount_type": "none",
      "price_override": 0,
      "discount_value": 0,
      "status": "A",
      "image_url": "",
      "created_at": "2026-06-30T18:28:45.528638Z",
      "updated_at": "2026-06-30T18:33:00.394333Z",
      "items": [
        {
          "id": "05bc22b9-a006-452b-bf96-93c236a15032",
          "bundle_id": "9a84247d-4909-44bf-a519-6fb34d11b236",
          "product_id": "5fc1c706-99fd-4d97-bf6c-ab2793da1cea",
          "quantity": 2,
          "sort_order": 0,
          "product_name": "Cafeteira Premium Branca",
          "slug": "cafeteira-premium-branca-01426-1426",
          "product_price": 19990,
          "product_image": "/uploads/exemplo/cafeteira.png",
          "product_sku": "SD-001426"
        }
      ],
      "calculated_price": 39980,
      "final_price": 39980
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10,
  "total_pages": 1
}
json
{
  "id": "9a84247d-4909-44bf-a519-6fb34d11b236",
  "name": "Kit Cozinha",
  "slug": "kit-cozinha",
  "description": "Cafeteira e jarra térmica.",
  "price_bps": 0,
  "discount_bps": 1000,
  "discount_type": "percentage",
  "price_override": 0,
  "discount_value": 1000,
  "status": "A",
  "image_url": "/uploads/exemplo/kit.png",
  "created_at": "2026-06-30T18:28:45.528638Z",
  "updated_at": "2026-06-30T18:33:00.394333Z",
  "items": [
    {
      "id": "05bc22b9-a006-452b-bf96-93c236a15032",
      "bundle_id": "9a84247d-4909-44bf-a519-6fb34d11b236",
      "product_id": "5fc1c706-99fd-4d97-bf6c-ab2793da1cea",
      "quantity": 2,
      "sort_order": 0,
      "product_name": "Cafeteira Premium Branca",
      "slug": "cafeteira-premium-branca-01426-1426",
      "product_price": 19990,
      "product_image": "/uploads/exemplo/cafeteira.png",
      "product_sku": "SD-001426"
    }
  ],
  "calculated_price": 39980,
  "final_price": 35982
}