Combinações de opções

As opções de um produto podem ser agrupadas em combinações de opções. Isso é útil para controlar produtos com vários atributos personalizáveis. Por exemplo, roupas vêm em várias cores e tamanhos, e é conveniente controlar separadamente quantas camisetas azuis G e quantas camisetas brancas M você tem. As combinações também permitem atribuir SKUs, preços e imagens exclusivos a cada combinação específica.

Esta seção documenta a API de combinações da REST API da Venddor. Ela usa as mesmas credenciais HTTP Basic do restante da API ($EMAIL:$API_KEY) e o endereço base da sua loja ($BASE_URL). Dois estilos de URL são descritos: API 2.0 (/api/2.0/products/{product_id}/options/combinations) e API 1.0 (/api/combinations).

Como funciona

Antes de criar combinações, planeje quais opções precisam de controle de estoque e marque Estoque (inventory=Y) nelas. Depois crie uma combinação para cada par (ou trio...) de variantes que você quer vender e mantenha o amount atualizado.

1. Leia as opções do produto
   Obtenha os IDs de opção e de variante do produto, veja Opções do produto.
2. Crie as combinações
   Envie o objeto combination com os pares de ID de opção e ID de variante. A API 2.0 também aceita várias combinações de uma vez.
3. Complete cada combinação
   Use um PUT para definir o product_code e as imagens, que o POST em /api/combinations não aceita.
4. Mantenha o estoque atualizado
   Atualize o amount com frequência para evitar vender além do estoque.

Conceitos principais

Estrutura da combinação

Este é o objeto de combinação como a referência da API 2.0 o mostra. Os comentários fazem parte do exemplo original.

{
  "combination_id": "251",
  "product_id": "423",
  "product_code": "TSHIRT-BL-XL",
  "combination_hash": "16_42_17_53",  // format: option_id_variant_id_option_id_variant_id
  "combination": {
    "16": "42",  // option_id: variant_id (Color: Black)
    "17": "53"   // option_id: variant_id (Size: XL)
  },
  "amount": "25",
  "position": 10,
  "image_pairs": {
    "pair_id": "156",
    "image_id": "421",
    "detailed_id": "422",
    "position": "0",
    "detailed": {
      "object_id": "421",
      "object_type": "product_option",
      "image_path": "/var/www/html/images/detailed/422/black_xl_tshirt.jpg",
      "alt": "",
      "image_x": "800",
      "image_y": "800",
      "http_image_path": "https://www.venddor.com.br/images/detailed/422/black_xl_tshirt.jpg",
      "https_image_path": "https://www.venddor.com.br/images/detailed/422/black_xl_tshirt.jpg",
      "absolute_path": "/var/www/html/images/detailed/422/black_xl_tshirt.jpg",
      "relative_path": "images/detailed/422/black_xl_tshirt.jpg"
    }
  }
}

Campos principais

• product_code: um SKU/código de produto exclusivo para esta combinação específica.
• combination_hash: uma string gerada pelo sistema que identifica de forma única a combinação de variantes de opções.
• combination: um objeto que mapeia IDs de opção para IDs de variante.
• amount: a quantidade em estoque disponível para esta combinação específica.
• position: a ordem de exibição desta combinação nas listas.
• image_pairs: imagens específicas desta combinação de opções.

A lista completa de campos está em Detalhes da combinação.

Casos de uso

• Controle de estoque. Cada combinação pode ter o seu próprio nível de estoque, o que permite um controle preciso em produtos com várias variantes.
• Preços personalizados. Combinações diferentes podem ter preços diferentes. Por exemplo, tamanhos maiores podem custar mais, ou cores premium podem ter um acréscimo.
• Imagens por combinação. Cada combinação pode ter a sua imagem, mostrando ao cliente exatamente o que ele vai receber ao escolher determinadas opções.
• SKUs personalizados. Códigos de produto exclusivos por combinação tornam a gestão do armazém e o atendimento dos pedidos mais eficientes.

Endpoints

Estilo API 1.0

Estilo API 2.0

Criando uma combinação com a API 2.0

Exemplo de requisição

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/products/423/options/combinations" \
  -H "Content-Type: application/json" \
  -d '{
  "product_code": "TSHIRT-RED-M",
  "combination": {
    "16": "44",
    "17": "52"
  },
  "amount": "15",
  "position": 20
}'

No exemplo original as variantes são anotadas: "16": "44" é Cor: Vermelho e "17": "52" é Tamanho: M.

Operações em lote

Para produtos com muitas combinações, pode ser mais eficiente usar operações em lote.

Exemplo de requisição

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/products/423/options/combinations/batch" \
  -H "Content-Type: application/json" \
  -d '{
  "combinations": [
    {
      "product_code": "TSHIRT-RED-S",
      "combination": {
        "16": "44",
        "17": "51"
      },
      "amount": "10",
      "position": 30
    },
    {
      "product_code": "TSHIRT-RED-L",
      "combination": {
        "16": "44",
        "17": "53"
      },
      "amount": "12",
      "position": 40
    }
  ]
}'

O exemplo original anota as variantes: "44" é Vermelho, "51" é P e "53" é G.

Boas práticas

• Planeje a estrutura das opções. Antes de criar combinações, planeje com cuidado quais opções precisarão de controle de estoque.
• Use operações em lote. Para produtos com muitas combinações, crie todas de uma vez.
• Mantenha a consistência. Use nomes e códigos consistentes em todos os produtos.
• Inclua imagens. Sempre que possível, informe imagens específicas por combinação para melhorar a experiência do cliente.
• Atualize com regularidade. Mantenha os níveis de estoque das combinações atualizados para evitar vender além do disponível.

Erros comuns

• Usar em uma combinação uma opção sem inventory=Y. A API retorna um erro.
• Tentar enviar product_code ou image_pairs no POST em /api/combinations. Eles só podem ser definidos depois, com um PUT.
• Tentar alterar a combination com um PUT. Exclua a combinação e crie outra.
• Chamar o DELETE sem o parâmetro de consulta product_id. Veja Excluir uma combinação.

Próximos passos