API atual/Referência completa/Catálogo: variações, tags e filtros

Editar e apagar variações

Altera e apaga variações simples e variações unificadas de um produto, e apaga exceções de combinação de opções.

Estas cinco rotas agem sobre um item pelo id dele. Antes de usar, confirme em qual dos três modelos de variação está o seu dado (veja a página da seção): variação simples tem id UUID, variação unificada tem id inteiro. Todas exigem manage_catalog.

Variação simples

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

Alterar uma variação simples

Atualização parcial: só os campos enviados mudam. Devolve a variação já atualizada.

Parâmetros de caminho

iduuidobrigatório

Id da variação.

Corpo da requisição

skustring

Código da variação. Envie "" para limpar.

priceinteger

Preço em centavos (4990 = R$ 49,90).

quantityinteger

Quantidade em estoque.

optionsobject

Mapa de eixo para valor, por exemplo {"cor":"vermelho","tamanho":"M"}. Substitui o mapa inteiro, não mescla.

image_urlstring

Imagem da variação (URL ou caminho).

bash

curl -X PUT "$BASE_URL/api/v1/admin/variations/7e4d2b10-95a3-4c6f-8e21-0b9d5a3c7f48" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price":4990,"quantity":25}'

200Variação atualizada

json

{
  "id": "7e4d2b10-95a3-4c6f-8e21-0b9d5a3c7f48",
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "sku": "CAM-VERM-M",
  "price": 4990,
  "quantity": 25,
  "options": { "cor": "vermelho", "tamanho": "M" },
  "image_url": "",
  "created_at": "2026-09-01T10:00:00Z"
}

Campos da resposta

iduuid

Id da variação.

product_iduuid

Produto dono.

skustring

Código da variação.

priceinteger

Preço em centavos.

quantityinteger

Estoque.

optionsobject

Mapa de eixo para valor.

image_urlstring

Imagem da variação.

created_atstring

RFC 3339, UTC.

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

Apagar uma variação simples

Remove a variação definitivamente.

Parâmetros de caminho

iduuidobrigatório

Id da variação.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/variations/7e4d2b10-95a3-4c6f-8e21-0b9d5a3c7f48" \
  -H "Authorization: Bearer $TOKEN"

200Variação apagada

json

{ "message": "variation deleted" }

Variação unificada

A variação unificada vive dentro de um grupo e guarda a combinação de valores ({"Cor":"Vermelho","Tamanho":"M"}) e a diferença de preço em relação ao produto pai.

PUT/api/v1/admin/unified-variations/{id}Admin

Alterar uma variação unificada

Atualização parcial. Ao marcar is_default: true, as outras variações do mesmo grupo deixam de ser a padrão. Devolve a variação atualizada.

Parâmetros de caminho

idintegerobrigatório

Id inteiro da variação unificada.

Corpo da requisição

combinationobject

Combinação eixo para valor. Substitui a combinação inteira.

price_modifierinteger

Diferença de preço sobre o pai, em centavos. Negativo dá desconto.

stockinteger

Estoque desta variação.

skustring

Código. "" limpa o código.

image_urlstring

Imagem. "" limpa a imagem.

is_defaultboolean

true torna esta a variação selecionada por padrão no grupo.

sort_orderinteger

Ordem de exibição entre as variações.

bash

curl -X PUT "$BASE_URL/api/v1/admin/unified-variations/42" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price_modifier":500,"stock":12,"is_default":true}'

200Variação atualizada

json

{
  "id": 42,
  "group_id": 7,
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "combination": { "Cor": "Vermelho", "Tamanho": "M" },
  "price_modifier": 500,
  "stock": 12,
  "sku": "CAM-VERM-M",
  "image_url": "",
  "is_default": true,
  "sort_order": 0,
  "created_at": "2026-09-01T10:00:00Z",
  "updated_at": "2026-10-11T21:40:00Z"
}

Campos da resposta

idinteger

Id da variação.

