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

Grupo de variação

Define e consulta os eixos (Tamanho, Cor) que distinguem os produtos filhos de um produto pai.

O grupo de variação é o que transforma um produto em pai: ele guarda a lista de eixos, isto é, quais atributos diferenciam um filho do outro. Num pai de camisetas, o eixo pode ser a característica Tamanho; cada filho então tem um valor nesse eixo (P, M, G). O grupo é criado na primeira vez que você define os eixos, e é compartilhado por pai e filhos (todos carregam o mesmo variation_group_id).

Há duas maneiras de definir os eixos:

Pelas características (recomendada): você informa as características que servem de eixo, como Tamanho ou Cor. É o que a vitrine e os filtros usam.
Pelas opções: você informa ids de opções do produto. Existe por compatibilidade com cadastros antigos.

Redefinir os eixos substitui a lista anterior. Os filhos já criados não são alterados nem apagados.

Consultar os eixos

GET/api/v1/admin/products/{id}/variation-groupAdmin

Consulta os eixos de variação de um produto

Devolve o id do grupo e a lista de eixos. Funciona para o pai e para qualquer filho (que devolve o grupo do pai). Produto sem grupo devolve group_id: null e lista vazia.

Path parameters

iduuidobrigatório

Id do produto pai ou de um filho.

Exemplo de requisição

bash

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

Resposta

200Produto com grupo

json

{
  "group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
  "features": [
    {
      "id": "2fb5c4d5-f948-4408-86d8-f7ea63cbdd55",
      "group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
      "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
      "purpose": "group_catalog_item"
    }
  ]
}

200Produto sem grupo

json

{ "features": [], "group_id": null }

Response fields

group_iduuid | null

Id do grupo, ou null se o produto não participa de nenhum.

featuresarray

Eixos do grupo.

features[].iduuid

Id do vínculo eixo-grupo.

features[].feature_iduuid

Característica usada como eixo (ausente quando o eixo foi definido por opção).

features[].option_iduuid

Opção usada como eixo (ausente quando o eixo é uma característica).

features[].purposestring

group_catalog_itemgroup_variation_catalog_item

Papel do eixo: group_catalog_item gera itens distintos no catálogo (por exemplo Cor); group_variation_catalog_item gera variações dentro de um mesmo item (por exemplo Tamanho).

Erros

Status	Quando	Exemplo de corpo
404	Produto não existe	`{"error":"product not found"}`
500	`id` que não é UUID	`{"error":"failed to get product","detail":"..."}`
401 / 403	Sem login / sem privilégio de ver o catálogo	veja Opções

Definir eixos pelas características

PUT/api/v1/admin/products/{id}/variation-group-featuresAdmin

Define os eixos de variação a partir das características

Cria o grupo do pai (se ainda não existir) e grava os eixos, substituindo os anteriores. Responde com o id do grupo. O produto precisa existir e não pode ser filho de outro.

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

featuresarrayobrigatório

Eixos do grupo. Pelo menos um.

feature_iduuidobrigatório

Id da característica usada como eixo (Características).

purposestringpadrão: group_catalog_item

group_catalog_itemgroup_variation_catalog_item

Papel do eixo.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PARENT_ID/variation-group-features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"features":[{"feature_id":"a827c238-e0ce-4ff3-9655-478b5e3adf1b","purpose":"group_catalog_item"}]}'

Resposta

200Grupo definido

json

