API atual/Referência completa/Kits e Compre junto

Gerenciar kits

Lista, cria, consulta, altera e apaga kits de produtos, com preço fechado ou desconto e a lista de itens.

Um kit junta produtos já cadastrados em um único item de venda. O cliente coloca o kit no carrinho e a plataforma aplica o preço do kit. Estas cinco rotas são o CRUD completo. Exigem o módulo product-bundles ligado e o privilégio manage_bundles ou manage_catalog. O cálculo do preço está na home da seção.

GET/api/v1/admin/bundlesAdmin

Lista os kits

Do mais novo para o mais antigo, com os itens de cada kit. A lista inclui os kits gerados pelo Compre junto (slug fbt-...).

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

statusstring

ADH

Status. Aceita a letra ou a palavra (active, disabled, hidden).

searchstring

Texto no nome ou na descrição do kit. Não procura no slug.

POST/api/v1/admin/bundlesAdmin

Cria um kit

Responde 201 com o kit. O slug é gerado a partir do nome (com sufixo se já existir) quando você não manda.

Corpo da requisição (JSON)

namestringobrigatório

Nome do kit.

statusstringobrigatório

ADHactivedisabledhidden

Status. Sempre envie. Omitido ou draft, a criação falha com 500.

slugstring

Trecho da URL. Gerado do nome se omitido; deve ser único.

descriptionstring

Descrição.

image_urlstring

Imagem do kit.

price_overrideinteger

Preço fechado do kit, em centavos. Quando maior que zero, vence qualquer desconto. (Alias: price_bps.)

discount_typestringpadrão: none

nonepercentagefixed

Tipo do desconto.

discount_valueinteger

Valor do desconto: em pontos-base quando percentage (1000 é 10%) ou em centavos quando fixed. (Alias: discount_bps, sempre percentual.)

vendor_iduuid

Seller dono do kit. Todos os itens precisam ser desse seller. Omitido, o kit é da loja.

itemsarray

Produtos do kit.

product_iduuidobrigatório

Id do produto.

quantityintegerpadrão: 1

Unidades do produto no kit. Menor que 1 vira 1.

sort_orderintegerpadrão: 0

Ordem de exibição.

GET/api/v1/admin/bundles/{id}Admin

Consulta um kit

Devolve o kit com os itens e os preços calculados.

Parâmetros de caminho

iduuidobrigatório

Id do kit.

PUT/api/v1/admin/bundles/{id}Admin

Altera um kit

Altera só os campos enviados. Quando items é enviado, a lista de itens é substituída por inteira; sem items, os itens não mudam.

Parâmetros de caminho

iduuidobrigatório

Id do kit.

Aceita os campos da criação, todos opcionais. Para tirar o preço fechado, envie price_override: 0.

DELETE/api/v1/admin/bundles/{id}Admin

Apaga um kit

Apaga o kit e os itens de forma definitiva.

Parâmetros de caminho

iduuidobrigatório

Id do kit.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/bundles" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Kit Escritório",
    "status": "active",
    "discount_type": "percentage",
    "discount_value": 1000,
    "items": [
      {"product_id": "12658adf-5a62-43c3-8310-73176df91202", "quantity": 1},
      {"product_id": "d3602023-101d-4f7d-8ef5-52abd5c7eaaf", "quantity": 2}
    ]
  }'

Resposta

201Kit criado

json

{
  "id": "66e84327-ef14-49dd-bd53-46c11958cd7b",
  "name": "Kit Escritório",
  "slug": "kit-escritorio",
  "description": "",
  "price_bps": 0,
  "discount_bps": 1000,
  "discount_type": "percentage",
  "price_override": 0,
  "discount_value": 1000,
  "status": "A",
  "image_url": "",
  "created_at": "2026-10-11T21:09:36.630755Z",
  "updated_at": "2026-10-11T21:09:36.630755Z",
  "items": [
    {
      "id": "9f078adc-78b5-48f4-ab65-a542a6aa8cbc",
      "bundle_id": "66e84327-ef14-49dd-bd53-46c11958cd7b",
      "product_id": "12658adf-5a62-43c3-8310-73176df91202",
      "quantity": 1,
      "sort_order": 0,
      "product_name": "Óculos Deluxe Preto 02710",
      "slug": "oculos-deluxe-preto-02710-2710",
      "product_price": 14990,
      "product_image": "/uploads/exemplo/product/oculos.png",
      "product_sku": "SD-002710"
    },
    {
      "id": "f61d7b2e-ff7a-4749-b3fe-9dc2dbd04274",
      "bundle_id": "66e84327-ef14-49dd-bd53-46c11958cd7b",
      "product_id": "d3602023-101d-4f7d-8ef5-52abd5c7eaaf",
      "quantity": 2,
      "sort_order": 0,
      "product_name": "Notebook Essencial Bege 02156",
      "slug": "notebook-essencial-bege-02156-2156",
      "product_price": 18990,
      "product_image": "/uploads/exemplo/product/notebook.png",
      "product_sku": "SD-002156"
    }
  ],
  "calculated_price": 52970,
  "final_price": 47673
}

