API atual/Referência completa/Variações e opções

Variações unificadas

Matriz de combinações (cor x tamanho) dentro de um único produto, com estoque, SKU, imagem e acréscimo de preço por combinação.

As variações unificadas guardam todas as combinações dentro de um só produto, sem criar produtos filhos. Você define o grupo com os eixos e seus valores (Cor: Azul, Preto e Tamanho: P, M, G) e, para cada combinação, uma linha com estoque, SKU, imagem e um acréscimo de preço sobre o preço do produto.

Use quando cada combinação precisa de estoque próprio, mas o cadastro de um produto por combinação seria exagero. Se cada combinação precisa de página, preço, fotos e SKU como um produto completo, use Variações.

Editar uma linha (PUT /api/v1/admin/unified-variations/{id}) e excluí-la (DELETE) estão na referência completa do administrador; a lista abaixo cobre a montagem da matriz.

Consultar grupo e linhas

GET/api/v1/admin/products/{id}/unified-variation-groupAdmin

Consulta o grupo e todas as suas linhas

Devolve o grupo (eixos) e todas as linhas de uma vez. Produto sem grupo devolve group: null e lista vazia.

Path parameters

iduuidobrigatório

Id do produto.

GET/api/v1/admin/products/{id}/unified-variationsAdmin

Lista somente as linhas

Devolve só as linhas, ordenadas por sort_order e id, com o total. Produto sem grupo devolve lista vazia.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variation-group" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grupo com linhas (resumido)

json

{
  "group": {
    "id": 5,
    "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
    "name": "Cor e tamanho",
    "features": [
      { "name": "Cor", "values": ["Azul", "Preto"] },
      { "name": "Tamanho", "values": ["P", "M", "G"] }
    ],
    "created_at": "2026-10-11T20:54:06.230905Z"
  },
  "variations": [
    {
      "id": 14,
      "group_id": 5,
      "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
      "combination": { "Cor": "Azul", "Tamanho": "P" },
      "price_modifier": 0,
      "stock": 5,
      "sku": "",
      "image_url": "",
      "is_default": false,
      "sort_order": 0,
      "created_at": "2026-10-11T20:54:06.300907Z",
      "updated_at": "2026-10-11T20:54:06.300907Z"
    }
  ]
}

200Produto sem grupo

json

{ "group": null, "variations": [] }

Response fields

group.idinteger

Id do grupo.

group.namestring

Nome do grupo (livre).

group.featuresarray

Eixos: cada um com name e a lista values.

variations[].idinteger

Id da linha.

variations[].combinationobject

Valor em cada eixo ({"Cor":"Azul","Tamanho":"P"}).

variations[].price_modifierinteger

Acréscimo em centavos sobre o preço do produto. Pode ser negativo.

variations[].stockinteger

Estoque da combinação.

variations[].skustring

SKU da combinação. Vazio se não houver.

variations[].image_urlstring

Imagem da combinação. Vazio se não houver.

variations[].is_defaultboolean

Se é a combinação pré-selecionada. Só uma por grupo.

variations[].sort_orderinteger

Ordem de exibição.

Erros

Status	Quando	Exemplo de corpo
500	`id` que não é UUID	`{"error":"failed to get variation group","detail":"..."}` (ou `"failed to list variations"` na lista)
401 / 403	Sem login / sem privilégio de ver o catálogo	veja Opções

Criar ou substituir o grupo

PUT/api/v1/admin/products/{id}/unified-variation-groupAdmin

Cria ou substitui o grupo

Define os eixos do produto. Se já havia um grupo, ele é apagado junto com todas as linhas e um novo é criado. Depois, gere as combinações (veja Gerar combinações, abaixo) ou crie as linhas uma a uma.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

namestring

Nome do grupo (livre).

featuresarrayobrigatório

Eixos. Pelo menos um.

namestringobrigatório

Nome do eixo (Cor). É a chave usada em combination.

valuesarrayobrigatório

Valores do eixo, em texto (["Azul","Preto"]).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variation-group" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cor e tamanho","features":[{"name":"Cor","values":["Azul","Preto"]},{"name":"Tamanho","values":["P","M","G"]}]}'

Resposta

200Grupo criado

json