group_idinteger

Id (inteiro) do grupo unificado.

product_iduuid

Produto pai.

combinationobject

Combinação eixo para valor.

price_modifierinteger

Diferença sobre o preço do pai, em centavos.

stockinteger

Estoque.

skustring

Código. Vazio quando não há.

image_urlstring

Imagem. Vazio quando não há.

is_defaultboolean

Se é a variação padrão do grupo.

sort_orderinteger

Ordem de exibição.

created_atstring

RFC 3339, UTC.

updated_atstring

RFC 3339, UTC.

DELETE/api/v1/admin/unified-variations/{id}Admin

Apagar uma variação unificada

Remove a variação do grupo.

Parâmetros de caminho

idintegerobrigatório

Id inteiro da variação unificada.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/unified-variations/42" \
  -H "Authorization: Bearer $TOKEN"

200Variação apagada

json

{ "message": "variation deleted" }

Exceção de opção

DELETE/api/v1/admin/option-exceptions/{id}Admin

Apagar uma exceção de combinação de opções

Remove uma regra que proibia (ou permitia) uma combinação de opções do produto.

Parâmetros de caminho

iduuidobrigatório

Id da exceção.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/option-exceptions/5b2f8c61-0d34-4e97-a1c8-3f6e9b7d2a05" \
  -H "Authorization: Bearer $TOKEN"

200Exceção apagada

json

{ "message": "option exception deleted" }

Erros