200Lista

json

{
  "bundles": [ { "id": "66e84327-ef14-49dd-bd53-46c11958cd7b", "name": "Kit Escritório", "status": "A", "calculated_price": 52970, "final_price": 47673, "items": [] } ],
  "total": 111,
  "page": 1,
  "per_page": 20,
  "total_pages": 6
}

200Kit apagado

json

{ "message": "bundle deleted" }

Campos do kit

iduuid

Id do kit.

namestring

Nome.

slugstring

Trecho da URL. Único.

descriptionstring

Descrição.

statusstring

ADH

Status.

image_urlstring

Imagem.

price_overrideinteger

Preço fechado em centavos. 0 sem preço fechado. Repete price_bps.

discount_typestring

nonepercentagefixed

Tipo do desconto.

discount_valueinteger

Valor do desconto (pontos-base em percentage, centavos em fixed). Repete discount_bps.

vendor_iduuid

Seller dono. Ausente nos kits da loja.

itemsarray

Itens: id, bundle_id, product_id, quantity, sort_order, e do produto product_name, slug, product_price (centavos, unitário), product_image, product_sku.

calculated_priceinteger

Soma de product_price × quantity, em centavos. Ausente (zero) quando não há itens.

final_priceinteger

Preço do kit depois do preço fechado ou do desconto, em centavos.

price_redactedboolean

