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

Mixes de produtos

Lista, cria, consulta, altera e exclui os mixes do seller: kits com componentes trocáveis e visibilidade por cliente ou grupo.

Um mix é um kit com regras, vindo do atacado: o seller define os componentes e um preço único, e decide quem pode ver (todos, só clientes escolhidos, ou grupos). Quando o cliente adiciona o mix ao carrinho, ele vira linhas comuns de produto e o preço do mix é rateado entre elas.

Módulo necessário

Estas rotas só funcionam em lojas que ligam o módulo mix-products; sem ele a resposta é 403 module_disabled.

Listar

GET/api/v1/vendor/mix-productsSeller

Listar os mixes

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: 25
Itens por página, 1 a 200.
statusstring
ADH
Filtra por status.
searchstring
Busca no nome.

Exemplo de requisição (listar)

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

Resposta (listar)

200Mixes
json
{
  "mixes": [
    {
      "id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Mix Atacado Verão",
      "description": "",
      "sku": "MIX-001",
      "status": "A",
      "bundle_price_centavos": 19990,
      "currency": "BRL",
      "visibility": "customer-list",
      "min_components": 1,
      "max_components": 5,
      "allow_customer_pick": true,
      "image_url": "",
      "created_at": "2026-10-11T20:00:00Z",
      "updated_at": "2026-10-11T20:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 25,
  "total_pages": 1
}

Campos da resposta

mixesarray

Mixes, sem componentes nem atribuições (use a consulta).

idstring (uuid)
Id do mix.
vendor_idstring (uuid)
Seu seller.
namestring
Nome.
descriptionstring
Descrição.
skustring
SKU do mix.
statusstring
ADH
A ativo, D desativado, H oculto.
bundle_price_centavosinteger
Preço do mix em centavos.
currencystring
Moeda (BRL).
visibilitystring
publicprivatecustomer-list
Quem vê o mix.
min_componentsinteger
Mínimo de componentes que o cliente leva (0 = sem regra).
max_componentsinteger
Máximo de componentes (0 = sem limite).
allow_customer_pickboolean
Se o cliente pode escolher/trocar componentes.
image_urlstring
Imagem.
componentsarray
Componentes (só no detalhe e na gravação): product_id, quantity, sort_order, is_required, allow_swap, swap_group e dados do produto.
assignmentsarray
Para quem o mix vale: customer_id e/ou usergroup_id.
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_catalog"]}
403O módulo mix-products está desligado na loja.{"error":"module_disabled","module":"mix-products"}

Criar

POST/api/v1/vendor/mix-productsSeller

Criar um mix

Cabeçalhos

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

Corpo da requisição

namestringobrigatório
Nome do mix.
componentsarrayobrigatório

Componentes. Ao menos um na criação. Na alteração, se enviado, substitui todos.

product_idstring (uuid)obrigatório
Produto.
quantityintegerpadrão: 1
Unidades (mínimo 1).
sort_orderinteger
Ordem.
is_requiredboolean
Componente obrigatório.
allow_swapboolean
Pode ser trocado por outro do mesmo swap_group.
swap_groupstring
Nome do grupo de trocas.
descriptionstring
Descrição.
skustring
SKU do mix.
statusstringpadrão: D
ADH
Status. Padrão na criação: D, para você revisar antes de publicar.
bundle_price_centavosinteger
Preço do mix em centavos (não negativo).
currencystringpadrão: BRL
Moeda.
visibilitystringpadrão: private
publicprivatecustomer-list
public: todos; customer-list: clientes ou grupos atribuídos; private: só clientes atribuídos diretamente (grupo não conta).
min_componentsinteger
Mínimo de componentes.
max_componentsinteger
Máximo de componentes; não pode ser menor que o mínimo.
allow_customer_pickboolean
Cliente pode trocar componentes.
image_urlstring
Imagem.
assignmentsarray

Para quem o mix vale. Se enviado, substitui a lista. Cada item precisa de customer_id ou usergroup_id.

customer_idstring (uuid)
Cliente.
usergroup_idstring (uuid)
Grupo de clientes.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/mix-products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Mix Atacado Verão",
  "sku": "MIX-001",
  "status": "A",
  "bundle_price_centavos": 19990,
  "visibility": "customer-list",
  "allow_customer_pick": true,
  "max_components": 5,
  "components": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 2,
      "is_required": true
    }
  ],
  "assignments": [
    {
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10"
    }
  ]
}'

Resposta (criar)

