VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Variações e opções

Opções de compra

Cria, lista, altera e exclui as opções de compra (tamanho, cor, texto livre, arquivo) de um produto do seller.

Uma opção é um campo que o cliente preenche ao comprar o produto. Opções de seleção (select, radio, checkbox, color) têm valores com ajuste de preço e peso, gerenciados em Valores de opção. Se cada versão precisa de estoque próprio, use variações em vez de opções.

Listar

GET/api/v1/vendor/products/{id}/optionsSeller

Listar as opções do produto

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Exemplo de requisição (listar)

bash
curl "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/options" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Opções
json
{
  "options": [
    {
      "id": "a1b2c3d4-0001-4aaa-8bbb-111122223333",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "name": "Tamanho",
      "type": "select",
      "required": true,
      "position": 0,
      "settings": {},
      "values": [
        {
          "id": "a1b2c3d4-0002-4aaa-8bbb-111122223333",
          "option_id": "a1b2c3d4-0001-4aaa-8bbb-111122223333",
          "value": "M",
          "price_modifier": 0,
          "price_modifier_type": "absolute",
          "weight_modifier": 0,
          "weight_modifier_type": "absolute",
          "sku_suffix": "-M",
          "position": 0
        }
      ]
    }
  ]
}

Campos da resposta

optionsarray

Opções em ordem de posição, cada uma com seus values. Vem null (e não lista vazia) quando o produto não tem opções.

idstring (uuid)
Id da opção.
product_idstring (uuid)
Produto dono.
namestring
Nome mostrado ao cliente.
typestring
selectradiocheckboxtextcolortextareafile
Tipo do campo.
requiredboolean
Se o cliente precisa escolher.
positioninteger
Ordem de exibição.
settingsobject
Ajustes do tipo: max_length, max_file_size_mb, allowed_types, min_select, max_select.
valuesarray
Valores escolhíveis (veja Valores de opção).

Erros (listar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}

Criar

POST/api/v1/vendor/products/{id}/optionsSeller

Criar uma opção

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Corpo da requisição

namestringobrigatório
Nome mostrado ao cliente.
typestringpadrão: select
selectradiocheckboxtextcolortextareafile
Tipo do campo. select e radio: uma escolha; checkbox: várias; text e textarea: texto livre; color: cor; file: envio de arquivo.
requiredbooleanpadrão: false
Se o cliente é obrigado a escolher.
positionintegerpadrão: 0
Ordem de exibição.
settingsobject
Ajustes por tipo: max_length (textarea, padrão 5000), max_file_size_mb (file, padrão 10), allowed_types (file, padrão jpg, jpeg, png, pdf, doc, docx, ai, eps, svg), min_select e max_select (checkbox, 0 = sem limite).

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Tamanho",
  "type": "select",
  "required": true,
  "position": 0
}'

Resposta (criar)

201Opção criada
json
{
  "id": "a1b2c3d4-0001-4aaa-8bbb-111122223333",
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "name": "Tamanho",
  "type": "select",
  "required": true,
  "position": 0,
  "settings": {},
  "values": []
}

Campos da resposta

idstring (uuid)
Id da opção.
product_idstring (uuid)
Produto dono.
namestring
Nome mostrado ao cliente.
typestring
selectradiocheckboxtextcolortextareafile
Tipo do campo.
requiredboolean
Se o cliente precisa escolher.
positioninteger
Ordem de exibição.
settingsobject
Ajustes do tipo: max_length, max_file_size_mb, allowed_types, min_select, max_select.
valuesarray
Valores escolhíveis (veja Valores de opção).

Erros (criar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
400name vazio, ou type fora da lista.{"error":"invalid option type: foo","detail":"allowed: select, radio, checkbox, text, color, textarea, file"}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}

Alterar

PUT/api/v1/vendor/products/{id}/options/{optionId}Seller

Alterar uma opção

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.
optionIdstring (uuid)obrigatório
Id da opção.

Corpo da requisição

namestring
Novo nome.
typestring
selectradiocheckboxtextcolortextareafile
Novo tipo.
requiredboolean
Obrigatória ou não.
positioninteger
Nova ordem.
settingsobject
Novos ajustes do tipo.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/options/$OPTION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "required": false,
  "position": 1
}'

Resposta (alterar)

200Opção alterada
json
{
  "id": "a1b2c3d4-0001-4aaa-8bbb-111122223333",
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "name": "Tamanho",
  "type": "select",
  "required": false,
  "position": 1,
  "settings": {},
  "values": [
    {
      "id": "a1b2c3d4-0002-4aaa-8bbb-111122223333",
      "option_id": "a1b2c3d4-0001-4aaa-8bbb-111122223333",
      "value": "M",
      "price_modifier": 0,
      "price_modifier_type": "absolute",
      "weight_modifier": 0,
      "weight_modifier_type": "absolute",
      "sku_suffix": "-M",
      "position": 0
    }
  ]
}

Campos da resposta

idstring (uuid)
Id da opção.
product_idstring (uuid)
Produto dono.
namestring
Nome mostrado ao cliente.
typestring
selectradiocheckboxtextcolortextareafile
Tipo do campo.
requiredboolean
Se o cliente precisa escolher.
positioninteger
Ordem de exibição.
settingsobject
Ajustes do tipo: max_length, max_file_size_mb, allowed_types, min_select, max_select.
valuesarray
Valores escolhíveis (veja Valores de opção).

Erros (alterar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
400Opção inexistente, tipo inválido ou corpo sem campo para alterar.{"error":"no fields to update"}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}

Excluir

DELETE/api/v1/vendor/products/{id}/options/{optionId}Seller

Excluir uma opção

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.
optionIdstring (uuid)obrigatório
Id da opção.

Exemplo de requisição (excluir)

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

Resposta (excluir)

200Opção excluída
json
{
  "message": "option deleted"
}

Campos da resposta

messagestring
Confirmação fixa.

Erros (excluir)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404A opção não existe.{"error":"option not found"}
Excluir leva os valores junto

Excluir uma opção apaga todos os seus valores, e pedidos futuros deixam de oferecê-la. Não há desfazer.

Ids de opção não são conferidos

Em PUT e DELETE, a plataforma confere se o produto do caminho é seu, mas não confere se optionId pertence a ele. Nunca use um id que não veio da lista deste produto.

Veja também

  • Variações e opções: visão geral
  • Produtos do seller
Anterior
Variações e opções
Próxima
Valores de opção
Nesta página
  • Listar
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Alterar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Excluir
  • Exemplo de requisição (excluir)
  • Resposta (excluir)
  • Erros (excluir)
  • Veja também