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

Opções do produto

Lista, cria, altera e exclui as opções de compra de um produto (tamanho, gravação, cor da fita).

Uma opção é uma escolha que o cliente faz no carrinho sobre um produto: "Tamanho" (lista), "Gravação" (texto livre), "Embalagem para presente" (caixa de seleção). Cada opção tem valores (P, M, G), e cada valor pode somar preço e peso e acrescentar um sufixo ao SKU. Os valores são tratados em Valores de opção.

Opções não têm estoque próprio: o estoque continua sendo o do produto. Se cada tamanho precisa de estoque, use Variações. Excluir uma opção apaga também todos os valores dela.

Listar opções

GET/api/v1/admin/products/{id}/optionsAdmin

Lista as opções de um produto

Devolve as opções ordenadas por position e depois por nome, cada uma com seus valores.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/07635228-fcac-442e-9a0c-caa7c1c89a97/options" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resposta

json

{
  "options": [
    {
      "id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
      "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
      "name": "Tamanho da camiseta",
      "type": "select",
      "required": true,
      "position": 0,
      "settings": {},
      "values": [
        {
          "id": "4e76c1af-82df-485c-9f88-11a8db6f987e",
          "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
          "value": "P",
          "price_modifier": 0,
          "price_modifier_type": "absolute",
          "weight_modifier": 0,
          "weight_modifier_type": "absolute",
          "sku_suffix": "-P",
          "position": 1
        },
        {
          "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
        }
      ]
    }
  ]
}

Campos da resposta

optionsarray | null

Opções do produto. Atenção: um produto sem nenhuma opção devolve null, não []. Trate os dois.

options[].iduuid

Id da opção.

options[].product_iduuid

Produto dono da opção.

options[].namestring

Nome mostrado ao cliente.

options[].typestring

selectradiocheckboxtextcolortextareafile

Como o cliente escolhe.

options[].requiredboolean

Se o cliente é obrigado a preencher.

options[].positioninteger

Ordem de exibição, crescente.

options[].settingsobject

Ajustes por tipo (veja Criar opção). {} se não houver.

options[].valuesarray

Valores da opção, ordenados por position. Campos em Valores de opção.

Erros

Status	Quando	Exemplo de corpo
401	Sem credenciais ou token inválido	`{"error":"missing authorization header"}`
403	Sem privilégio de ver o catálogo	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
500	Id que não é UUID (`/products/abc/options`)	`{"error":"failed to list options","detail":"..."}`

Criar opção

POST/api/v1/admin/products/{id}/optionsAdmin

Cria uma opção

Cria uma opção sem valores. Depois, acrescente os valores com Criar valor. Responde 201 com a opção criada.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

namestringobrigatório

Nome da opção, mostrado ao cliente.

typestringpadrão: select

selectradiocheckboxtextcolortextareafile

Como o cliente escolhe. select é lista suspensa, radio é escolha única em botões, checkbox é múltipla escolha, text é uma linha livre, textarea é texto longo, color é seletor de cor, file é envio de arquivo.

requiredbooleanpadrão: false

Se o cliente precisa preencher para comprar.

positionintegerpadrão: 0

Ordem de exibição.

settingsobject

Ajustes que dependem do tipo.

max_lengthinteger

textarea: máximo de caracteres. Se omitido, vale 5000.

max_file_size_mbinteger

file: tamanho máximo do arquivo em MB. Se omitido, vale 10.

allowed_typesarray

file: extensões aceitas. Se omitido: jpg, jpeg, png, pdf, doc, docx, ai, eps, svg.

min_selectinteger

checkbox: mínimo de escolhas. 0 = sem mínimo extra.

max_selectinteger

checkbox: máximo de escolhas. 0 = sem máximo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/07635228-fcac-442e-9a0c-caa7c1c89a97/options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tamanho","type":"select","required":true,"position":1}'

Resposta

201Opção criada

json

