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

Kits

Lista, cria, consulta, altera e exclui os kits do seller: vários produtos seus vendidos juntos, com preço fixo ou desconto.

O kit mostra ao cliente um conjunto de produtos com um preço único. O preço pode ser fixo (price_bps) ou calculado: a soma dos itens menos um desconto percentual (discount_bps) ou em valor (discount_type: "fixed"). Kits do seller só aparecem na página do próprio seller, não na vitrine geral do marketplace.

Listar

GET/api/v1/vendor/bundlesSeller

Listar os kits

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página, 1 a 100.
statusstring
Filtra por status (A, D).
searchstring
Busca no nome.

Exemplo de requisição (listar)

bash
curl "$BASE_URL/api/v1/vendor/bundles?per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Kits
json
{
  "bundles": [
    {
      "id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
      "name": "Kit Camiseta + Boné",
      "slug": "kit-camiseta-bone",
      "description": "Leve os dois e economize",
      "price_bps": 0,
      "discount_bps": 1000,
      "discount_type": "percentage",
      "price_override": 0,
      "discount_value": 1000,
      "status": "A",
      "image_url": "",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "created_at": "2026-10-11T20:00:00Z",
      "updated_at": "2026-10-11T20:00:00Z",
      "items": [
        {
          "id": "63903d90-fb9c-4c17-997b-f92f4c239e41",
          "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
          "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
          "quantity": 1,
          "sort_order": 0,
          "product_name": "Camiseta Básica Algodão Preta",
          "slug": "camiseta-basica-algodao-preta",
          "product_price": 4990,
          "product_image": "/uploads/dfe2555e/camiseta.png",
          "product_sku": "CAM-001"
        },
        {
          "id": "ed10be82-1ba0-4c25-b9be-31be4391927b",
          "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
          "product_id": "0d6c7b0e-3f55-4d2c-9f0e-1d3b6d1f6a10",
          "quantity": 1,
          "sort_order": 1,
          "product_name": "Boné Liso",
          "slug": "bone-liso",
          "product_price": 3990,
          "product_image": "",
          "product_sku": "BON-001"
        }
      ],
      "calculated_price": 8980,
      "final_price": 8082
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

bundlesarray

Kits, no formato abaixo.

idstring (uuid)
Id do kit.
namestring
Nome.
slugstring
Slug único.
descriptionstring
Descrição.
price_bpsinteger
Preço final fixo do kit, em centavos (0 = calcular a partir dos itens). Apesar do nome, não é pontos-base.
discount_bpsinteger
Desconto: pontos-base (1000 = 10%) se discount_type é percentage; centavos se fixed.
discount_typestring
nonepercentagefixed
Tipo do desconto.
price_overrideinteger
Espelho de price_bps.
discount_valueinteger
Espelho de discount_bps.
statusstring
A ativo, D desativado.
image_urlstring
Imagem do kit.
vendor_idstring (uuid)
Seu seller.
itemsarray
Itens (só na consulta e na criação/alteração): product_id, quantity, sort_order, e dados do produto.
calculated_priceinteger
Soma dos itens (preço × quantidade) em centavos.
final_priceinteger
Preço que o cliente paga: o override, ou a soma menos o desconto. Nunca negativo.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).
totalinteger
Total.
pageinteger
Página.
per_pageinteger
Itens por página.
total_pagesinteger
Total de páginas.

Erros (listar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}

Criar

POST/api/v1/vendor/bundlesSeller

Criar um kit

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

namestringobrigatório
Nome do kit.
slugstring
Slug; vazio = derivado do nome.
descriptionstring
Descrição.
statusstringobrigatório
AD
A ativo ou D desativado. Envie sempre: o padrão da API quebra a criação.
price_bpsinteger
Preço final fixo em centavos. Se maior que zero, ignora o desconto.
discount_bpsinteger
Desconto percentual em pontos-base (1000 = 10%).
discount_typestring
nonepercentagefixed
Opcional. Com discount_value, permite desconto fixed (centavos).
discount_valueinteger
Valor do desconto conforme discount_type.
price_overrideinteger
Sinônimo de price_bps.
image_urlstring
Imagem do kit.
itemsarray

Produtos do kit. Cada um precisa ser seu.

product_idstring (uuid)obrigatório
Produto.
quantityintegerpadrão: 1
Unidades no kit. Mínimo 1.
sort_orderinteger
Ordem.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/bundles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Kit Camiseta + Boné",
  "status": "A",
  "discount_bps": 1000,
  "items": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 1
    },
    {
      "product_id": "0d6c7b0e-3f55-4d2c-9f0e-1d3b6d1f6a10",
      "quantity": 1
    }
  ]
}'

Resposta (criar)

