Variações e opções
Como a Venddor modela produtos com tamanho, cor e personalização, o que a API legada permite ler e o mapa das rotas.
Muitos produtos não são uma coisa só: a camiseta vem em P, M e G, a caneca aceita uma gravação, o tênis tem numeração e cor. A Venddor tem modelos para isso, e entender cada um evita erro de leitura. Esta seção documenta o que a API legada, compatível com a Venddor 1.0 (/api/v1.0/...), oferece: a consulta das opções de um produto e dos seus produtos filhos.
Como funciona
Qual modelo usar
| Você quer... | Use | Por quê |
|---|---|---|
| Ler o detalhe que o cliente escolhe no carrinho (gravação, cor da fita, sabor) sem estoque por escolha | Opções | A escolha viaja no item do carrinho. O estoque é um só, o do produto. |
| Ler cada tamanho/cor com estoque, código, preço e fotos próprios, aparecendo como produto na busca, em feeds e em ERPs | Variações | Cada filho é um produto completo. Convém quando o ERP já tem um código por combinação. |
Regra prática: se o estoque muda por combinação, a combinação é um filho (variação). Se só o detalhe muda, é uma opção.
Como ligam com as características
Característica (feature) é um atributo do catálogo, como Tamanho, Cor ou Material, com uma lista de valores (PP, P, M, G...). A leitura delas está em Características e conteúdo do produto.
- Variações (produtos filhos): o grupo de variação do pai diz quais características são os eixos (por exemplo Tamanho). Cada filho guarda o valor que tem em cada eixo (Tamanho = M), em
product_features. - Opções: não usam características. São criadas por produto.
Conceitos-chave
Pai, filho e grupo
O pai é o produto que agrupa; os filhos são produtos comuns com um campo que aponta para o pai. Um filho não pode ter filhos. Para ler os filhos de um pai, use Variações.
Status e visibilidade dos filhos
As listagens administrativas devolvem todos os filhos, inclusive inativos. A vitrine mostra só os ativos. Status segue as letras do catálogo (Produtos).
Dinheiro nas opções e variações
| Onde | Campo | Unidade |
|---|---|---|
| Valor de opção | modifier | string decimal ("5.00"); com modifier_type P é o percentual ("10.00" = 10%) |
| Variação filha | price | string decimal ("49.90") |
Ids
Ids de produto, opção e valor de opção são UUID em /api/v1.0/.... Na rota /api/products/... (sem v1.0), a API devolve os ids como números decimais em string, no estilo da Venddor 1.0.
Permissões
As rotas desta seção exigem um administrador (HTTP Basic com e-mail:chave_de_api, ou Authorization: Bearer <JWT>). Sem credenciais a resposta é 401.
Endpoints
| Método | Caminho | Para quê | Página |
|---|---|---|---|
| GET | /api/v1.0/products/{id}/options | Opções do produto | Opções |
| GET | /api/v1.0/products/{id}/variations | Filhos do produto | Variações |
| POST | /api/v1.0/product_variations | Criar grupo de variação (não implementado) | Criar grupo de variações |
| GET, POST, PUT, DELETE | /api/v1.0/options, /api/v1.0/options/{id} | Manutenção das opções do produto | Cadastro de opções |
| GET, POST, PUT, DELETE | /api/v1.0/combinations, /api/v1.0/combinations/{hash} | Estoque por combinação de opções | Combinações |
| GET, POST, DELETE | /api/v1.0/exceptions, /api/v1.0/exceptions/{id} | Combinações de opções proibidas | Exceções |
As rotas de leitura de produto, como /api/v1.0/products/{id}/options, também respondem sem a versão (/api/products/{id}/options). As rotas de manutenção deste quadro existem apenas sob /api/v1.0.
Erros comuns
- Esperar estoque por valor de opção. Valores de opção não têm estoque. Se precisa de estoque por tamanho, use variações.
- Achar que esta API cria variações. Ela não cria grupos de variação, só lê os filhos.
POST /api/v1.0/product_variationsresponde 501. - Usar o código do produto no caminho. O
{id}é o UUID do produto pai. Um valor que não é UUID devolve 500. - Esperar 404 para um produto sem opções ou sem filhos. A resposta é 200 com lista vazia.