Exceções de opções

Você pode usar exceções para definir combinações específicas de opções de produto que o cliente não conseguirá selecionar. Por exemplo, se você vende uma camiseta em várias cores e tamanhos, pode tornar uma determinada cor indisponível para um tamanho específico.

As exceções são parecidas com as combinações de opções: as duas incluem o objeto combination com variantes de opções diferentes. Esta seção documenta a API de exceções da REST API da Venddor, em dois estilos de URL: API 2.0 (/api/2.0/products/{product_id}/exceptions) e API 1.0 (/api/exceptions). As requisições usam as credenciais HTTP Basic ($EMAIL:$API_KEY) e o endereço base da sua loja ($BASE_URL).

Como funciona

1. Escolha o tipo de exceção
   Defina o exceptions_type do produto como F (proibida) ou A (permitida).
2. Crie as exceções
   Envie um objeto combination com IDs de opção e IDs de variante. Use -1 e -2 para "qualquer variante" e "nenhuma variante".
3. Trate isso na loja
   Garanta que o seu frontend desabilite ou oculte variantes de opções conforme a seleção atual do cliente, para que ele não consiga escolher combinações inválidas.

Conceitos principais

Tipos de exceção

• Proibida: o cliente não conseguirá selecionar as combinações de variantes de opções informadas no objeto combination.
• Permitida: o cliente poderá selecionar SOMENTE as combinações de variantes de opções informadas no objeto combination.

O tipo da exceção é determinado pelo produto ao qual ela está associada. Um produto tem um campo chamado exceptions_type, que pode ter o valor A (permitida) ou F (proibida).

Estrutura da exceção

{
  "exception_id": "42",
  "product_id": "423",
  "combination": {
    "16": "43",  // option_id: variant_id (Color: White)
    "17": "52"   // option_id: variant_id (Size: XL)
  }
}

Neste exemplo, se o exceptions_type do produto for:

• F (proibida): o cliente não conseguirá selecionar a cor "Branco" no tamanho "XL".
• A (permitida): o cliente só conseguirá selecionar a cor "Branco" no tamanho "XL", e nenhuma outra combinação.

Quando usar cada tipo

Use exceções proibidas (exceptions_type="F") quando a maioria das combinações é válida e você só precisa excluir algumas específicas. Casos de uso comuns:

• Certas combinações de cor e tamanho que não são fabricadas.
• Combinações de opções temporariamente fora de estoque.
• Combinações de características incompatíveis.

Use exceções permitidas (exceptions_type="A") quando só algumas combinações específicas são válidas e a maioria deve ficar indisponível. Casos de uso comuns:

• Produtos com restrições rígidas de fabricação.
• Produtos em que só certas combinações fazem sentido.
• Lançamento de um produto novo com poucas combinações de opções no início.

Endpoints

Estilo API 1.0

Estilo API 2.0

Criando uma combinação proibida com a API 2.0

O exemplo original define primeiro o tipo do produto e depois cria a exceção. Os comentários fazem parte do exemplo original.

// First, set the exceptions_type for the product (if needed)
PUT /api/2.0/products/423

{
  "exceptions_type": "F"  // F - forbidden, A - allowed
}

// Then create the exception
POST /api/2.0/products/423/exceptions

{
  "combination": {
    "16": "43",  // Color: White
    "17": "52"   // Size: XL
  }
}

Exemplo de requisição

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/products/423/exceptions" \
  -H "Content-Type: application/json" \
  -d '{
  "combination": {
    "16": "43",
    "17": "52"
  }
}'

Boas práticas

• Use com moderação. Exceções demais deixam o gerenciamento do produto complexo.
• Mantenha atualizado. Revise as exceções com regularidade, conforme o estoque e a capacidade de fabricação mudam.
• Comunique com clareza. Garanta que as descrições do produto expliquem por que certas combinações estão indisponíveis.
• Escolha o tipo certo. Escolha exceções "proibidas" ou "permitidas" conforme a que exigir gerenciar menos combinações.

Erros comuns

• Usar uma opção de um tipo que não tem variantes. Só opções Checkbox, Select box e Radiogroup podem fazer parte de uma exceção.
• Esquecer que o tipo vem do produto. A mesma combination é proibida com exceptions_type="F" e é a única permitida com exceptions_type="A".
• Atualizar uma exceção com uma combination parcial. As opções não incluídas na requisição são removidas da exceção, veja Atualizar uma exceção.
• Chamar o DELETE sem o parâmetro de consulta product_id, veja Excluir uma exceção.

Próximos passos