201Kit criado
json
{
  "id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
  "name": "Kit Camiseta + Boné",
  "slug": "kit-camiseta-bone",
  "description": "Leve os dois e economize",
  "price_bps": 0,
  "discount_bps": 1000,
  "discount_type": "percentage",
  "price_override": 0,
  "discount_value": 1000,
  "status": "A",
  "image_url": "",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "items": [
    {
      "id": "63903d90-fb9c-4c17-997b-f92f4c239e41",
      "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 1,
      "sort_order": 0,
      "product_name": "Camiseta Básica Algodão Preta",
      "slug": "camiseta-basica-algodao-preta",
      "product_price": 4990,
      "product_image": "/uploads/dfe2555e/camiseta.png",
      "product_sku": "CAM-001"
    },
    {
      "id": "ed10be82-1ba0-4c25-b9be-31be4391927b",
      "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
      "product_id": "0d6c7b0e-3f55-4d2c-9f0e-1d3b6d1f6a10",
      "quantity": 1,
      "sort_order": 1,
      "product_name": "Boné Liso",
      "slug": "bone-liso",
      "product_price": 3990,
      "product_image": "",
      "product_sku": "BON-001"
    }
  ],
  "calculated_price": 8980,
  "final_price": 8082
}

Campos da resposta

idstring (uuid)
Id do kit.
namestring
Nome.
slugstring
Slug único.
descriptionstring
Descrição.
price_bpsinteger
Preço final fixo do kit, em centavos (0 = calcular a partir dos itens). Apesar do nome, não é pontos-base.
discount_bpsinteger
Desconto: pontos-base (1000 = 10%) se discount_type é percentage; centavos se fixed.
discount_typestring
nonepercentagefixed
Tipo do desconto.
price_overrideinteger
Espelho de price_bps.
discount_valueinteger
Espelho de discount_bps.
statusstring
A ativo, D desativado.
image_urlstring
Imagem do kit.
vendor_idstring (uuid)
Seu seller.
itemsarray
Itens (só na consulta e na criação/alteração): product_id, quantity, sort_order, e dados do produto.
calculated_priceinteger
Soma dos itens (preço × quantidade) em centavos.
final_priceinteger
Preço que o cliente paga: o override, ou a soma menos o desconto. Nunca negativo.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (criar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
400name ausente.{"error":"name is required"}
400Algum item aponta para produto que não é seu ou não existe.{"error":"product 0d6c... does not belong to this vendor"}
400status omitido: o padrão não cabe na coluna e a criação falha.{"error":"..."}

Consultar

GET/api/v1/vendor/bundles/{id}Seller

Consultar um kit

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do kit.

Exemplo de requisição (consultar)

bash
curl "$BASE_URL/api/v1/vendor/bundles/$BUNDLE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Kit
json
{
  "id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
  "name": "Kit Camiseta + Boné",
  "slug": "kit-camiseta-bone",
  "description": "Leve os dois e economize",
  "price_bps": 0,
  "discount_bps": 1000,
  "discount_type": "percentage",
  "price_override": 0,
  "discount_value": 1000,
  "status": "A",
  "image_url": "",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "items": [
    {
      "id": "63903d90-fb9c-4c17-997b-f92f4c239e41",
      "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 1,
      "sort_order": 0,
      "product_name": "Camiseta Básica Algodão Preta",
      "slug": "camiseta-basica-algodao-preta",
      "product_price": 4990,
      "product_image": "/uploads/dfe2555e/camiseta.png",
      "product_sku": "CAM-001"
    },
    {
      "id": "ed10be82-1ba0-4c25-b9be-31be4391927b",
      "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
      "product_id": "0d6c7b0e-3f55-4d2c-9f0e-1d3b6d1f6a10",
      "quantity": 1,
      "sort_order": 1,
      "product_name": "Boné Liso",
      "slug": "bone-liso",
      "product_price": 3990,
      "product_image": "",
      "product_sku": "BON-001"
    }
  ],
  "calculated_price": 8980,
  "final_price": 8082
}

Campos da resposta

idstring (uuid)
Id do kit.
namestring
Nome.
slugstring
Slug único.
descriptionstring
Descrição.
price_bpsinteger
Preço final fixo do kit, em centavos (0 = calcular a partir dos itens). Apesar do nome, não é pontos-base.
discount_bpsinteger
Desconto: pontos-base (1000 = 10%) se discount_type é percentage; centavos se fixed.
discount_typestring
nonepercentagefixed
Tipo do desconto.
price_overrideinteger
Espelho de price_bps.
discount_valueinteger
Espelho de discount_bps.
statusstring
A ativo, D desativado.
image_urlstring
Imagem do kit.
vendor_idstring (uuid)
Seu seller.
itemsarray
Itens (só na consulta e na criação/alteração): product_id, quantity, sort_order, e dados do produto.
calculated_priceinteger
Soma dos itens (preço × quantidade) em centavos.
final_priceinteger
Preço que o cliente paga: o override, ou a soma menos o desconto. Nunca negativo.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (consultar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404O kit não existe ou não é seu.{"error":"bundle not found"}

Alterar

Altera só o que for enviado. Se enviar items, a lista substitui os itens atuais.

PUT/api/v1/vendor/bundles/{id}Seller

Alterar um kit

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do kit.

Corpo da requisição

slugstring
Slug; vazio = derivado do nome.
descriptionstring
Descrição.
price_bpsinteger
Preço final fixo em centavos. Se maior que zero, ignora o desconto.
discount_bpsinteger
Desconto percentual em pontos-base (1000 = 10%).
discount_typestring
nonepercentagefixed
Opcional. Com discount_value, permite desconto fixed (centavos).
discount_valueinteger
Valor do desconto conforme discount_type.
price_overrideinteger
Sinônimo de price_bps.
image_urlstring
Imagem do kit.
itemsarray

Produtos do kit. Cada um precisa ser seu.

product_idstring (uuid)obrigatório
Produto.
quantityintegerpadrão: 1
Unidades no kit. Mínimo 1.
sort_orderinteger
Ordem.
namestring
Novo nome.
statusstring
AD
Novo status.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/bundles/$BUNDLE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "discount_bps": 1500,
  "status": "A"
}'

Resposta (alterar)

200Kit alterado
json
{
  "id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
  "name": "Kit Camiseta + Boné",
  "slug": "kit-camiseta-bone",
  "description": "Leve os dois e economize",
  "price_bps": 0,
  "discount_bps": 1500,
  "discount_type": "percentage",
  "price_override": 0,
  "discount_value": 1500,
  "status": "A",
  "image_url": "",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "items": [
    {
      "id": "63903d90-fb9c-4c17-997b-f92f4c239e41",
      "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 1,
      "sort_order": 0,
      "product_name": "Camiseta Básica Algodão Preta",
      "slug": "camiseta-basica-algodao-preta",
      "product_price": 4990,
      "product_image": "/uploads/dfe2555e/camiseta.png",
      "product_sku": "CAM-001"
    },
    {
      "id": "ed10be82-1ba0-4c25-b9be-31be4391927b",
      "bundle_id": "abd73557-8dfa-4c74-bf4b-f2dafffe3e6b",
      "product_id": "0d6c7b0e-3f55-4d2c-9f0e-1d3b6d1f6a10",
      "quantity": 1,
      "sort_order": 1,
      "product_name": "Boné Liso",
      "slug": "bone-liso",
      "product_price": 3990,
      "product_image": "",
      "product_sku": "BON-001"
    }
  ],
  "calculated_price": 8980,
  "final_price": 8082
}

Campos da resposta

idstring (uuid)
Id do kit.
namestring
Nome.
slugstring
Slug único.
descriptionstring
Descrição.
price_bpsinteger
Preço final fixo do kit, em centavos (0 = calcular a partir dos itens). Apesar do nome, não é pontos-base.
discount_bpsinteger
Desconto: pontos-base (1000 = 10%) se discount_type é percentage; centavos se fixed.
discount_typestring
nonepercentagefixed
Tipo do desconto.
price_overrideinteger
Espelho de price_bps.
discount_valueinteger
Espelho de discount_bps.
statusstring
A ativo, D desativado.
image_urlstring
Imagem do kit.
vendor_idstring (uuid)
Seu seller.
itemsarray
Itens (só na consulta e na criação/alteração): product_id, quantity, sort_order, e dados do produto.
calculated_priceinteger
Soma dos itens (preço × quantidade) em centavos.
final_priceinteger
Preço que o cliente paga: o override, ou a soma menos o desconto. Nunca negativo.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (alterar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404O kit não existe ou não é seu.{"error":"bundle not found"}
400Algum item aponta para produto que não é seu ou não existe.{"error":"product 0d6c... does not belong to this vendor"}

Excluir

DELETE/api/v1/vendor/bundles/{id}Seller

Excluir um kit

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do kit.

Exemplo de requisição (excluir)

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/bundles/$BUNDLE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (excluir)

200Kit excluído
json
{
  "message": "bundle deleted"
}

Campos da resposta

messagestring
Confirmação fixa.

Erros (excluir)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404O kit não existe ou não é seu.{"error":"bundle not found"}
Sempre envie `status` ao criar

Hoje, criar um kit sem status falha: o valor padrão interno ("draft") é maior que a coluna de status, que guarda uma letra. Mande A ou D explicitamente.

Ordem de prioridade do preço
  1. price_bps maior que zero vale como preço final. 2) Senão, discount_type: "fixed" subtrai centavos. 3) Senão, o desconto percentual em pontos-base é aplicado à soma. O resultado nunca é negativo.

Veja também

  • Vitrine e ofertas: visão geral
Anterior
Selos nos produtos
Próxima
Mixes de produtos
Nesta página
  • Listar
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Consultar
  • Exemplo de requisição (consultar)
  • Resposta (consultar)
  • Erros (consultar)
  • Alterar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Excluir
  • Exemplo de requisição (excluir)
  • Resposta (excluir)
  • Erros (excluir)
  • Veja também