VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
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).
200Variação atualizada

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.
200Variação apagada

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.
200Variação atualizada

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.
200Variação apagada

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.
200Exceção apagada

Erros

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

Na variação simples, qualquer id inexistente responde 500 com variation not found em detail. Na unificada, o PUT dá 404, mas o DELETE de um id inexistente dá 500. Teste o detail, não só o status.

Preço final da variação

Na variação simples, price é o preço final. Na unificada, price_modifier é só a diferença sobre o pai: o preço final é preço do pai + price_modifier.

Veja também

  • Grupos de variação
  • Tags e filtros
  • Variações, tags e filtros
Anterior
Variações, tags e filtros
Próxima
Grupos de variação
Nesta página
  • Variação simples
  • Variação unificada
  • Exceção de opção
  • Erros
  • Veja também
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}'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/variations/7e4d2b10-95a3-4c6f-8e21-0b9d5a3c7f48" \
  -H "Authorization: Bearer $TOKEN"
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}'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/unified-variations/42" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X DELETE "$BASE_URL/api/v1/admin/option-exceptions/5b2f8c61-0d34-4e97-a1c8-3f6e9b7d2a05" \
  -H "Authorization: Bearer $TOKEN"
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"
}
json
{ "message": "variation deleted" }
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"
}
json
{ "message": "variation deleted" }
json
{ "message": "option exception deleted" }