API atual/Guia rápido/Variações e opções

Valores de opção

Lista, cria, altera e exclui os valores de uma opção (P, M, G), com acréscimo de preço e peso e sufixo de SKU.

Os valores são as escolhas dentro de uma opção: na opção "Tamanho", os valores P, M e GG. O valor se chama variant no caminho e value no corpo. Cada valor pode:

somar ao preço do produto (um valor fixo em centavos ou um percentual);
somar ao peso, que entra no cálculo do frete;
acrescentar um sufixo ao SKU (-GG), útil para o ERP identificar a combinação.

Não confunda com "variação" (produto filho): aqui o valor não tem estoque, imagem nem produto próprios.

Listar valores

GET/api/v1/admin/products/{id}/options/{optionId}/variantsAdmin

Lista os valores de uma opção

Devolve os valores ordenados por position e depois por texto. Os valores também vêm dentro de cada opção em Listar opções, no objeto variants.

Path parameters

iduuidobrigatório

Id do produto (não é conferido).

optionIduuidobrigatório

Id da opção.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Valores da opção

json

{
  "variants": [
    {
      "id": "8770ee09-1b35-418e-bac1-60b4435ca24c",
      "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
      "value": "GG",
      "price_modifier": 500,
      "price_modifier_type": "absolute",
      "weight_modifier": 50,
      "weight_modifier_type": "absolute",
      "sku_suffix": "-GG",
      "position": 3
    }
  ]
}

Response fields

variants[].iduuid

Id do valor.

variants[].option_iduuid

Opção a que pertence.

variants[].valuestring

Texto mostrado ao cliente.

variants[].price_modifierinteger

Acréscimo de preço: centavos (absoluto) ou pontos-base (percentual). Negativo é desconto.

variants[].price_modifier_typestring

absolutepercentage

Como interpretar price_modifier.

variants[].weight_modifierinteger

Acréscimo de peso: gramas (absoluto) ou pontos-base (percentual).

variants[].weight_modifier_typestring

absolutepercentage

Como interpretar weight_modifier.

variants[].sku_suffixstring

Sufixo somado ao SKU. Vazio se não houver.

variants[].positioninteger

Ordem de exibição.

Erros

Status	Quando	Exemplo de corpo
404	A opção não existe	`{"error":"option not found"}`
401 / 403	Sem login / sem privilégio de ver o catálogo	veja Opções

Criar valor

POST/api/v1/admin/products/{id}/options/{optionId}/variantsAdmin

Cria um valor de opção

Acrescenta um valor à opção. Responde 201 com o valor criado.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção que recebe o valor.

Corpo da requisição

valuestringobrigatório

Texto do valor.

price_modifierintegerpadrão: 0

Acréscimo de preço (centavos ou pontos-base).

price_modifier_typestringpadrão: absolute

absolutepercentage

Unidade do acréscimo de preço.

weight_modifierintegerpadrão: 0

Acréscimo de peso (gramas ou pontos-base).

weight_modifier_typestringpadrão: absolute

absolutepercentage

Unidade do acréscimo de peso.

sku_suffixstring

Sufixo do SKU.

positionintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"GG","price_modifier":500,"weight_modifier":50,"sku_suffix":"-GG","position":3}'

Resposta

201Valor criado

json