Status	Quando	Corpo de exemplo
400	`PUT` com corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Unificada: o `{id}` não é um inteiro.	`{"error":"invalid variation ID","detail":"must be an integer"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Unificada: id que não existe no `PUT`, ou `PUT` sem nenhum campo.	`{"error":"variation not found"}`
404	Exceção que não existe.	`{"error":"exception not found"}`
500	Simples: id que não existe, `PUT` sem campos, ou id que não é UUID.	`{"error":"failed to update variation","detail":"variation not found"}`
500	Unificada: `DELETE` de id que não existe.	`{"error":"failed to delete variation","detail":"get variation product_id: sql: no rows in result set"}`

Veja também

API atual/Referência completa/Catálogo: variações, tags e filtros

Editar e apagar variações

Altera e apaga variações simples e variações unificadas de um produto, e apaga exceções de combinação de opções.

Variação simples

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

Alterar uma variação simples

Atualização parcial: só os campos enviados mudam. Devolve a variação já atualizada.

Parâmetros de caminho

iduuidobrigatório

Id da variação.

Corpo da requisição

skustring

Código da variação. Envie "" para limpar.

priceinteger

Preço em centavos (4990 = R$ 49,90).

quantityinteger

Quantidade em estoque.

optionsobject

Mapa de eixo para valor, por exemplo {"cor":"vermelho","tamanho":"M"}. Substitui o mapa inteiro, não mescla.

image_urlstring

Imagem da variação (URL ou caminho).

bash

curl -X PUT "$BASE_URL/api/v1/admin/variations/7e4d2b10-95a3-4c6f-8e21-0b9d5a3c7f48" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price":4990,"quantity":25}'

200Variação atualizada

json

{
  "id": "7e4d2b10-95a3-4c6f-8e21-0b9d5a3c7f48",
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "sku": "CAM-VERM-M",
  "price": 4990,
  "quantity": 25,
  "options": { "cor": "vermelho", "tamanho": "M" },
  "image_url": "",
  "created_at": "2026-09-01T10:00:00Z"
}

Campos da resposta

iduuid

Id da variação.

product_iduuid

Produto dono.

skustring

Código da variação.

priceinteger

Preço em centavos.

quantityinteger

Estoque.

optionsobject

Mapa de eixo para valor.

image_urlstring

Imagem da variação.

created_atstring

RFC 3339, UTC.

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

Apagar uma variação simples

Remove a variação definitivamente.

Parâmetros de caminho

iduuidobrigatório

Id da variação.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/variations/7e4d2b10-95a3-4c6f-8e21-0b9d5a3c7f48" \
  -H "Authorization: Bearer $TOKEN"

200Variação apagada

json

{ "message": "variation deleted" }

Variação unificada

A variação unificada vive dentro de um grupo e guarda a combinação de valores ({"Cor":"Vermelho","Tamanho":"M"}) e a diferença de preço em relação ao produto pai.

PUT/api/v1/admin/unified-variations/{id}Admin

Alterar uma variação unificada

Atualização parcial. Ao marcar is_default: true, as outras variações do mesmo grupo deixam de ser a padrão. Devolve a variação atualizada.

Parâmetros de caminho

idintegerobrigatório

Id inteiro da variação unificada.

Corpo da requisição

combinationobject

Combinação eixo para valor. Substitui a combinação inteira.

price_modifierinteger

Diferença de preço sobre o pai, em centavos. Negativo dá desconto.

stockinteger

Estoque desta variação.

skustring

Código. "" limpa o código.

image_urlstring

Imagem. "" limpa a imagem.

is_defaultboolean

true torna esta a variação selecionada por padrão no grupo.

sort_orderinteger

Ordem de exibição entre as variações.

bash

curl -X PUT "$BASE_URL/api/v1/admin/unified-variations/42" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price_modifier":500,"stock":12,"is_default":true}'

200Variação atualizada

json

{
  "id": 42,
  "group_id": 7,
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "combination": { "Cor": "Vermelho", "Tamanho": "M" },
  "price_modifier": 500,
  "stock": 12,
  "sku": "CAM-VERM-M",
  "image_url": "",
  "is_default": true,
  "sort_order": 0,
  "created_at": "2026-09-01T10:00:00Z",
  "updated_at": "2026-10-11T21:40:00Z"
}

Campos da resposta

idinteger

Id da variação.

group_idinteger

Id (inteiro) do grupo unificado.

product_iduuid

Produto pai.

combinationobject

Combinação eixo para valor.

price_modifierinteger

Diferença sobre o preço do pai, em centavos.

stockinteger

Estoque.

skustring

Código. Vazio quando não há.

image_urlstring

Imagem. Vazio quando não há.

is_defaultboolean

Se é a variação padrão do grupo.

sort_orderinteger

Ordem de exibição.

created_atstring

RFC 3339, UTC.

updated_atstring

RFC 3339, UTC.

DELETE/api/v1/admin/unified-variations/{id}Admin

Apagar uma variação unificada

Remove a variação do grupo.

Parâmetros de caminho

idintegerobrigatório

Id inteiro da variação unificada.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/unified-variations/42" \
  -H "Authorization: Bearer $TOKEN"

200Variação apagada

json

{ "message": "variation deleted" }

Exceção de opção

DELETE/api/v1/admin/option-exceptions/{id}Admin

Apagar uma exceção de combinação de opções

Remove uma regra que proibia (ou permitia) uma combinação de opções do produto.

Parâmetros de caminho

iduuidobrigatório

Id da exceção.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/option-exceptions/5b2f8c61-0d34-4e97-a1c8-3f6e9b7d2a05" \
  -H "Authorization: Bearer $TOKEN"

200Exceção apagada

json

{ "message": "option exception deleted" }

Erros

Status	Quando	Corpo de exemplo
400	`PUT` com corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Unificada: o `{id}` não é um inteiro.	`{"error":"invalid variation ID","detail":"must be an integer"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Unificada: id que não existe no `PUT`, ou `PUT` sem nenhum campo.	`{"error":"variation not found"}`
404	Exceção que não existe.	`{"error":"exception not found"}`
500	Simples: id que não existe, `PUT` sem campos, ou id que não é UUID.	`{"error":"failed to update variation","detail":"variation not found"}`
500	Unificada: `DELETE` de id que não existe.	`{"error":"failed to delete variation","detail":"get variation product_id: sql: no rows in result set"}`