API atual/Guia rápido/Variações e opções

Ações sobre variações

Gera filhos em lote, vincula um produto existente como filho, copia dados do pai, desvincula um filho e define a variação padrão.

Estas operações cuidam do ciclo de vida dos produtos filhos de um pai. Todas partem do mesmo princípio: o pai precisa ter um grupo de variação com os eixos definidos. Para listar, criar um filho e alterar preço e estoque, veja Variações.

Todas exigem o privilégio de gerenciar o catálogo.

Gerar variações

POST/api/v1/admin/products/{id}/variations/generateAdmin

Gera variações filhas em lote

Cria vários filhos de uma vez, um por combinação enviada. Cada filho copia do pai preço, custo, dimensões, descrição e status, mas nasce sem SKU e com estoque 0: preencha-os depois com Atualizar variação. O nome é o do pai mais os valores (Camiseta - P). Uma combinação que já existe é pulada. A operação é única: se uma combinação falha, nenhum filho é criado.

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

combinationsarrayobrigatório

Lista de combinações, uma por filho a criar. Pelo menos uma.

(item)object

Objeto cujas chaves são ids de característica (os eixos do grupo) e cujos valores são ids do valor cadastrado dessa característica: {"<id-Tamanho>": "<id-do-valor-M>"}. Com duas características, o objeto tem duas chaves.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"combinations":[
        {"a827c238-e0ce-4ff3-9655-478b5e3adf1b":"68399e61-4bf1-4762-b6d8-912c026a496a"},
        {"a827c238-e0ce-4ff3-9655-478b5e3adf1b":"177db45a-f708-4564-af8f-604b3053c5a1"}
      ]}'

Resposta

201Filhos criados (um item, resumido)

json

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

Response fields

countinteger

Filhos criados nesta chamada (combinações que já existiam não entram).

variationsarray

Os filhos criados, no formato de produto.

Erros

Status	Quando	Exemplo de corpo
400	`combinations` vazio ou ausente	`{"error":"combinations is required","detail":"provide at least one combination"}`
500	Pai sem grupo de variação	`{"error":"failed to generate variations","detail":"parent product has no variation group; create one first"}`
500	Pai é filho de outro	`{"error":"failed to generate variations","detail":"cannot generate variations from a child product"}`

Vincular produto existente

POST/api/v1/admin/products/{id}/variations/linkAdmin

Vincula um produto existente como variação filha

Transforma um produto que já existe em filho do pai informado. Serve para quem já cadastrou cada tamanho como produto separado (por exemplo, vindo de uma importação) e agora quer agrupá-los. O filho entra no grupo do pai (que é criado se ainda não existir). Os dois produtos precisam ser do mesmo seller, e o pai não pode ser filho de outro produto.

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

child_product_iduuidobrigatório

Id do produto que passará a ser filho.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations/link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"child_product_id":"'"$CHILD_ID"'"}'

Resposta

200Vinculado

json

{ "message": "product linked as variation" }

Erros

Status	Quando	Exemplo de corpo
400	`child_product_id` ausente	`{"error":"child_product_id is required"}`
500	Produto não encontrado, sellers diferentes ou pai já é filho	`{"error":"failed to link variation","detail":"child and parent products must belong to the same vendor"}`

Sincronizar dados do pai

POST/api/v1/admin/products/{id}/variations/syncAdmin

Copia os dados compartilhados do pai para todos os filhos

Copia do pai para todos os filhos a descrição, a descrição curta, a categoria, o título e a descrição de SEO e as categorias adicionais. Nome, SKU, preço, estoque, peso, imagens e os valores dos eixos de cada filho não são tocados. Use depois de editar a descrição do pai. Os filhos são reindexados na busca.

Path parameters

iduuidobrigatório

Id do produto pai (precisa ser um UUID válido e não pode ser filho).

Exemplo de requisição

bash

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

Resposta

200Sincronizado

json

{ "message": "variation data synced" }

Erros

Status	Quando	Exemplo de corpo
400	`id` que não é UUID	mensagem de validação do id
500	Pai inexistente ou que é filho	`{"error":"failed to sync variation data","detail":"parent product not found or is itself a child"}`

Desvincular variação

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

Unlink a child variation

Solta o filho do pai. O produto continua existindo como produto comum, sem pai e sem grupo. Não exclui nada. Para apagar o produto, use Excluir produto.

Path parameters

iduuidobrigatório

Id do produto pai (informativo).

varIDuuidobrigatório

Id do filho a desvincular.

Exemplo de requisição

bash

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

Resposta

200Desvinculado

json

{ "message": "variation unlinked" }

Erros

Status	Quando	Exemplo de corpo
500	`varID` não corresponde a nenhum produto	`{"error":"failed to unlink variation","detail":"variation not found"}`

A operação não confere se varID é mesmo filho de {id}: chamá-la com qualquer produto existente o desvincula de onde estiver, e repeti-la é inofensiva (responde 200 de novo).

Definir variação padrão

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

Define a variação filha padrão

