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

Cadastro de opções

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

Uma opção é uma escolha que o cliente faz no carrinho sobre um produto, e cada opção tem valores (P, M, G). As rotas desta página são as de manutenção do cadastro, no contrato da Venddor 1.0: elas servem a quem sincroniza opções de um sistema externo. Todas exigem um administrador. Opções não têm estoque próprio; para estoque por combinação, veja Combinações.

Listar as opções de um produto

Devolve todas as opções de compra de um produto, cada uma com seus valores. É a leitura em lote de quem mantém o cadastro; para apenas consultar as opções no estilo da vitrine, veja Opções do produto.

GET/api/v1.0/optionsAdmin

Listar opções de um produto

A resposta é uma lista JSON pura (sem envelope). Um produto sem opções, ou que não existe, devolve [] com 200. Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de consulta

product_idstringobrigatório
Id do produto (UUID).

Exemplo de requisição

bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/options?product_id=48e87591-5fb1-40da-b32e-edec3a8c596d"

Resposta

200Opções devolvidas
json
[
  {
    "option_id": "5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10",
    "product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d",
    "option_name": "Tamanho",
    "option_type": "S",
    "required": "Y",
    "position": 1,
    "variants": {
      "a1b2c3d4-0001-4aaa-9bbb-000000000001": {
        "variant_id": "a1b2c3d4-0001-4aaa-9bbb-000000000001",
        "variant_name": "M",
        "modifier_type": "A",
        "modifier": "0.00",
        "weight_modifier_type": "A",
        "weight_modifier": 0,
        "sku_suffix": "-M",
        "position": 1
      },
      "a1b2c3d4-0002-4aaa-9bbb-000000000002": {
        "variant_id": "a1b2c3d4-0002-4aaa-9bbb-000000000002",
        "variant_name": "G",
        "modifier_type": "A",
        "modifier": "5.00",
        "weight_modifier_type": "A",
        "weight_modifier": 0,
        "sku_suffix": "-G",
        "position": 2
      }
    }
  }
]

Campos da resposta

option_idstring
Id da opção (UUID).
product_idstring
Id do produto dono da opção (UUID).
option_namestring
Nome da opção, como o cliente vê no carrinho.
option_typestring
SRCITF
Tipo da opção: S lista, R botões de rádio, C caixa de seleção, I texto de uma linha, T texto de várias linhas, F arquivo.
requiredstring
YN
Y se o cliente é obrigado a escolher, N caso contrário.
positioninteger
Posição de exibição.
variantsobject
Valores da opção, indexados pelo id de cada valor. Opções de texto ou arquivo vêm com o objeto vazio.
variants.{id}.variant_idstring
Id do valor (UUID).
variants.{id}.variant_namestring
Texto do valor, por exemplo M.
variants.{id}.modifier_typestring
AP
A soma um valor absoluto ao preço, P soma uma porcentagem.
variants.{id}.modifierstring
Quanto o valor soma ao preço, em string decimal ("5.00"). Com modifier_type igual a P, é o percentual.
variants.{id}.weight_modifier_typestring
AP
A ou P, como em modifier_type, mas para o peso.
variants.{id}.weight_modifiernumber
Quanto o valor soma ao peso.
variants.{id}.sku_suffixstring
Sufixo acrescentado ao código (SKU) do produto quando este valor é escolhido.
variants.{id}.positioninteger
Posição do valor dentro da opção.

Erros

StatusQuandoCorpo
400product_id ausente{"error":"product_id is required"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"query options: ..."}
Atenção ao formato do erro

Nesta família de rotas os erros de validação chegam como {"error":"..."}, enquanto autenticação e permissão usam {"message":"...","status":N}. Trate os dois formatos.

Consultar uma opção

Devolve uma opção pelo id, com os valores. Use depois de listar, ou quando você já guardou o id devolvido na criação.

GET/api/v1.0/options/{id}Admin

Consultar uma opção

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

idstringobrigatório
Id da opção (UUID).

Exemplo de requisição

bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/options/5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10"

Resposta

200Opção devolvida
json
{
  "option_id": "5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10",
  "product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d",
  "option_name": "Tamanho",
  "option_type": "S",
  "required": "Y",
  "position": 1,
  "variants": {
    "a1b2c3d4-0001-4aaa-9bbb-000000000001": {
      "variant_id": "a1b2c3d4-0001-4aaa-9bbb-000000000001",
      "variant_name": "M",
      "modifier_type": "A",
      "modifier": "0.00",
      "weight_modifier_type": "A",
      "weight_modifier": 0,
      "sku_suffix": "-M",
      "position": 1
    },
    "a1b2c3d4-0002-4aaa-9bbb-000000000002": {
      "variant_id": "a1b2c3d4-0002-4aaa-9bbb-000000000002",
      "variant_name": "G",
      "modifier_type": "A",
      "modifier": "5.00",
      "weight_modifier_type": "A",
      "weight_modifier": 0,
      "sku_suffix": "-G",
      "position": 2
    }
  }
}

