Variações (produtos filhos)
Lista os produtos filhos de um produto pai, cria um filho com SKU, preço e estoque próprios e atualiza os dados de cada filho.
Uma variação é um produto filho: um produto completo (com SKU, preço, estoque, imagens e página próprios) ligado a um produto pai. É o modelo certo quando cada tamanho ou cor precisa de controle de estoque e de código próprios, por exemplo porque o ERP trata cada combinação como um item.
Para entender quando usar variações em vez de opções ou variações unificadas, leia a visão geral. Antes de criar filhos, o pai precisa ter um grupo de variação com os eixos definidos (Grupo de variação). As ações de lote e de manutenção (gerar, vincular, sincronizar, desvincular, definir padrão) estão em Ações sobre variações.
Listar variações
/api/v1/admin/products/{id}/variationsAdminLista as variações filhas de um produto
Devolve todos os filhos, inclusive inativos, ordenados pela posição e pela data de criação. Preços em centavos.
Path parameters
iduuidobrigatórioExemplo de requisição
Resposta
Response fields
totalintegervariationsarrayvariations[].parent_product_iduuidvariations[].variation_group_iduuidvariations[].is_variationbooleantrue para filhos.variations[].feature_valuesobjectvariant_id é o valor cadastrado da característica (ausente em filhos criados por Criar variação); value é o texto.Erros
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 401 | Sem credenciais | {"error":"missing authorization header"} |
| 403 | Sem privilégio de ver o catálogo | {"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]} |
| 500 | Falha ao ler os filhos (por exemplo, id que não é UUID) | {"error":"failed to list variations","detail":"..."} |
Criar variação
/api/v1/admin/products/{id}/variationsAdminCria uma variação filha
Cria um filho copiando do pai descrição, categoria, custo, dimensões e status, e aplicando o que você enviar. O nome do filho é o do pai seguido dos valores (Camiseta - G) e o endereço (slug) ganha sufixo numérico se já existir. O filho entra no grupo de variação do pai. Se o pai não tem grupo, a resposta é erro.
Path parameters
iduuidobrigatórioCorpo da requisição
feature_valuesobjectobrigatório{"<id-do-Tamanho>": "G"}). Pelo menos um. O texto é procurado entre os valores cadastrados da característica; se achar, o filho fica filtrável por ela.skustringpriceintegerquantityintegerweightnumberExemplo de requisição
Resposta
Erros
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 400 | Corpo não é JSON | {"error":"invalid request body","detail":"..."} |
| 400 | feature_values vazio | {"error":"feature_values is required","detail":"provide at least one feature value"} |
| 500 | Pai sem grupo de variação | {"error":"failed to create variation","detail":"parent product has no variation group; create one first via SetVariationGroup"} |
| 500 | Pai é filho de outro, pai inexistente ou id inválido | {"error":"failed to create variation","detail":"cannot create variation from a child product"} |
| 401 / 403 | Sem login / sem privilégio de gerenciar o catálogo | veja Opções |
Atualizar variação
/api/v1/admin/products/{id}/variations/{varID}AdminAtualiza uma variação filha
Atualiza o filho como se fosse um produto comum: o corpo é o mesmo de Atualizar produto, e você envia só os campos que mudam. É o jeito de acertar preço, SKU e estoque de cada tamanho. Responde com o produto completo.
Path parameters
iduuidobrigatóriovarID é filho dele).varIDuuidobrigatórioCorpo da requisição
skustringpriceintegerquantitynumberstatusstringADHnamestringExemplo de requisição
Resposta
Erros
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 400 | Corpo não é JSON | {"error":"invalid request body","detail":"..."} |
| 4xx | Regras de atualização de produto, como campos travados de produto ligado a um master | o mesmo corpo de Atualizar produto |
| 500 | Falha ao gravar | {"error":"failed to update variation","detail":"..."} |
| 401 / 403 | Sem login / sem privilégio | veja Opções |