API atual/Referência completa/Variações e opções

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

GET/api/v1/admin/products/{id}/variationsAdmin

Lista 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ório

Id do produto pai.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Um filho, resumido

json

{
  "total": 3,
  "variations": [
    {
      "id": "c1101af4-512b-4775-a467-787135f57b7c",
      "name": "ZZ Var Camiseta Pai - P",
      "slug": "zz-var-camiseta-pai-p",
      "sku": "ZZVAR-PAI-P",
      "price": 4590,
      "quantity": 12,
      "track_inventory": true,
      "status": "A",
      "parent_product_id": "3cbd86fd-0e6c-404f-8264-c99438a28ce0",
      "variation_group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
      "is_variation": true,
      "feature_values": {
        "a827c238-e0ce-4ff3-9655-478b5e3adf1b": {
          "variant_id": "68399e61-4bf1-4762-b6d8-912c026a496a",
          "value": "P"
        }
      }
    }
  ]
}

Response fields

totalinteger

Quantidade de filhos.

variationsarray

Filhos. Cada item é um produto completo (os campos estão em Consultar produto).

variations[].parent_product_iduuid

Id do pai.

variations[].variation_group_iduuid

Grupo de variação compartilhado com o pai.

variations[].is_variationboolean

true para filhos.

variations[].feature_valuesobject

Valor do filho em cada eixo, indexado pelo id da característica. variant_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

POST/api/v1/admin/products/{id}/variationsAdmin

Cria 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ório

Id do produto pai. Não pode ser ele mesmo um filho.

Corpo da requisição

feature_valuesobjectobrigatório

Valor do filho em cada eixo: o id da característica como chave e o texto do valor como valor ({"<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.

skustring

SKU do filho. Se omitido, fica vazio.

priceinteger

Preço do filho em centavos. Se omitido, usa o do pai.

quantityinteger

Estoque do filho. Se omitido, usa o do pai.

weightnumber

Peso do filho. Se omitido, usa o do pai.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"feature_values":{"a827c238-e0ce-4ff3-9655-478b5e3adf1b":"G"},"sku":"CAM-G","price":5490,"quantity":7}'

Resposta

201Filho criado (resumido)

json

{
  "id": "c6587447-9ee7-4a1b-a62b-6dfe55a066f1",
  "name": "ZZ Var Camiseta Pai - G",
  "slug": "zz-var-camiseta-pai-g",
  "sku": "ZZVAR-PAI-G",
  "price": 5490,
  "quantity": 7,
  "status": "A",
  "parent_product_id": "3cbd86fd-0e6c-404f-8264-c99438a28ce0",
  "variation_group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
  "is_variation": true,
  "feature_values": {
    "a827c238-e0ce-4ff3-9655-478b5e3adf1b": { "value": "G" }
  }
}

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

PUT/api/v1/admin/products/{id}/variations/{varID}Admin

Atualiza 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ório

Id do produto pai (informativo: a rota não confere se varID é filho dele).

varIDuuidobrigatório

Id do produto filho.

Corpo da requisição

skustring

SKU do filho.

priceinteger

Preço em centavos.

quantitynumber

Estoque.

statusstring

ADH

Status do filho.

namestring

Nome do filho. Os demais campos de produto também são aceitos (veja Atualizar produto).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations/$CHILD_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sku":"CAM-P","price":4590,"quantity":12}'

Resposta

200Filho atualizado (resumido)

json

{
  "id": "c1101af4-512b-4775-a467-787135f57b7c",
  "name": "ZZ Var Camiseta Pai - P",
  "sku": "CAM-P",
  "price": 4590,
  "quantity": 12,
  "status": "A",
  "parent_product_id": "3cbd86fd-0e6c-404f-8264-c99438a28ce0",
  "is_variation": true
}

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

Veja também

API atual/Referência completa/Variações e opções

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.

Listar variações

GET/api/v1/admin/products/{id}/variationsAdmin

Lista 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ório

Id do produto pai.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Um filho, resumido

json

{
  "total": 3,
  "variations": [
    {
      "id": "c1101af4-512b-4775-a467-787135f57b7c",
      "name": "ZZ Var Camiseta Pai - P",
      "slug": "zz-var-camiseta-pai-p",
      "sku": "ZZVAR-PAI-P",
      "price": 4590,
      "quantity": 12,
      "track_inventory": true,
      "status": "A",
      "parent_product_id": "3cbd86fd-0e6c-404f-8264-c99438a28ce0",
      "variation_group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
      "is_variation": true,
      "feature_values": {
        "a827c238-e0ce-4ff3-9655-478b5e3adf1b": {
          "variant_id": "68399e61-4bf1-4762-b6d8-912c026a496a",
          "value": "P"
        }
      }
    }
  ]
}

Response fields

totalinteger

Quantidade de filhos.

variationsarray

Filhos. Cada item é um produto completo (os campos estão em Consultar produto).

variations[].parent_product_iduuid

Id do pai.

variations[].variation_group_iduuid

Grupo de variação compartilhado com o pai.

variations[].is_variationboolean

true para filhos.

variations[].feature_valuesobject

Valor do filho em cada eixo, indexado pelo id da característica. variant_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

POST/api/v1/admin/products/{id}/variationsAdmin

Cria uma variação filha

Path parameters

iduuidobrigatório

Id do produto pai. Não pode ser ele mesmo um filho.

Corpo da requisição

feature_valuesobjectobrigatório

skustring

SKU do filho. Se omitido, fica vazio.

priceinteger

Preço do filho em centavos. Se omitido, usa o do pai.

quantityinteger

Estoque do filho. Se omitido, usa o do pai.

weightnumber

Peso do filho. Se omitido, usa o do pai.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"feature_values":{"a827c238-e0ce-4ff3-9655-478b5e3adf1b":"G"},"sku":"CAM-G","price":5490,"quantity":7}'

Resposta

201Filho criado (resumido)

json

{
  "id": "c6587447-9ee7-4a1b-a62b-6dfe55a066f1",
  "name": "ZZ Var Camiseta Pai - G",
  "slug": "zz-var-camiseta-pai-g",
  "sku": "ZZVAR-PAI-G",
  "price": 5490,
  "quantity": 7,
  "status": "A",
  "parent_product_id": "3cbd86fd-0e6c-404f-8264-c99438a28ce0",
  "variation_group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
  "is_variation": true,
  "feature_values": {
    "a827c238-e0ce-4ff3-9655-478b5e3adf1b": { "value": "G" }
  }
}

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

PUT/api/v1/admin/products/{id}/variations/{varID}Admin

Atualiza uma variação filha

Path parameters

iduuidobrigatório

Id do produto pai (informativo: a rota não confere se varID é filho dele).

varIDuuidobrigatório

Id do produto filho.

Corpo da requisição

skustring

SKU do filho.

priceinteger

Preço em centavos.

quantitynumber

Estoque.

statusstring

ADH

Status do filho.

namestring

Nome do filho. Os demais campos de produto também são aceitos (veja Atualizar produto).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations/$CHILD_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sku":"CAM-P","price":4590,"quantity":12}'

Resposta

200Filho atualizado (resumido)

json

{
  "id": "c1101af4-512b-4775-a467-787135f57b7c",
  "name": "ZZ Var Camiseta Pai - P",
  "sku": "CAM-P",
  "price": 4590,
  "quantity": 12,
  "status": "A",
  "parent_product_id": "3cbd86fd-0e6c-404f-8264-c99438a28ce0",
  "is_variation": true
}

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