{
  "id": "8770ee09-1b35-418e-bac1-60b4435ca24c",
  "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "value": "GG",
  "price_modifier": 500,
  "price_modifier_type": "absolute",
  "weight_modifier": 50,
  "weight_modifier_type": "absolute",
  "sku_suffix": "-GG",
  "position": 3
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`value` vazio	`{"error":"variant value is required"}`
500	`optionId` que não é UUID ou opção inexistente	`{"error":"failed to create variant","detail":"..."}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	veja Opções

Atualizar valor

PUT/api/v1/admin/products/{id}/options/{optionId}/variants/{variantId}Admin

Atualiza um valor de opção

Atualização parcial. Envie só os campos que mudam; pelo menos um é obrigatório.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção.

variantIduuidobrigatório

Id do valor. É o único usado para localizar o registro.

Corpo da requisição

valuestring

Novo texto.

price_modifierinteger

Novo acréscimo de preço.

price_modifier_typestring

absolutepercentage

Nova unidade.

weight_modifierinteger

Novo acréscimo de peso.

weight_modifier_typestring

absolutepercentage

Nova unidade.

sku_suffixstring

Novo sufixo.

positioninteger

Nova posição.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants/$VARIANT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price_modifier":700}'

Resposta

200Valor atualizado

json

{
  "id": "8770ee09-1b35-418e-bac1-60b4435ca24c",
  "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "value": "GG",
  "price_modifier": 700,
  "price_modifier_type": "absolute",
  "weight_modifier": 50,
  "weight_modifier_type": "absolute",
  "sku_suffix": "-GG",
  "position": 3
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo `{}`	`{"error":"no fields to update"}`
400	Valor não existe	`{"error":"option value not found"}`
401 / 403	Sem login / sem privilégio	veja acima

Excluir valor

DELETE/api/v1/admin/products/{id}/options/{optionId}/variants/{variantId}Admin

Exclui um valor de opção

Remove um valor. As outras escolhas da opção continuam como estão.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção.

variantIduuidobrigatório

Id do valor.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants/$VARIANT_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Valor excluído

json

{ "message": "variant deleted" }

Erros

Status	Quando	Exemplo de corpo
404	O valor não existe (inclusive se já foi excluído)	`{"error":"variant not found"}`
401 / 403	Sem login / sem privilégio	veja acima

Veja também

API atual/Guia rápido/Variações e opções

Valores de opção

Lista, cria, altera e exclui os valores de uma opção (P, M, G), com acréscimo de preço e peso e sufixo de SKU.

Os valores são as escolhas dentro de uma opção: na opção "Tamanho", os valores P, M e GG. O valor se chama variant no caminho e value no corpo. Cada valor pode:

somar ao preço do produto (um valor fixo em centavos ou um percentual);
somar ao peso, que entra no cálculo do frete;
acrescentar um sufixo ao SKU (-GG), útil para o ERP identificar a combinação.

Não confunda com "variação" (produto filho): aqui o valor não tem estoque, imagem nem produto próprios.

Listar valores

GET/api/v1/admin/products/{id}/options/{optionId}/variantsAdmin

Lista os valores de uma opção

Devolve os valores ordenados por position e depois por texto. Os valores também vêm dentro de cada opção em Listar opções, no objeto variants.

Path parameters

iduuidobrigatório

Id do produto (não é conferido).

optionIduuidobrigatório

Id da opção.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Valores da opção

json

{
  "variants": [
    {
      "id": "8770ee09-1b35-418e-bac1-60b4435ca24c",
      "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
      "value": "GG",
      "price_modifier": 500,
      "price_modifier_type": "absolute",
      "weight_modifier": 50,
      "weight_modifier_type": "absolute",
      "sku_suffix": "-GG",
      "position": 3
    }
  ]
}

Response fields

variants[].iduuid

Id do valor.

variants[].option_iduuid

Opção a que pertence.

variants[].valuestring

Texto mostrado ao cliente.

variants[].price_modifierinteger

Acréscimo de preço: centavos (absoluto) ou pontos-base (percentual). Negativo é desconto.

variants[].price_modifier_typestring

absolutepercentage

Como interpretar price_modifier.

variants[].weight_modifierinteger

Acréscimo de peso: gramas (absoluto) ou pontos-base (percentual).

variants[].weight_modifier_typestring

absolutepercentage

Como interpretar weight_modifier.

variants[].sku_suffixstring

Sufixo somado ao SKU. Vazio se não houver.

variants[].positioninteger

Ordem de exibição.

Erros

Status	Quando	Exemplo de corpo
404	A opção não existe	`{"error":"option not found"}`
401 / 403	Sem login / sem privilégio de ver o catálogo	veja Opções

Criar valor

POST/api/v1/admin/products/{id}/options/{optionId}/variantsAdmin

Cria um valor de opção

Acrescenta um valor à opção. Responde 201 com o valor criado.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção que recebe o valor.

Corpo da requisição

valuestringobrigatório

Texto do valor.

price_modifierintegerpadrão: 0

Acréscimo de preço (centavos ou pontos-base).

price_modifier_typestringpadrão: absolute

absolutepercentage

Unidade do acréscimo de preço.

weight_modifierintegerpadrão: 0

Acréscimo de peso (gramas ou pontos-base).

weight_modifier_typestringpadrão: absolute

absolutepercentage

Unidade do acréscimo de peso.

sku_suffixstring

Sufixo do SKU.

positionintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"GG","price_modifier":500,"weight_modifier":50,"sku_suffix":"-GG","position":3}'

Resposta

201Valor criado

json

{
  "id": "8770ee09-1b35-418e-bac1-60b4435ca24c",
  "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "value": "GG",
  "price_modifier": 500,
  "price_modifier_type": "absolute",
  "weight_modifier": 50,
  "weight_modifier_type": "absolute",
  "sku_suffix": "-GG",
  "position": 3
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`value` vazio	`{"error":"variant value is required"}`
500	`optionId` que não é UUID ou opção inexistente	`{"error":"failed to create variant","detail":"..."}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	veja Opções

Atualizar valor

PUT/api/v1/admin/products/{id}/options/{optionId}/variants/{variantId}Admin

Atualiza um valor de opção

Atualização parcial. Envie só os campos que mudam; pelo menos um é obrigatório.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção.

variantIduuidobrigatório

Id do valor. É o único usado para localizar o registro.

Corpo da requisição

valuestring

Novo texto.

price_modifierinteger

Novo acréscimo de preço.

price_modifier_typestring

absolutepercentage

Nova unidade.

weight_modifierinteger

Novo acréscimo de peso.

weight_modifier_typestring

absolutepercentage

Nova unidade.

sku_suffixstring

Novo sufixo.

positioninteger

Nova posição.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants/$VARIANT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price_modifier":700}'

Resposta

200Valor atualizado

json

{
  "id": "8770ee09-1b35-418e-bac1-60b4435ca24c",
  "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "value": "GG",
  "price_modifier": 700,
  "price_modifier_type": "absolute",
  "weight_modifier": 50,
  "weight_modifier_type": "absolute",
  "sku_suffix": "-GG",
  "position": 3
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo `{}`	`{"error":"no fields to update"}`
400	Valor não existe	`{"error":"option value not found"}`
401 / 403	Sem login / sem privilégio	veja acima

Excluir valor

DELETE/api/v1/admin/products/{id}/options/{optionId}/variants/{variantId}Admin

Exclui um valor de opção

Remove um valor. As outras escolhas da opção continuam como estão.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção.

variantIduuidobrigatório

Id do valor.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID/variants/$VARIANT_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Valor excluído

json

{ "message": "variant deleted" }

Erros

Status	Quando	Exemplo de corpo
404	O valor não existe (inclusive se já foi excluído)	`{"error":"variant not found"}`
401 / 403	Sem login / sem privilégio	veja acima