201Mix criado
json
{
  "id": "c4a76056-c671-4631-bbcb-65223ff3322b",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Mix Atacado Verão",
  "description": "",
  "sku": "MIX-001",
  "status": "A",
  "bundle_price_centavos": 19990,
  "currency": "BRL",
  "visibility": "customer-list",
  "min_components": 1,
  "max_components": 5,
  "allow_customer_pick": true,
  "image_url": "",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "components": [
    {
      "id": "d1d2d3d4-0001-4a1b-8c2d-111122223333",
      "mix_id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 2,
      "sort_order": 0,
      "is_required": true,
      "allow_swap": false,
      "product_name": "Camiseta Básica Algodão Preta",
      "product_sku": "CAM-001",
      "product_price_centavos": 4990
    }
  ],
  "assignments": [
    {
      "id": "e1e2e3e4-0001-4a1b-8c2d-111122223333",
      "mix_id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "created_at": "2026-10-11T20:00:00Z",
      "customer_email": "maria.souza@example.com"
    }
  ],
  "component_subtotal_centavos": 9980,
  "savings_centavos": 0
}

Campos da resposta

idstring (uuid)
Id do mix.
vendor_idstring (uuid)
Seu seller.
namestring
Nome.
descriptionstring
Descrição.
skustring
SKU do mix.
statusstring
ADH
A ativo, D desativado, H oculto.
bundle_price_centavosinteger
Preço do mix em centavos.
currencystring
Moeda (BRL).
visibilitystring
publicprivatecustomer-list
Quem vê o mix.
min_componentsinteger
Mínimo de componentes que o cliente leva (0 = sem regra).
max_componentsinteger
Máximo de componentes (0 = sem limite).
allow_customer_pickboolean
Se o cliente pode escolher/trocar componentes.
image_urlstring
Imagem.
componentsarray
Componentes (só no detalhe e na gravação): product_id, quantity, sort_order, is_required, allow_swap, swap_group e dados do produto.
assignmentsarray
Para quem o mix vale: customer_id e/ou usergroup_id.
component_subtotal_centavosinteger
Soma dos componentes (preço × quantidade).
savings_centavosinteger
Economia contra a soma, nunca negativa.
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_catalog"]}
400Nome vazio, sem componentes, preço negativo, status/visibilidade inválidos, mínimo maior que máximo, componente sem produto, atribuição sem cliente nem grupo.{"error":"invalid_input","message":"mix-products: invalid input: at least one component is required"}
403O módulo mix-products está desligado na loja.{"error":"module_disabled","module":"mix-products"}

Consultar

GET/api/v1/vendor/mix-products/{id}Seller

Consultar um mix

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 mix.

Exemplo de requisição (consultar)

bash
curl "$BASE_URL/api/v1/vendor/mix-products/$MIX_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Mix
json
{
  "id": "c4a76056-c671-4631-bbcb-65223ff3322b",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Mix Atacado Verão",
  "description": "",
  "sku": "MIX-001",
  "status": "A",
  "bundle_price_centavos": 19990,
  "currency": "BRL",
  "visibility": "customer-list",
  "min_components": 1,
  "max_components": 5,
  "allow_customer_pick": true,
  "image_url": "",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "components": [
    {
      "id": "d1d2d3d4-0001-4a1b-8c2d-111122223333",
      "mix_id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 2,
      "sort_order": 0,
      "is_required": true,
      "allow_swap": false,
      "product_name": "Camiseta Básica Algodão Preta",
      "product_sku": "CAM-001",
      "product_price_centavos": 4990
    }
  ],
  "assignments": [
    {
      "id": "e1e2e3e4-0001-4a1b-8c2d-111122223333",
      "mix_id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "created_at": "2026-10-11T20:00:00Z",
      "customer_email": "maria.souza@example.com"
    }
  ],
  "component_subtotal_centavos": 9980,
  "savings_centavos": 0
}

Campos da resposta

idstring (uuid)
Id do mix.
vendor_idstring (uuid)
Seu seller.
namestring
Nome.
descriptionstring
Descrição.
skustring
SKU do mix.
statusstring
ADH
A ativo, D desativado, H oculto.
bundle_price_centavosinteger
Preço do mix em centavos.
currencystring
Moeda (BRL).
visibilitystring
publicprivatecustomer-list
Quem vê o mix.
min_componentsinteger
Mínimo de componentes que o cliente leva (0 = sem regra).
max_componentsinteger
Máximo de componentes (0 = sem limite).
allow_customer_pickboolean
Se o cliente pode escolher/trocar componentes.
image_urlstring
Imagem.
componentsarray
Componentes (só no detalhe e na gravação): product_id, quantity, sort_order, is_required, allow_swap, swap_group e dados do produto.
assignmentsarray
Para quem o mix vale: customer_id e/ou usergroup_id.
component_subtotal_centavosinteger
Soma dos componentes (preço × quantidade).
savings_centavosinteger
Economia contra a soma, nunca negativa.
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_catalog"]}
404O mix não existe ou não é seu.{"error":"not_found","message":"mix not found"}
403O módulo mix-products está desligado na loja.{"error":"module_disabled","module":"mix-products"}

