Variações e opções

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 três modelos para isso, e escolher o certo logo no começo evita retrabalho. Esta seção documenta as rotas de administração (/api/v1/admin/products/{id}/...) que criam e mantêm cada um deles.

Como funciona

Qual modelo usar

Regra prática: se o estoque muda por combinação, use variações ou variações unificadas. Se só o detalhe muda, use opções.

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...). O cadastro 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). Veja Grupo de variação.
• Variações unificadas: não usam o cadastro de características. Os eixos e valores são texto livre dentro do próprio produto ("Cor": ["Azul","Preto"]).
• Opções: não usam características. São criadas por produto.

Fluxo típico de variações (produtos filhos)

1. Crie o produto pai

   Use Criar produto. O pai é o produto "genérico" que o cliente vê primeiro. Ele não pode ser filho de outro produto.

2. Defina os eixos

   Chame Definir eixos pelas características com as características que distinguem os filhos. Isso cria o grupo de variação do pai.

3. Gere ou crie os filhos

   Gerar variações cria vários filhos de uma vez a partir de combinações de valores; Criar variação cria um com SKU, preço e estoque. Para aproveitar um produto que já existe, use Vincular variação.

4. Ajuste cada filho

   Atualizar variação altera preço, SKU e estoque do filho. Definir variação padrão escolhe qual filho aparece primeiro.

5. Propague o conteúdo do pai

   Sincronizar dados copia descrição e categorias do pai para todos os filhos.

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. O grupo de variação é o identificador compartilhado por pai e filhos, e é ele que carrega a lista de eixos. Na leitura de um produto (veja Consultar produto), o filho vem com parent_product_id, variation_group_id e is_variation: true.

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

Ids

Ids de produto, opção, valor de opção, exceção e grupo de variação são UUID. Ids de variação unificada e de grupo unificado são inteiros.

Permissões

Todas as rotas desta seção exigem login de administrador (Authorization: Bearer <JWT>). Para ler basta o privilégio de visualizar o catálogo; para escrever (POST, PUT, DELETE) é preciso o privilégio de gerenciar o catálogo. Sem eles a resposta é 403: {"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]} na leitura e {"error":"insufficient privileges","required":"manage_catalog"} na escrita.

Endpoints

Editar e excluir uma linha de variação unificada (PUT e DELETE /api/v1/admin/unified-variations/{id}), excluir uma regra de exceção (DELETE /api/v1/admin/option-exceptions/{id}) e ler um grupo pelo id dele (GET /api/v1/admin/variation-groups/{id}) fazem parte da referência completa do administrador.

Erros comuns

• Gerar variações antes de criar o grupo. generate e POST variations respondem 500 com "parent product has no variation group; create one first". Defina os eixos primeiro (Grupo de variação).
• 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.
• Mandar price_modifier em reais. É centavos (ou pontos-base, se percentage). 5 é R$ 0,05.
• Usar o id de uma variação unificada como UUID. É um inteiro.
• Criar um filho de um filho. Um produto que já é filho não pode ser pai: a API recusa.
• Redefinir eixos de um grupo com filhos ativos sem conferir. Os eixos são trocados; os valores já gravados nos filhos continuam, mas podem deixar de corresponder aos novos eixos.

Próximos passos