VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Catálogo: kits, mix e compartilhamento

Mix de produtos

Cria, lista, lê, altera e apaga mixes, pacotes de produtos com preço fechado que o cliente pode montar escolhendo entre componentes.

Um mix de produtos é um pacote com preço fechado (bundle_price_centavos) formado por vários produtos, os componentes. Quando o cliente o adiciona ao carrinho, a plataforma o separa em linhas normais, uma por componente, e reparte o preço do pacote entre elas proporcionalmente. O frete e os impostos continuam funcionando como em qualquer carrinho.

Um mix pode ser fixo (leva tudo) ou montável: com allow_customer_pick ligado, o cliente escolhe entre min_components e max_components e pode trocar um componente por outro do mesmo swap_group. Quem enxerga o mix na vitrine depende da visibility e das atribuições a clientes e grupos.

Todas as rotas exigem o módulo mix-products ligado e o privilégio manage_mix_products ou manage_catalog. Um mix recém-criado fica desativado (D) até você mudar o status para A.

Listar mixes

GET/api/v1/admin/mix-productsAdmin

Listar mixes de todos os sellers

A lista traz os dados do mix, sem os componentes (leia um mix para vê-los). Ordem: o mais novo primeiro.

Parâmetros de consulta

pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 25
De 1 a 200. Fora disso vale 25.
statusstring
ADH
Filtra por status.
vendor_iduuid
Só mixes deste seller.
searchstring
Busca no nome, no sku e na descrição.
bash
curl "$BASE_URL/api/v1/admin/mix-products?status=A&per_page=10" \
  -H "Authorization: Bearer $TOKEN"
200Página de mixes
json
{
  "mixes": [
    {
      "id": "c4a76056-c671-4631-bbcb-65223ff3322b",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Kit Verão",
      "description": "",
      "sku": "MIX-001",
      "status": "A",
      "bundle_price_centavos": 19990,
      "currency": "BRL",
      "visibility": "public",
      "min_components": 1,
      "max_components": 5,
      "allow_customer_pick": false,
      "image_url": "",
      "created_at": "2026-07-19T13:08:54.861669Z",
      "updated_at": "2026-07-20T14:54:44.873099Z"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 10,
  "total_pages": 1
}

Criar um mix

POST/api/v1/admin/mix-productsAdmin

Criar um mix

Cria o mix com seus componentes e atribuições de uma vez, numa transação, e devolve o mix completo.

Corpo da requisição

namestringobrigatório
Nome do mix.
componentsarrayobrigatório

Componentes. Ao menos um.

product_iduuidobrigatório
Produto do componente.
quantityintegerpadrão: 1
Quantidade do produto no mix. Valor abaixo de 1 vira 1.
sort_orderinteger
Ordem de exibição.
is_requiredboolean
Se o componente é obrigatório quando o cliente monta o mix.
allow_swapboolean
Se o cliente pode trocá-lo por outro produto do mesmo grupo.
swap_groupstring
Nome do grupo de trocas. Só produtos do mesmo grupo substituem um ao outro.
bundle_price_centavosinteger
Preço do pacote, em centavos. Não pode ser negativo.
descriptionstring
Descrição.
skustring
Código do mix.
statusstringpadrão: D
ADH
A ativo, D desativado, H oculto. Vazio vira D.
currencystringpadrão: BRL
Moeda.
visibilitystringpadrão: private
publicprivatecustomer-list
Quem vê o mix na vitrine.
min_componentsintegerpadrão: 0
Mínimo de componentes que o cliente deve levar.
max_componentsintegerpadrão: 0
Máximo de componentes. 0 significa sem máximo. Se informado, min_components não pode ser maior.
allow_customer_pickbooleanpadrão: false
Se o cliente escolhe os componentes. Desligado, ele leva todos.
image_urlstring
Imagem do mix.
vendor_iduuid
Seller dono do mix. Vazio cria um mix da loja.
assignmentsarray

Para quem o mix é liberado.

customer_iduuid
Cliente atribuído.
usergroup_iduuid
Grupo de usuários atribuído. Cada item precisa de customer_id ou usergroup_id.
bash
curl -X POST "$BASE_URL/api/v1/admin/mix-products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kit Verão",
    "bundle_price_centavos": 19990,
    "status": "A",
    "visibility": "public",
    "components": [
      {"product_id": "ab3f1a07-2ae2-45b7-a4be-bcb67314d601", "quantity": 2, "is_required": true}
    ]
  }'

Ler um mix

GET/api/v1/admin/mix-products/{id}Admin

Ler um mix com componentes e atribuições

Devolve o mix completo: além dos campos da lista, components e assignments, e os totais calculados quando há componentes.

Parâmetros de caminho

iduuidobrigatório
Id do mix.
bash
curl "$BASE_URL/api/v1/admin/mix-products/050363eb-f63c-4c3c-abb6-30581638e91a" \
  -H "Authorization: Bearer $TOKEN"

Resposta (criar, ler e alterar)

200Mix completo

A criação responde 201 com o mesmo corpo.

json
{
  "id": "050363eb-f63c-4c3c-abb6-30581638e91a",
  "name": "Kit Verão",
  "description": "",
  "sku": "MIX-005",
  "status": "A",
  "bundle_price_centavos": 19990,
  "currency": "BRL",
  "visibility": "public",
  "min_components": 0,
  "max_components": 0,
  "allow_customer_pick": false,
  "image_url": "",
  "created_at": "2026-07-04T18:33:35.649004Z",
  "updated_at": "2026-07-04T18:33:35.649004Z",
  "components": [
    {
      "id": "bde899cc-65d0-459a-838f-b9cc85af6b60",
      "mix_id": "050363eb-f63c-4c3c-abb6-30581638e91a",
      "product_id": "ab3f1a07-2ae2-45b7-a4be-bcb67314d601",
      "quantity": 2,
      "sort_order": 0,
      "is_required": true,
      "allow_swap": false,
      "product_name": "Camiseta Básica",
      "product_sku": "CAM-001",
      "product_price_centavos": 8990
    }
  ],
  "component_subtotal_centavos": 17980,
  "savings_centavos": 0
}

Campos da resposta

iduuid
Id do mix.
vendor_iduuid
Seller dono. Ausente em mix da loja.
namestring
Nome.
descriptionstring
Descrição.
skustring
Código.
statusstring
ADH
Status em letra.
bundle_price_centavosinteger
Preço do pacote em centavos.
currencystring
Moeda.
visibilitystring
publicprivatecustomer-list
Visibilidade.
min_componentsinteger
Mínimo de componentes.
max_componentsinteger
Máximo de componentes (0 sem máximo).
allow_customer_pickboolean
Se o cliente escolhe.
image_urlstring
Imagem.
componentsarray
Componentes, só na leitura de um mix. Cada item traz id, mix_id, product_id, quantity, sort_order, is_required, allow_swap, swap_group e, do produto, product_name, product_sku, product_price_centavos, product_image.
assignmentsarray
Atribuições, só na leitura de um mix. Cada item traz id, mix_id, customer_id ou usergroup_id, created_at e, para exibição, customer_email ou usergroup_name.
component_subtotal_centavosinteger
Soma de preço por quantidade dos componentes. Só aparece quando é maior que zero.
savings_centavosinteger
Subtotal dos componentes menos o preço do pacote. Só aparece quando é maior que zero.
created_atstring
RFC 3339, UTC.
updated_atstring
RFC 3339, UTC.

Alterar um mix

PUT/api/v1/admin/mix-products/{id}Admin

Alterar um mix

Atualização parcial dos campos do mix. As listas têm regra própria: se você enviar components, todos os componentes são substituídos pela lista nova; se enviar assignments, todas as atribuições são substituídas. Omitir a lista a mantém. Devolve o mix completo.

Parâmetros de caminho

iduuidobrigatório
Id do mix.

Corpo da requisição

namestring
Nome.
descriptionstring
Descrição.
skustring
Código.
statusstring
ADH
Status.
bundle_price_centavosinteger
Preço do pacote em centavos, não negativo.
currencystring
Moeda.
visibilitystring
publicprivatecustomer-list
Visibilidade.
min_componentsinteger
Mínimo de componentes.
max_componentsinteger
Máximo de componentes.
allow_customer_pickboolean
Se o cliente escolhe.
image_urlstring
Imagem.
componentsarray
Lista completa de componentes, no formato da criação. Substitui a atual.
assignmentsarray
Lista completa de atribuições, no formato da criação. Substitui a atual.
bash
curl -X PUT "$BASE_URL/api/v1/admin/mix-products/050363eb-f63c-4c3c-abb6-30581638e91a" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"A","bundle_price_centavos":17990}'