{
  "group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
  "message": "variation group created from features"
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`features` vazio	`{"error":"features is required","detail":"provide at least one feature"}`
500	Produto inexistente ou é um filho	`{"error":"failed to create variation group from features","detail":"a child variation cannot be a variation group parent"}`
500	`feature_id` inexistente ou inválido	`{"error":"failed to create variation group from features","detail":"..."}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	veja Opções

Definir eixos pelas opções

PUT/api/v1/admin/products/{id}/variation-groupAdmin

Define os eixos de variação a partir das opções do produto

Mesma ideia da rota anterior, mas os eixos são ids de opções de produto. Cada opção vira um eixo com purpose group_catalog_item. Prefira as características; use esta só se o seu cadastro de variações já se baseia em opções.

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

option_idsarrayobrigatório

Ids (UUID) das opções que servem de eixo. Pelo menos um.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PARENT_ID/variation-group" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"option_ids":["d89e2489-1661-423e-9cda-dc2c2903fcf4"]}'

Resposta

200Grupo definido

json

{
  "group_id": "4d8a21dc-91f7-4ed0-924b-2a9de92f5536",
  "message": "variation group created"
}

Erros

Status	Quando	Exemplo de corpo
400	`option_ids` ausente ou vazio	`{"error":"option_ids is required","detail":"provide at least one option ID"}`
500	Produto inexistente, é um filho, ou id que não é UUID	`{"error":"failed to create variation group","detail":"..."}`

Veja também

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

Grupo de variação

Define e consulta os eixos (Tamanho, Cor) que distinguem os produtos filhos de um produto pai.

Há duas maneiras de definir os eixos:

Pelas características (recomendada): você informa as características que servem de eixo, como Tamanho ou Cor. É o que a vitrine e os filtros usam.
Pelas opções: você informa ids de opções do produto. Existe por compatibilidade com cadastros antigos.

Redefinir os eixos substitui a lista anterior. Os filhos já criados não são alterados nem apagados.

Consultar os eixos

GET/api/v1/admin/products/{id}/variation-groupAdmin

Consulta os eixos de variação de um produto

Devolve o id do grupo e a lista de eixos. Funciona para o pai e para qualquer filho (que devolve o grupo do pai). Produto sem grupo devolve group_id: null e lista vazia.

Path parameters

iduuidobrigatório

Id do produto pai ou de um filho.

Exemplo de requisição

bash

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

Resposta

200Produto com grupo

json

{
  "group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
  "features": [
    {
      "id": "2fb5c4d5-f948-4408-86d8-f7ea63cbdd55",
      "group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
      "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
      "purpose": "group_catalog_item"
    }
  ]
}

200Produto sem grupo

json

{ "features": [], "group_id": null }

Response fields

group_iduuid | null

Id do grupo, ou null se o produto não participa de nenhum.

featuresarray

Eixos do grupo.

features[].iduuid

Id do vínculo eixo-grupo.

features[].feature_iduuid

Característica usada como eixo (ausente quando o eixo foi definido por opção).

features[].option_iduuid

Opção usada como eixo (ausente quando o eixo é uma característica).

features[].purposestring

group_catalog_itemgroup_variation_catalog_item

Papel do eixo: group_catalog_item gera itens distintos no catálogo (por exemplo Cor); group_variation_catalog_item gera variações dentro de um mesmo item (por exemplo Tamanho).

Erros

Status	Quando	Exemplo de corpo
404	Produto não existe	`{"error":"product not found"}`
500	`id` que não é UUID	`{"error":"failed to get product","detail":"..."}`
401 / 403	Sem login / sem privilégio de ver o catálogo	veja Opções

Definir eixos pelas características

PUT/api/v1/admin/products/{id}/variation-group-featuresAdmin

Define os eixos de variação a partir das características

Cria o grupo do pai (se ainda não existir) e grava os eixos, substituindo os anteriores. Responde com o id do grupo. O produto precisa existir e não pode ser filho de outro.

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

featuresarrayobrigatório

Eixos do grupo. Pelo menos um.

feature_iduuidobrigatório

Id da característica usada como eixo (Características).

purposestringpadrão: group_catalog_item

group_catalog_itemgroup_variation_catalog_item

Papel do eixo.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PARENT_ID/variation-group-features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"features":[{"feature_id":"a827c238-e0ce-4ff3-9655-478b5e3adf1b","purpose":"group_catalog_item"}]}'

Resposta

200Grupo definido

json

{
  "group_id": "7ecbf2d0-9c44-4562-b531-e7d5b3fc34ff",
  "message": "variation group created from features"
}

Erros

Status	Quando	Exemplo de corpo
400	Corpo não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`features` vazio	`{"error":"features is required","detail":"provide at least one feature"}`
500	Produto inexistente ou é um filho	`{"error":"failed to create variation group from features","detail":"a child variation cannot be a variation group parent"}`
500	`feature_id` inexistente ou inválido	`{"error":"failed to create variation group from features","detail":"..."}`
401 / 403	Sem login / sem privilégio de gerenciar o catálogo	veja Opções

Definir eixos pelas opções

PUT/api/v1/admin/products/{id}/variation-groupAdmin

Define os eixos de variação a partir das opções do produto

Path parameters

iduuidobrigatório

Id do produto pai.

Corpo da requisição

option_idsarrayobrigatório

Ids (UUID) das opções que servem de eixo. Pelo menos um.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PARENT_ID/variation-group" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"option_ids":["d89e2489-1661-423e-9cda-dc2c2903fcf4"]}'

Resposta

200Grupo definido

json

{
  "group_id": "4d8a21dc-91f7-4ed0-924b-2a9de92f5536",
  "message": "variation group created"
}

Erros

Status	Quando	Exemplo de corpo
400	`option_ids` ausente ou vazio	`{"error":"option_ids is required","detail":"provide at least one option ID"}`
500	Produto inexistente, é um filho, ou id que não é UUID	`{"error":"failed to create variation group","detail":"..."}`