Alterar

PUT/api/v1/vendor/mix-products/{id}Seller

Alterar um mix

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 mix.

Corpo da requisição

namestring
Novo nome.
componentsarray
Se enviado, substitui todos os componentes.
descriptionstring
Descrição.
skustring
SKU do mix.
statusstringpadrão: D
ADH
Status. Padrão na criação: D, para você revisar antes de publicar.
bundle_price_centavosinteger
Preço do mix em centavos (não negativo).
currencystringpadrão: BRL
Moeda.
visibilitystringpadrão: private
publicprivatecustomer-list
public: todos; customer-list: clientes ou grupos atribuídos; private: só clientes atribuídos diretamente (grupo não conta).
min_componentsinteger
Mínimo de componentes.
max_componentsinteger
Máximo de componentes; não pode ser menor que o mínimo.
allow_customer_pickboolean
Cliente pode trocar componentes.
image_urlstring
Imagem.
assignmentsarray

Para quem o mix vale. Se enviado, substitui a lista. Cada item precisa de customer_id ou usergroup_id.

customer_idstring (uuid)
Cliente.
usergroup_idstring (uuid)
Grupo de clientes.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/mix-products/$MIX_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "bundle_price_centavos": 18990,
  "status": "A"
}'

Resposta (alterar)

200Mix alterado
json
{
  "id": "c4a76056-c671-4631-bbcb-65223ff3322b",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Mix Atacado Verão",
  "description": "",
  "sku": "MIX-001",
  "status": "A",
  "bundle_price_centavos": 18990,
  "currency": "BRL",
  "visibility": "customer-list",
  "min_components": 1,
  "max_components": 5,
  "allow_customer_pick": true,
  "image_url": "",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "components": [
    {
      "id": "d1d2d3d4-0001-4a1b-8c2d-111122223333",
      "mix_id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "quantity": 2,
      "sort_order": 0,
      "is_required": true,
      "allow_swap": false,
      "product_name": "Camiseta Básica Algodão Preta",
      "product_sku": "CAM-001",
      "product_price_centavos": 4990
    }
  ],
  "assignments": [
    {
      "id": "e1e2e3e4-0001-4a1b-8c2d-111122223333",
      "mix_id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "created_at": "2026-10-11T20:00:00Z",
      "customer_email": "maria.souza@example.com"
    }
  ],
  "component_subtotal_centavos": 9980,
  "savings_centavos": 0
}

Campos da resposta

idstring (uuid)
Id do mix.
vendor_idstring (uuid)
Seu seller.
namestring
Nome.
descriptionstring
Descrição.
skustring
SKU do mix.
statusstring
ADH
A ativo, D desativado, H oculto.
bundle_price_centavosinteger
Preço do mix em centavos.
currencystring
Moeda (BRL).
visibilitystring
publicprivatecustomer-list
Quem vê o mix.
min_componentsinteger
Mínimo de componentes que o cliente leva (0 = sem regra).
max_componentsinteger
Máximo de componentes (0 = sem limite).
allow_customer_pickboolean
Se o cliente pode escolher/trocar componentes.
image_urlstring
Imagem.
componentsarray
Componentes (só no detalhe e na gravação): product_id, quantity, sort_order, is_required, allow_swap, swap_group e dados do produto.
assignmentsarray
Para quem o mix vale: customer_id e/ou usergroup_id.
component_subtotal_centavosinteger
Soma dos componentes (preço × quantidade).
savings_centavosinteger
Economia contra a soma, nunca negativa.
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_catalog"]}
404O mix não existe ou não é seu.{"error":"not_found","message":"mix not found"}
403O módulo mix-products está desligado na loja.{"error":"module_disabled","module":"mix-products"}
400Campo inválido (status, visibilidade, preço, limites).{"error":"invalid_input","message":"..."}

Excluir

DELETE/api/v1/vendor/mix-products/{id}Seller

Excluir um mix

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 mix.

Exemplo de requisição (excluir)

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/mix-products/$MIX_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (excluir)

204Mix excluído (sem corpo)
text
(sem corpo / empty body)

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_catalog"]}
404O mix não existe ou não é seu.{"error":"not_found","message":"mix not found"}
403O módulo mix-products está desligado na loja.{"error":"module_disabled","module":"mix-products"}
Componentes: use produtos seus

A plataforma não confere de quem é cada product_id dos componentes. Monte o mix apenas com produtos do seu seller, para não vender o produto de outro.

Visibilidade `private`

private é o padrão e só vale para os clientes atribuídos diretamente; atribuir um grupo não libera o mix. Para liberar por grupo, use customer-list.

Veja também

  • Vitrine e ofertas: visão geral
Anterior
Kits
Próxima
Caixas de produto
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