Apagar um mix

DELETE/api/v1/admin/mix-products/{id}Admin

Apagar um mix

Remove o mix e, com ele, seus componentes e atribuições. Responde 204 sem corpo.

Parâmetros de caminho

iduuidobrigatório
Id do mix.
bash
curl -X DELETE "$BASE_URL/api/v1/admin/mix-products/050363eb-f63c-4c3c-abb6-30581638e91a" \
  -H "Authorization: Bearer $TOKEN"
204Mix apagado

Sem corpo.

Erros

Esta área devolve erros no formato {"error": "<código>", "message": "<texto>"}, diferente do formato {"error", "detail"} de outras áreas.

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid_body","message":"..."}
400Dados inválidos: sem name, sem componentes, status ou visibility fora da lista, preço negativo, min maior que max, componente sem product_id, atribuição sem cliente nem grupo.{"error":"invalid_input","message":"mix-products: invalid input: at least one component is required"}
401Sem token ou token expirado.{"error":"invalid or expired token"}
403Módulo desligado.{"error":"module_disabled","module":"mix-products"}
403Sem o privilégio.{"error":"insufficient privileges","privilege_required_any":["manage_mix_products","manage_catalog"]}
404GET de um mix que não existe.{"error":"not_found","message":"mix not found"}
500{id} que não é UUID; DELETE de mix que não existe.{"error":"internal_error","message":"..."}
A mensagem de 500 pode expor texto do banco

Em 500, o campo message desta área pode trazer o texto bruto do banco de dados (por exemplo invalid input syntax for type uuid). Não o exiba ao usuário final. Valide o formato do id antes de chamar.

Ative por último

Crie o mix já com os componentes e só então mude o status para A. Como o padrão é D, ele não aparece para clientes enquanto você monta.

Veja também

  • Listas sugeridas
  • Kits, mix e compartilhamento
Anterior
Kits, mix e compartilhamento
Próxima
Listas sugeridas
Nesta página
  • Listar mixes
  • Criar um mix
  • Ler um mix
  • Resposta (criar, ler e alterar)
  • Alterar um mix
  • Apagar um mix
  • Erros
  • Veja também