true quando os preços foram ocultados (visitante em loja que esconde preços). Não ocorre em chamadas de administrador autenticado.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `name`	`{"error":"name is required"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta o privilégio	`{"error":"module_disabled","module":"product-bundles"}`
404	`GET` de um kit que não existe	`{"error":"bundle not found"}`
500	`status` ausente ou `draft`, produto inexistente, ou slug repetido	`{"error":"failed to create bundle","detail":"..."}`
500	`PUT` ou `DELETE` de um kit que não existe	`{"error":"failed to delete bundle","detail":"bundle not found"}`

Veja também

Gerenciar kits

Lista, cria, consulta, altera e apaga kits de produtos, com preço fechado ou desconto e a lista de itens.

GET/api/v1/admin/bundlesAdmin

Lista os kits

Do mais novo para o mais antigo, com os itens de cada kit. A lista inclui os kits gerados pelo Compre junto (slug fbt-...).

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

statusstring

ADH

Status. Aceita a letra ou a palavra (active, disabled, hidden).

searchstring

Texto no nome ou na descrição do kit. Não procura no slug.

POST/api/v1/admin/bundlesAdmin

Cria um kit

Responde 201 com o kit. O slug é gerado a partir do nome (com sufixo se já existir) quando você não manda.

Corpo da requisição (JSON)

namestringobrigatório

Nome do kit.

statusstringobrigatório

ADHactivedisabledhidden

Status. Sempre envie. Omitido ou draft, a criação falha com 500.

slugstring

Trecho da URL. Gerado do nome se omitido; deve ser único.

descriptionstring

Descrição.

image_urlstring

Imagem do kit.

price_overrideinteger

Preço fechado do kit, em centavos. Quando maior que zero, vence qualquer desconto. (Alias: price_bps.)

discount_typestringpadrão: none

nonepercentagefixed

Tipo do desconto.

discount_valueinteger

Valor do desconto: em pontos-base quando percentage (1000 é 10%) ou em centavos quando fixed. (Alias: discount_bps, sempre percentual.)

vendor_iduuid

Seller dono do kit. Todos os itens precisam ser desse seller. Omitido, o kit é da loja.

itemsarray

Produtos do kit.

product_iduuidobrigatório

Id do produto.

quantityintegerpadrão: 1

Unidades do produto no kit. Menor que 1 vira 1.

sort_orderintegerpadrão: 0

Ordem de exibição.

GET/api/v1/admin/bundles/{id}Admin

Consulta um kit

Devolve o kit com os itens e os preços calculados.

Parâmetros de caminho

iduuidobrigatório

Id do kit.

PUT/api/v1/admin/bundles/{id}Admin

Altera um kit

Altera só os campos enviados. Quando items é enviado, a lista de itens é substituída por inteira; sem items, os itens não mudam.

Parâmetros de caminho

iduuidobrigatório

Id do kit.

Aceita os campos da criação, todos opcionais. Para tirar o preço fechado, envie price_override: 0.

DELETE/api/v1/admin/bundles/{id}Admin

Apaga um kit

Apaga o kit e os itens de forma definitiva.

Parâmetros de caminho

iduuidobrigatório

Id do kit.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/bundles" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Kit Escritório",
    "status": "active",
    "discount_type": "percentage",
    "discount_value": 1000,
    "items": [
      {"product_id": "12658adf-5a62-43c3-8310-73176df91202", "quantity": 1},
      {"product_id": "d3602023-101d-4f7d-8ef5-52abd5c7eaaf", "quantity": 2}
    ]
  }'

Resposta

201Kit criado

json

{
  "id": "66e84327-ef14-49dd-bd53-46c11958cd7b",
  "name": "Kit Escritório",
  "slug": "kit-escritorio",
  "description": "",
  "price_bps": 0,
  "discount_bps": 1000,
  "discount_type": "percentage",
  "price_override": 0,
  "discount_value": 1000,
  "status": "A",
  "image_url": "",
  "created_at": "2026-10-11T21:09:36.630755Z",
  "updated_at": "2026-10-11T21:09:36.630755Z",
  "items": [
    {
      "id": "9f078adc-78b5-48f4-ab65-a542a6aa8cbc",
      "bundle_id": "66e84327-ef14-49dd-bd53-46c11958cd7b",
      "product_id": "12658adf-5a62-43c3-8310-73176df91202",
      "quantity": 1,
      "sort_order": 0,
      "product_name": "Óculos Deluxe Preto 02710",
      "slug": "oculos-deluxe-preto-02710-2710",
      "product_price": 14990,
      "product_image": "/uploads/exemplo/product/oculos.png",
      "product_sku": "SD-002710"
    },
    {
      "id": "f61d7b2e-ff7a-4749-b3fe-9dc2dbd04274",
      "bundle_id": "66e84327-ef14-49dd-bd53-46c11958cd7b",
      "product_id": "d3602023-101d-4f7d-8ef5-52abd5c7eaaf",
      "quantity": 2,
      "sort_order": 0,
      "product_name": "Notebook Essencial Bege 02156",
      "slug": "notebook-essencial-bege-02156-2156",
      "product_price": 18990,
      "product_image": "/uploads/exemplo/product/notebook.png",
      "product_sku": "SD-002156"
    }
  ],
  "calculated_price": 52970,
  "final_price": 47673
}

200Lista

json

{
  "bundles": [ { "id": "66e84327-ef14-49dd-bd53-46c11958cd7b", "name": "Kit Escritório", "status": "A", "calculated_price": 52970, "final_price": 47673, "items": [] } ],
  "total": 111,
  "page": 1,
  "per_page": 20,
  "total_pages": 6
}

200Kit apagado

json

{ "message": "bundle deleted" }

Campos do kit

iduuid

Id do kit.

namestring

Nome.

slugstring

Trecho da URL. Único.

descriptionstring

Descrição.

statusstring

ADH

Status.

image_urlstring

Imagem.

price_overrideinteger

Preço fechado em centavos. 0 sem preço fechado. Repete price_bps.

discount_typestring

nonepercentagefixed

Tipo do desconto.

discount_valueinteger

Valor do desconto (pontos-base em percentage, centavos em fixed). Repete discount_bps.

vendor_iduuid

Seller dono. Ausente nos kits da loja.

itemsarray

Itens: id, bundle_id, product_id, quantity, sort_order, e do produto product_name, slug, product_price (centavos, unitário), product_image, product_sku.

calculated_priceinteger

Soma de product_price × quantity, em centavos. Ausente (zero) quando não há itens.

final_priceinteger

Preço do kit depois do preço fechado ou do desconto, em centavos.

price_redactedboolean

true quando os preços foram ocultados (visitante em loja que esconde preços). Não ocorre em chamadas de administrador autenticado.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `name`	`{"error":"name is required"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta o privilégio	`{"error":"module_disabled","module":"product-bundles"}`
404	`GET` de um kit que não existe	`{"error":"bundle not found"}`
500	`status` ausente ou `draft`, produto inexistente, ou slug repetido	`{"error":"failed to create bundle","detail":"..."}`
500	`PUT` ou `DELETE` de um kit que não existe	`{"error":"failed to delete bundle","detail":"bundle not found"}`