{
  "id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "name": "Tamanho",
  "type": "select",
  "required": true,
  "position": 1,
  "settings": {},
  "values": []
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"option name is required"}`
400	`type` desconhecido	`{"error":"invalid option type: bogus","detail":"allowed: select, radio, checkbox, text, color, textarea, file"}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	`{"error":"insufficient privileges","required":"manage_catalog"}`
500	`id` que não é UUID ou produto inexistente	`{"error":"failed to create option","detail":"..."}`

Atualizar opção

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

Atualiza uma opção

Atualização parcial: envie só o que muda. Pelo menos um campo é obrigatório. Os valores da opção não são alterados aqui.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção. Só ele é usado para localizar a opção: a rota não confere se a opção pertence ao id informado.

Corpo da requisição

namestring

Novo nome.

typestring

selectradiocheckboxtextcolortextareafile

Novo tipo.

requiredboolean

Obrigatória ou não.

positioninteger

Nova posição.

settingsobject

Substitui os ajustes inteiros (mesmos campos de Criar opção).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tamanho da camiseta","position":0}'

Resposta

200Opção atualizada, com os valores

json

{
  "id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "name": "Tamanho da camiseta",
  "type": "select",
  "required": true,
  "position": 0,
  "settings": {},
  "values": [
    {
      "id": "4e76c1af-82df-485c-9f88-11a8db6f987e",
      "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
      "value": "P",
      "price_modifier": 0,
      "price_modifier_type": "absolute",
      "weight_modifier": 0,
      "weight_modifier_type": "absolute",
      "sku_suffix": "-P",
      "position": 1
    }
  ]
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo vazio `{}`	`{"error":"no fields to update"}`
400	Opção não existe	`{"error":"option not found"}`
500	`type` inválido (a validação acontece tarde e vira erro de servidor)	`{"error":"failed to update option","detail":"invalid option type: zzz"}`
401 / 403	Sem login / sem privilégio	veja acima

Excluir opção

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

Exclui uma opção e seus valores

Remove a opção e todos os seus valores. Não há como desfazer.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção.

Exemplo de requisição

bash

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

Resposta

200Opção excluída

json

{ "message": "option deleted" }

Erros

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

Veja também

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

Opções do produto

Lista, cria, altera e exclui as opções de compra de um produto (tamanho, gravação, cor da fita).

Opções não têm estoque próprio: o estoque continua sendo o do produto. Se cada tamanho precisa de estoque, use Variações. Excluir uma opção apaga também todos os valores dela.

Listar opções

GET/api/v1/admin/products/{id}/optionsAdmin

Lista as opções de um produto

Devolve as opções ordenadas por position e depois por nome, cada uma com seus valores.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/07635228-fcac-442e-9a0c-caa7c1c89a97/options" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resposta

json

{
  "options": [
    {
      "id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
      "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
      "name": "Tamanho da camiseta",
      "type": "select",
      "required": true,
      "position": 0,
      "settings": {},
      "values": [
        {
          "id": "4e76c1af-82df-485c-9f88-11a8db6f987e",
          "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
          "value": "P",
          "price_modifier": 0,
          "price_modifier_type": "absolute",
          "weight_modifier": 0,
          "weight_modifier_type": "absolute",
          "sku_suffix": "-P",
          "position": 1
        },
        {
          "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
        }
      ]
    }
  ]
}

Campos da resposta

optionsarray | null

Opções do produto. Atenção: um produto sem nenhuma opção devolve null, não []. Trate os dois.

options[].iduuid

Id da opção.

options[].product_iduuid

Produto dono da opção.

options[].namestring

Nome mostrado ao cliente.

options[].typestring

selectradiocheckboxtextcolortextareafile

Como o cliente escolhe.

options[].requiredboolean

Se o cliente é obrigado a preencher.

options[].positioninteger

Ordem de exibição, crescente.

options[].settingsobject

Ajustes por tipo (veja Criar opção). {} se não houver.

options[].valuesarray

Valores da opção, ordenados por position. Campos em Valores de opção.

Erros

Status	Quando	Exemplo de corpo
401	Sem credenciais ou token inválido	`{"error":"missing authorization header"}`
403	Sem privilégio de ver o catálogo	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
500	Id que não é UUID (`/products/abc/options`)	`{"error":"failed to list options","detail":"..."}`

Criar opção

POST/api/v1/admin/products/{id}/optionsAdmin

Cria uma opção

Cria uma opção sem valores. Depois, acrescente os valores com Criar valor. Responde 201 com a opção criada.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

namestringobrigatório

Nome da opção, mostrado ao cliente.

typestringpadrão: select

selectradiocheckboxtextcolortextareafile

requiredbooleanpadrão: false

Se o cliente precisa preencher para comprar.

positionintegerpadrão: 0

Ordem de exibição.

settingsobject

Ajustes que dependem do tipo.

max_lengthinteger

textarea: máximo de caracteres. Se omitido, vale 5000.

max_file_size_mbinteger

file: tamanho máximo do arquivo em MB. Se omitido, vale 10.

allowed_typesarray

file: extensões aceitas. Se omitido: jpg, jpeg, png, pdf, doc, docx, ai, eps, svg.

min_selectinteger

checkbox: mínimo de escolhas. 0 = sem mínimo extra.

max_selectinteger

checkbox: máximo de escolhas. 0 = sem máximo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/07635228-fcac-442e-9a0c-caa7c1c89a97/options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tamanho","type":"select","required":true,"position":1}'

Resposta

201Opção criada

json

{
  "id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "name": "Tamanho",
  "type": "select",
  "required": true,
  "position": 1,
  "settings": {},
  "values": []
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"option name is required"}`
400	`type` desconhecido	`{"error":"invalid option type: bogus","detail":"allowed: select, radio, checkbox, text, color, textarea, file"}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	`{"error":"insufficient privileges","required":"manage_catalog"}`
500	`id` que não é UUID ou produto inexistente	`{"error":"failed to create option","detail":"..."}`

Atualizar opção

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

Atualiza uma opção

Atualização parcial: envie só o que muda. Pelo menos um campo é obrigatório. Os valores da opção não são alterados aqui.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção. Só ele é usado para localizar a opção: a rota não confere se a opção pertence ao id informado.

Corpo da requisição

namestring

Novo nome.

typestring

selectradiocheckboxtextcolortextareafile

Novo tipo.

requiredboolean

Obrigatória ou não.

positioninteger

Nova posição.

settingsobject

Substitui os ajustes inteiros (mesmos campos de Criar opção).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/options/$OPTION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tamanho da camiseta","position":0}'

Resposta

200Opção atualizada, com os valores

json

{
  "id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
  "product_id": "07635228-fcac-442e-9a0c-caa7c1c89a97",
  "name": "Tamanho da camiseta",
  "type": "select",
  "required": true,
  "position": 0,
  "settings": {},
  "values": [
    {
      "id": "4e76c1af-82df-485c-9f88-11a8db6f987e",
      "option_id": "d89e2489-1661-423e-9cda-dc2c2903fcf4",
      "value": "P",
      "price_modifier": 0,
      "price_modifier_type": "absolute",
      "weight_modifier": 0,
      "weight_modifier_type": "absolute",
      "sku_suffix": "-P",
      "position": 1
    }
  ]
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo vazio `{}`	`{"error":"no fields to update"}`
400	Opção não existe	`{"error":"option not found"}`
500	`type` inválido (a validação acontece tarde e vira erro de servidor)	`{"error":"failed to update option","detail":"invalid option type: zzz"}`
401 / 403	Sem login / sem privilégio	veja acima

Excluir opção

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

Exclui uma opção e seus valores

Remove a opção e todos os seus valores. Não há como desfazer.

Path parameters

iduuidobrigatório

Id do produto.

optionIduuidobrigatório

Id da opção.

Exemplo de requisição

bash

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

Resposta

200Opção excluída

json

{ "message": "option deleted" }

Erros

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