Opções do produto

Os produtos podem ter opções: propriedades adicionais que os clientes podem escolher ao comprar um produto. Em roupas, por exemplo, seriam cor, tamanho ou acessórios opcionais. As opções permitem oferecer variações e personalizações do produto sem criar cadastros de produto separados.

Esta seção tem dois grupos de URLs. As URLs da API 2.0 trabalham nas opções de um produto (/api/2.0/products/{product_id}/options) e são descritas nesta página. As URLs da API 1.0 trabalham nas próprias opções (/api/options) e têm uma página cada: listar, consultar, criar, atualizar e excluir. As credenciais são as do HTTP Basic do administrador ($EMAIL e $API_KEY).

Como funciona

Tipos de opção

Estrutura de uma opção

A estrutura de uma opção, como a referência a mostra. O texto depois de // é a explicação da referência para o código.

{
  "option_id": "16",
  "product_id": "423",
  "option_name": "Color",
  "option_type": "S",
  "position": 10,
  "required": "Y",
  "comment": "Please select your preferred color",
  "inventory": "Y",
  "variants": [
    {
      "variant_id": "42",
      "variant_name": "Black",
      "position": 10,
      "modifier_type": "A", // A - absolute, P - percentage
      "modifier": "0.00",
      "weight_modifier": "0.00",
      "status": "A"
    },
    {
      "variant_id": "43",
      "variant_name": "White",
      "position": 20,
      "modifier_type": "A",
      "modifier": "0.00",
      "weight_modifier": "0.00",
      "status": "A"
    },
    {
      "variant_id": "44",
      "variant_name": "Red",
      "position": 30,
      "modifier_type": "A",
      "modifier": "5.00",
      "weight_modifier": "0.00",
      "status": "A"
    }
  ]
}

Conceitos principais

Campos da opção

• option_type: define como a opção é exibida aos clientes (veja a tabela acima).
• required: indica se o cliente precisa escolher esta opção antes de adicionar o produto ao carrinho (Y ou N).
• inventory: indica se esta opção afeta o controle de estoque (Y ou N).
• comment: texto de apoio exibido ao cliente para ajudar na escolha.

Campos da variante

• modifier_type: como o preço muda com esta variante. A é absoluto (soma ou subtrai um valor fixo) e P é percentual (soma ou subtrai uma porcentagem do preço base).
• modifier: o valor que altera o preço do produto. Pode ser positivo ou negativo.
• weight_modifier: o valor que altera o peso do produto. Pode ser positivo ou negativo.
• status: indica se a variante está ativa (A) ou desativada (D).

Endpoints da API

Exemplo: criar uma opção de tamanho

POST /api/2.0/products/423/options com o corpo abaixo cria uma opção "Size" com quatro variantes para o produto 423.

curl -X POST "$BASE_URL/api/2.0/products/423/options" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "option_name": "Size",
  "option_type": "S",
  "position": 20,
  "required": "Y",
  "comment": "Please select your size",
  "inventory": "Y",
  "variants": [
    {
      "variant_name": "Small",
      "position": 10,
      "modifier_type": "A",
      "modifier": "0.00",
      "weight_modifier": "-0.20",
      "status": "A"
    },
    {
      "variant_name": "Medium",
      "position": 20,
      "modifier_type": "A",
      "modifier": "0.00",
      "weight_modifier": "0.00",
      "status": "A"
    },
    {
      "variant_name": "Large",
      "position": 30,
      "modifier_type": "A",
      "modifier": "2.00",
      "weight_modifier": "0.30",
      "status": "A"
    },
    {
      "variant_name": "Extra Large",
      "position": 40,
      "modifier_type": "A",
      "modifier": "5.00",
      "weight_modifier": "0.50",
      "status": "A"
    }
  ]
}'

Trabalhando com combinações de opções

Quando há várias opções com controle de estoque ativado, é preciso gerenciar o estoque de combinações específicas de opções. Por exemplo, você pode ter 10 camisas "Azul" e "P", mas só 5 camisas "Vermelha" e "G".

As combinações de opções são gerenciadas por um endpoint separado, /api/2.0/products/{product_id}/options/combinations: o GET retorna todas as combinações de opções de um produto e o POST cria uma nova combinação com dados de estoque. Elas estão documentadas em Combinações de opções.

Endpoints

Erros comuns e boas práticas

• Não exija opções demais: muitas escolhas obrigatórias podem complicar o processo de compra.
• Use nomes de opção claros, descritivos e fáceis de entender.
• Use o campo comment para orientar o cliente nas escolhas.
• Defina valores de position para que as opções apareçam em uma sequência lógica.
• Aplique modificadores de preço que façam sentido para as variantes (por exemplo, materiais premium custam mais).
• Mantenha a estrutura das opções consistente entre produtos semelhantes, para oferecer uma experiência de compra uniforme.

Próximos passos