Marca qual filho é a variação padrão do pai, a que a loja usa quando o cliente abre o produto sem escolher nada. Substitui o padrão anterior. Não precisa de corpo.

Path parameters

iduuidobrigatório

Id do produto pai.

varIDuuidobrigatório

Id do filho que será o padrão. Precisa ser filho deste pai.

Exemplo de requisição

bash

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

Resposta

200Padrão definido

json

{ "message": "default variation set" }

Erros

Status	Quando	Exemplo de corpo
400	O produto não é filho deste pai	`{"error":"product 07635228-fcac-442e-9a0c-caa7c1c89a97 is not a child of parent 3cbd86fd-0e6c-404f-8264-c99438a28ce0"}`
400	`varID` não existe	`{"error":"child product not found"}`

Veja também

API atual/Guia rápido/Variações e opções

Ações sobre variações

Gera filhos em lote, vincula um produto existente como filho, copia dados do pai, desvincula um filho e define a variação padrão.

Todas exigem o privilégio de gerenciar o catálogo.

Gerar variações

POST/api/v1/admin/products/{id}/variations/generateAdmin

Gera variações filhas em lote

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

combinationsarrayobrigatório

Lista de combinações, uma por filho a criar. Pelo menos uma.

(item)object

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"combinations":[
        {"a827c238-e0ce-4ff3-9655-478b5e3adf1b":"68399e61-4bf1-4762-b6d8-912c026a496a"},
        {"a827c238-e0ce-4ff3-9655-478b5e3adf1b":"177db45a-f708-4564-af8f-604b3053c5a1"}
      ]}'

Resposta

201Filhos criados (um item, resumido)

json

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

Response fields

countinteger

Filhos criados nesta chamada (combinações que já existiam não entram).

variationsarray

Os filhos criados, no formato de produto.

Erros

Status	Quando	Exemplo de corpo
400	`combinations` vazio ou ausente	`{"error":"combinations is required","detail":"provide at least one combination"}`
500	Pai sem grupo de variação	`{"error":"failed to generate variations","detail":"parent product has no variation group; create one first"}`
500	Pai é filho de outro	`{"error":"failed to generate variations","detail":"cannot generate variations from a child product"}`

Vincular produto existente

POST/api/v1/admin/products/{id}/variations/linkAdmin

Vincula um produto existente como variação filha

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

child_product_iduuidobrigatório

Id do produto que passará a ser filho.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PARENT_ID/variations/link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"child_product_id":"'"$CHILD_ID"'"}'

Resposta

200Vinculado

json

{ "message": "product linked as variation" }

Erros

Status	Quando	Exemplo de corpo
400	`child_product_id` ausente	`{"error":"child_product_id is required"}`
500	Produto não encontrado, sellers diferentes ou pai já é filho	`{"error":"failed to link variation","detail":"child and parent products must belong to the same vendor"}`

Sincronizar dados do pai

POST/api/v1/admin/products/{id}/variations/syncAdmin

Copia os dados compartilhados do pai para todos os filhos

Path parameters

iduuidobrigatório

Id do produto pai (precisa ser um UUID válido e não pode ser filho).

Exemplo de requisição

bash

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

Resposta

200Sincronizado

json

{ "message": "variation data synced" }

Erros

Status	Quando	Exemplo de corpo
400	`id` que não é UUID	mensagem de validação do id
500	Pai inexistente ou que é filho	`{"error":"failed to sync variation data","detail":"parent product not found or is itself a child"}`

Desvincular variação

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

Unlink a child variation

Solta o filho do pai. O produto continua existindo como produto comum, sem pai e sem grupo. Não exclui nada. Para apagar o produto, use Excluir produto.

Path parameters

iduuidobrigatório

Id do produto pai (informativo).

varIDuuidobrigatório

Id do filho a desvincular.

Exemplo de requisição

bash

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

Resposta

200Desvinculado

json

{ "message": "variation unlinked" }

Erros

Status	Quando	Exemplo de corpo
500	`varID` não corresponde a nenhum produto	`{"error":"failed to unlink variation","detail":"variation not found"}`

A operação não confere se varID é mesmo filho de {id}: chamá-la com qualquer produto existente o desvincula de onde estiver, e repeti-la é inofensiva (responde 200 de novo).

Definir variação padrão

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

Define a variação filha padrão

Marca qual filho é a variação padrão do pai, a que a loja usa quando o cliente abre o produto sem escolher nada. Substitui o padrão anterior. Não precisa de corpo.

Path parameters

iduuidobrigatório

Id do produto pai.

varIDuuidobrigatório

Id do filho que será o padrão. Precisa ser filho deste pai.

Exemplo de requisição

bash

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

Resposta

200Padrão definido

json

{ "message": "default variation set" }

Erros

Status	Quando	Exemplo de corpo
400	O produto não é filho deste pai	`{"error":"product 07635228-fcac-442e-9a0c-caa7c1c89a97 is not a child of parent 3cbd86fd-0e6c-404f-8264-c99438a28ce0"}`
400	`varID` não existe	`{"error":"child product not found"}`