{
  "id": 5,
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "name": "Cor e tamanho",
  "features": [
    { "name": "Cor", "values": ["Azul", "Preto"] },
    { "name": "Tamanho", "values": ["P", "M", "G"] }
  ],
  "created_at": "2026-10-11T20:54:06.230905Z"
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`features` vazio	`{"error":"at least one feature axis is required"}`
404	Produto não existe	`{"error":"product not found"}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	veja Opções

Gerar combinações

POST/api/v1/admin/products/{id}/unified-variations/generateAdmin

Gera todas as combinações dos eixos

Cria uma linha para cada combinação possível dos eixos do grupo (o produto cartesiano). Combinações que já existem são puladas, então pode ser chamada de novo depois de acrescentar um valor ao eixo. Cada linha nasce com acréscimo 0, sem SKU e sem imagem, e com o estoque inicial que você informar. O limite é 1000 combinações por chamada (por exemplo, 10 x 10 x 10 x 2 passa do limite).

O corpo é opcional: sem corpo, o estoque inicial é 0.

Path parameters

iduuidobrigatório

Id do produto, que já deve ter um grupo.

Corpo da requisição

default_stockintegerpadrão: 0

Estoque inicial de cada linha criada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variations/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_stock":5}'

Resposta

200Linhas criadas (uma mostrada)

json

{
  "generated": 6,
  "variations": [
    {
      "id": 14,
      "group_id": 5,
      "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
      "combination": { "Cor": "Azul", "Tamanho": "P" },
      "price_modifier": 0,
      "stock": 5,
      "sku": "",
      "image_url": "",
      "is_default": false,
      "sort_order": 0,
      "created_at": "2026-10-11T20:54:06.300907Z",
      "updated_at": "2026-10-11T20:54:06.300907Z"
    }
  ]
}

Response fields

generatedinteger

Linhas criadas agora. 0 se todas as combinações já existiam. Quando não cria nada, variations vem null.

variationsarray | null

As linhas criadas.

Erros

Status	Quando	Exemplo de corpo
500	Produto sem grupo	`{"error":"failed to generate variations","detail":"no variation group exists for this product; create one first"}`
500	Mais de 1000 combinações	`{"error":"failed to generate variations","detail":"too many variations (would generate 1200, max is 1000)"}`
500	Grupo sem eixos	`{"error":"failed to generate variations","detail":"variation group has no feature axes defined"}`

Criar uma linha

POST/api/v1/admin/products/{id}/unified-variationsAdmin

Cria uma linha

Cria uma única combinação, com SKU, imagem, estoque e acréscimo. Útil para criar um valor fora do que foi gerado ou para criar já com os dados completos. Marcar is_default desmarca a anterior.

Path parameters

iduuidobrigatório

Id do produto, que já deve ter um grupo.

Corpo da requisição

combinationobjectobrigatório

Valor em cada eixo, como texto: {"Cor":"Verde","Tamanho":"GG"}. Não pode ser vazio.

price_modifierintegerpadrão: 0

Acréscimo em centavos sobre o preço do produto (negativo para desconto).

stockintegerpadrão: 0

Estoque da combinação.

skustring

SKU da combinação.

image_urlstring

URL da imagem da combinação.

is_defaultbooleanpadrão: false

Combinação pré-selecionada.

sort_orderintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"combination":{"Cor":"Verde","Tamanho":"GG"},"price_modifier":1000,"stock":3,"sku":"CAM-VRD-GG","is_default":true}'

Resposta

201Linha criada

json

{
  "id": 20,
  "group_id": 5,
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "combination": { "Cor": "Verde", "Tamanho": "GG" },
  "price_modifier": 1000,
  "stock": 3,
  "sku": "CAM-VRD-GG",
  "image_url": "",
  "is_default": true,
  "sort_order": 0,
  "created_at": "2026-10-11T20:54:06.381578Z",
  "updated_at": "2026-10-11T20:54:06.381578Z"
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`combination` vazio	`{"error":"combination is required"}`
500	Produto sem grupo	`{"error":"failed to create variation","detail":"no variation group exists for this product; create one first"}`
401 / 403	Sem login / sem privilégio	veja Opções

Veja também

API atual/Referência completa/Variações e opções

Variações unificadas

Matriz de combinações (cor x tamanho) dentro de um único produto, com estoque, SKU, imagem e acréscimo de preço por combinação.

Editar uma linha (PUT /api/v1/admin/unified-variations/{id}) e excluí-la (DELETE) estão na referência completa do administrador; a lista abaixo cobre a montagem da matriz.

Consultar grupo e linhas

GET/api/v1/admin/products/{id}/unified-variation-groupAdmin

Consulta o grupo e todas as suas linhas

Devolve o grupo (eixos) e todas as linhas de uma vez. Produto sem grupo devolve group: null e lista vazia.

Path parameters

iduuidobrigatório

Id do produto.

GET/api/v1/admin/products/{id}/unified-variationsAdmin

Lista somente as linhas

Devolve só as linhas, ordenadas por sort_order e id, com o total. Produto sem grupo devolve lista vazia.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variation-group" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grupo com linhas (resumido)

json

{
  "group": {
    "id": 5,
    "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
    "name": "Cor e tamanho",
    "features": [
      { "name": "Cor", "values": ["Azul", "Preto"] },
      { "name": "Tamanho", "values": ["P", "M", "G"] }
    ],
    "created_at": "2026-10-11T20:54:06.230905Z"
  },
  "variations": [
    {
      "id": 14,
      "group_id": 5,
      "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
      "combination": { "Cor": "Azul", "Tamanho": "P" },
      "price_modifier": 0,
      "stock": 5,
      "sku": "",
      "image_url": "",
      "is_default": false,
      "sort_order": 0,
      "created_at": "2026-10-11T20:54:06.300907Z",
      "updated_at": "2026-10-11T20:54:06.300907Z"
    }
  ]
}

200Produto sem grupo

json

{ "group": null, "variations": [] }

Response fields

group.idinteger

Id do grupo.

group.namestring

Nome do grupo (livre).

group.featuresarray

Eixos: cada um com name e a lista values.

variations[].idinteger

Id da linha.

variations[].combinationobject

Valor em cada eixo ({"Cor":"Azul","Tamanho":"P"}).

variations[].price_modifierinteger

Acréscimo em centavos sobre o preço do produto. Pode ser negativo.

variations[].stockinteger

Estoque da combinação.

variations[].skustring

SKU da combinação. Vazio se não houver.

variations[].image_urlstring

Imagem da combinação. Vazio se não houver.

variations[].is_defaultboolean

Se é a combinação pré-selecionada. Só uma por grupo.

variations[].sort_orderinteger

Ordem de exibição.

Erros

Status	Quando	Exemplo de corpo
500	`id` que não é UUID	`{"error":"failed to get variation group","detail":"..."}` (ou `"failed to list variations"` na lista)
401 / 403	Sem login / sem privilégio de ver o catálogo	veja Opções

Criar ou substituir o grupo

PUT/api/v1/admin/products/{id}/unified-variation-groupAdmin

Cria ou substitui o grupo

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

namestring

Nome do grupo (livre).

featuresarrayobrigatório

Eixos. Pelo menos um.

namestringobrigatório

Nome do eixo (Cor). É a chave usada em combination.

valuesarrayobrigatório

Valores do eixo, em texto (["Azul","Preto"]).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variation-group" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cor e tamanho","features":[{"name":"Cor","values":["Azul","Preto"]},{"name":"Tamanho","values":["P","M","G"]}]}'

Resposta

200Grupo criado

json

{
  "id": 5,
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "name": "Cor e tamanho",
  "features": [
    { "name": "Cor", "values": ["Azul", "Preto"] },
    { "name": "Tamanho", "values": ["P", "M", "G"] }
  ],
  "created_at": "2026-10-11T20:54:06.230905Z"
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`features` vazio	`{"error":"at least one feature axis is required"}`
404	Produto não existe	`{"error":"product not found"}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	veja Opções

Gerar combinações

POST/api/v1/admin/products/{id}/unified-variations/generateAdmin

Gera todas as combinações dos eixos

O corpo é opcional: sem corpo, o estoque inicial é 0.

Path parameters

iduuidobrigatório

Id do produto, que já deve ter um grupo.

Corpo da requisição

default_stockintegerpadrão: 0

Estoque inicial de cada linha criada.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variations/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_stock":5}'

Resposta

200Linhas criadas (uma mostrada)

json

{
  "generated": 6,
  "variations": [
    {
      "id": 14,
      "group_id": 5,
      "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
      "combination": { "Cor": "Azul", "Tamanho": "P" },
      "price_modifier": 0,
      "stock": 5,
      "sku": "",
      "image_url": "",
      "is_default": false,
      "sort_order": 0,
      "created_at": "2026-10-11T20:54:06.300907Z",
      "updated_at": "2026-10-11T20:54:06.300907Z"
    }
  ]
}

Response fields

generatedinteger

Linhas criadas agora. 0 se todas as combinações já existiam. Quando não cria nada, variations vem null.

variationsarray | null

As linhas criadas.

Erros

Status	Quando	Exemplo de corpo
500	Produto sem grupo	`{"error":"failed to generate variations","detail":"no variation group exists for this product; create one first"}`
500	Mais de 1000 combinações	`{"error":"failed to generate variations","detail":"too many variations (would generate 1200, max is 1000)"}`
500	Grupo sem eixos	`{"error":"failed to generate variations","detail":"variation group has no feature axes defined"}`

Criar uma linha

POST/api/v1/admin/products/{id}/unified-variationsAdmin

Cria uma linha

Path parameters

iduuidobrigatório

Id do produto, que já deve ter um grupo.

Corpo da requisição

combinationobjectobrigatório

Valor em cada eixo, como texto: {"Cor":"Verde","Tamanho":"GG"}. Não pode ser vazio.

price_modifierintegerpadrão: 0

Acréscimo em centavos sobre o preço do produto (negativo para desconto).

stockintegerpadrão: 0

Estoque da combinação.

skustring

SKU da combinação.

image_urlstring

URL da imagem da combinação.

is_defaultbooleanpadrão: false

Combinação pré-selecionada.

sort_orderintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/unified-variations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"combination":{"Cor":"Verde","Tamanho":"GG"},"price_modifier":1000,"stock":3,"sku":"CAM-VRD-GG","is_default":true}'

Resposta

201Linha criada

json

{
  "id": 20,
  "group_id": 5,
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "combination": { "Cor": "Verde", "Tamanho": "GG" },
  "price_modifier": 1000,
  "stock": 3,
  "sku": "CAM-VRD-GG",
  "image_url": "",
  "is_default": true,
  "sort_order": 0,
  "created_at": "2026-10-11T20:54:06.381578Z",
  "updated_at": "2026-10-11T20:54:06.381578Z"
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`combination` vazio	`{"error":"combination is required"}`
500	Produto sem grupo	`{"error":"failed to create variation","detail":"no variation group exists for this product; create one first"}`
401 / 403	Sem login / sem privilégio	veja Opções