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, variações, preços por quantidade e produtos obrigatórios de um produto do seller, e quando usar cada um.

Um mesmo produto pode ser vendido em várias versões (cor, tamanho, voltagem) e com preço que cai conforme a quantidade. Esta seção reúne as quatro ferramentas para isso: opções de compra, variações, escalas de preço e produtos obrigatórios. Todas operam sobre um produto do seu seller, em /api/v1/vendor/products/{id}/....

Pontos principais
  • Opção e variação resolvem coisas diferentes: a opção é uma escolha dentro de um produto (tamanho que muda o preço, texto de gravação); a variação é outro produto (filho) com SKU, estoque e preço próprios.
  • Dinheiro é inteiro em centavos; ajustes percentuais usam pontos-base (1000 = 10%).
  • Todas as rotas exigem token de seller com privilégio de catálogo, como em Produtos do seller.
  • Só o produto do caminho é conferido: ids de opção e de valor devem ser os que você acabou de ler daquele mesmo produto.
  • Estas rotas têm lacunas de validação (veja "Erros comuns"). Trate 500 com detail como erro de dados, não da plataforma.

Como funciona

FerramentaQuando usarEstoque e SKU
Opção de compraEscolha dentro do produto: camiseta P/M/G com o mesmo estoque, gravação personalizada, embrulho.Do produto. O valor só soma um sufixo ao SKU.
VariaçãoVersões realmente diferentes: cada cor/tamanho tem estoque e SKU próprios.De cada variação (produto filho).
Escala de preçoPreço menor a partir de certa quantidade ou para um grupo de clientes.Não muda.
Produto obrigatórioAo comprar este produto, o cliente também leva (ou é sugerido a levar) outro.Cada produto tem o seu.

O fluxo das variações tem três passos, sempre nesta ordem:

  1. Defina os eixos

    Chame Definir eixos com as características que diferenciam as versões (por exemplo Cor e Tamanho). Isso cria o grupo de variação do produto pai.

  2. Crie as variações

    Uma a uma em Variações, ou todas as combinações de uma vez com generate.

  3. Ajuste cada filha

    As filhas nascem copiando o pai. Corrija SKU, estoque e preço de cada uma; depois use sync quando mudar descrição ou categoria do pai.

Conceitos importantes

Produto pai e filhas

O pai é o produto que o cliente vê agrupando as versões. Cada variação é um produto de verdade (com parent_product_id), que também aparece na listagem de produtos com is_variation: true. Uma variação não pode ter filhas.

Preços por quantidade

Uma escala diz "a partir de N unidades o preço unitário é X". O preço cobrado nunca passa do preço base do produto, e se mais de uma escala se aplica, vale a de menor preço efetivo (regra padrão da loja).

Endpoints

MétodoCaminhoPara que serve
GET/api/v1/vendor/products/{id}/optionsLista as opções de compra.
POST/api/v1/vendor/products/{id}/optionsCria uma opção.
PUT/api/v1/vendor/products/{id}/options/{optionId}Altera uma opção.
DELETE/api/v1/vendor/products/{id}/options/{optionId}Exclui uma opção e seus valores.
GET/api/v1/vendor/products/{id}/options/{optionId}/variantsLista os valores de uma opção.
POST/api/v1/vendor/products/{id}/options/{optionId}/variantsCria um valor.
PUT/api/v1/vendor/products/{id}/options/{optionId}/variants/{variantId}Altera um valor.
DELETE/api/v1/vendor/products/{id}/options/{optionId}/variants/{variantId}Exclui um valor.
GET/api/v1/vendor/products/{id}/variationsLista as variações (produtos filhos).
POST/api/v1/vendor/products/{id}/variationsCria uma variação.
PUT/api/v1/vendor/products/{id}/variations/{varID}Altera uma variação.
DELETE/api/v1/vendor/products/{id}/variations/{varID}Desvincula uma variação.
GET/api/v1/vendor/products/{id}/variation-groupLê os eixos de variação.
PUT/api/v1/vendor/products/{id}/variation-group-featuresDefine os eixos de variação.
POST/api/v1/vendor/products/{id}/variations/generateGera variações por combinação.
POST/api/v1/vendor/products/{id}/variations/syncCopia dados do pai para as variações.
GET/api/v1/vendor/products/{id}/price-tiersLê as escalas de preço por quantidade.
POST/api/v1/vendor/products/{id}/price-tiersCria ou atualiza uma escala.
PUT/api/v1/vendor/products/{id}/price-tiersSubstitui todas as escalas.
GET/api/v1/vendor/products/{id}/required-productsLista os produtos obrigatórios.
POST/api/v1/vendor/products/{id}/required-productsAdiciona um produto obrigatório.
PUT/api/v1/vendor/products/{id}/required-productsSubstitui a lista de obrigatórios.
DELETE/api/v1/vendor/products/{id}/required-products/{requiredId}Remove um obrigatório.

Erros comuns

  1. Criar variação antes dos eixos. Volta 500 com "parent product has no variation group". Defina os eixos primeiro.
  2. Esperar que DELETE .../variations/{id} apague a filha. Ele só desvincula: a filha vira um produto comum. Para apagar de vez, use Excluir produto nela.
  3. Gerar variações e esquecer o estoque. As filhas geradas nascem com estoque 0 e SKU vazio.
  4. Trocar PUT .../price-tiers por POST. O PUT substitui todas as escalas; o POST cria ou atualiza uma só.
  5. Mandar um optionId de outra opção. A plataforma não confere se a opção é do produto do caminho. Use só ids lidos do mesmo produto.
  6. Reutilizar o mesmo par lower_limit/grupo. O POST de escala faz upsert: sobrescreve a escala existente em vez de dar erro.
  7. Esquecer que percentage_discount manda. Em uma escala com percentage_discount maior que zero, o price é ignorado no cálculo do carrinho.

Próximos passos

Eixos e geração
Monte um grupo de variação do zero.
Opções de compra
Tamanho, cor, texto livre e arquivo.
Preço por quantidade
Atacado e preços por grupo.
Anterior
Assinatura e compra programada
Próxima
Opções de compra
Nesta página
  • Como funciona
  • Conceitos importantes
  • Produto pai e filhas
  • Preços por quantidade
  • Endpoints
  • Erros comuns
  • Próximos passos