O objeto tem os mesmos campos de cada item da listagem.

Erros

StatusQuandoCorpo
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
404A opção não existe{"error":"Option not found"}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"query option ...: ..."}

Criar uma opção

Cria uma opção para um produto e, se você enviar variants, já cria os valores. Use para montar o cadastro de personalização (gravação, tamanho, cor da fita) a partir de um sistema externo.

POST/api/v1.0/optionsAdmin

Criar uma opção

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Corpo da requisição

product_idstringobrigatório
Id do produto (UUID).
option_namestring
Nome da opção.
option_typestringpadrão: S
SRCITF
Tipo: S lista, R rádio, C caixa de seleção, I texto de uma linha, T texto de várias linhas, F arquivo. Uma letra desconhecida vira S.
requiredstring
YN
Y torna a escolha obrigatória. Qualquer outro valor (ou omitir) deixa opcional.
positioninteger
Posição de exibição.
variantsobject
Valores iniciais. Aceita um objeto (as chaves são ignoradas) ou uma lista de objetos com variant_name, modifier_type (A ou P), modifier (string ou número) e position. Os campos weight_modifier* e sku_suffix não são lidos na criação.

Exemplo de requisição

bash
curl -X POST -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d", "option_name": "Tamanho", "option_type": "S", "required": "Y", "position": 1, "variants": [{"variant_name": "M", "modifier_type": "A", "modifier": "0.00", "position": 1}, {"variant_name": "G", "modifier_type": "A", "modifier": "5.00", "position": 2}]}' \
  "$BASE_URL/api/v1.0/options"

Resposta

201Opção criada
json
{
  "option_id": "5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10"
}

Campos da resposta

option_idstring
Id (UUID) da opção criada.

Erros

StatusQuandoCorpo
400Corpo que não é JSON válido, ou sem product_id{"error":"Invalid JSON"} / {"error":"product_id is required"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"insert option: ..."}
Guarde o id

A resposta traz só o option_id. Para obter os ids de cada valor, consulte a opção em seguida.

Alterar uma opção

Altera nome, tipo, obrigatoriedade ou posição de uma opção. Só o que você enviar muda. Os valores da opção não são alterados por esta rota.

PUT/api/v1.0/options/{id}Admin

Alterar uma opção

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

idstringobrigatório
Id da opção (UUID).

Corpo da requisição

option_namestring
Nome da opção.
option_typestringpadrão: S
SRCITF
Tipo: S lista, R rádio, C caixa de seleção, I texto de uma linha, T texto de várias linhas, F arquivo. Uma letra desconhecida vira S.
requiredstring
YN
Y torna a escolha obrigatória. Qualquer outro valor (ou omitir) deixa opcional.
positioninteger
Posição de exibição.

Exemplo de requisição

bash
curl -X PUT -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"option_name": "Tamanho da camisa", "required": "N"}' \
  "$BASE_URL/api/v1.0/options/5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10"

Resposta

200Opção alterada
json
{
  "option_id": "5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10"
}

Campos da resposta

option_idstring
Id da opção alterada.

Erros

StatusQuandoCorpo
400Corpo que não é JSON válido{"error":"Invalid JSON"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"..."}

Excluir uma opção

Remove a opção do produto. Quem já comprou com ela não é afetado, mas a opção deixa de aparecer em novas compras.

DELETE/api/v1.0/options/{id}Admin

Excluir uma opção

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

idstringobrigatório
Id da opção (UUID).

Exemplo de requisição

bash
curl -X DELETE -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/options/5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10"

Resposta

204Opção excluída, sem corpo
http
HTTP/1.1 204 No Content

Erros

StatusQuandoCorpo
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"option not found"}
Exclusão é definitiva

Não há como desfazer. Uma opção que não existe responde 500 com option not found, não 404.

Veja também

  • Opções do produto
  • Combinações
  • Exceções
Anterior
Variações (produtos filhos)
Próxima
Combinações de opções
Nesta página
  • Listar as opções de um produto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma opção
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar uma opção
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma opção
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir uma opção
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também