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

bash

curl "$BASE_URL/api/v1/storefront/bundles?per_page=10"

Resposta

200Kits retornados

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
}

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)

bash

curl "$BASE_URL/api/v1/storefront/bundles/kit-cozinha"

Resposta (detalhe)

200Kit com preço fixo e desconto percentual

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
}

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

Status	Quando	Corpo
401	A loja exige login para navegar e a chamada é anônima.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
404	Kit inexistente, inativo ou de seller (detalhe).	`{"error":"bundle not found"}`
500	Falha interna.	`{"error":"failed to get bundle","detail":"..."}`

Veja também

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.

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

bash

curl "$BASE_URL/api/v1/storefront/bundles?per_page=10"

Resposta

200Kits retornados

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
}

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)

bash

curl "$BASE_URL/api/v1/storefront/bundles/kit-cozinha"

Resposta (detalhe)

200Kit com preço fixo e desconto percentual

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
}

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

Status	Quando	Corpo
401	A loja exige login para navegar e a chamada é anônima.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
404	Kit inexistente, inativo ou de seller (detalhe).	`{"error":"bundle not found"}`
500	Falha interna.	`{"error":"failed to get bundle","detail":"..."}`