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

Eixos e geração de variações

Define os eixos de variação de um produto, gera todas as combinações e sincroniza dados do pai para as filhas.

Os eixos são as características (Cor, Tamanho) que diferenciam as versões de um produto. Eles formam o grupo de variação, criado na primeira chamada de definição. Só depois dele é possível criar filhas, uma a uma ou por combinação.

Ler eixos

GET/api/v1/vendor/products/{id}/variation-groupSeller

Ler os eixos de variação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (ler eixos)

bash

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

Resposta (ler eixos)

200Eixos

json

{
  "features": [
    {
      "id": "d1e2f3a4-0001-4b2c-8d3e-4f5a6b7c8d9e",
      "group_id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
      "feature_id": "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b",
      "purpose": "group_catalog_item"
    }
  ],
  "group_id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a"
}

Campos da resposta

group_idstring (uuid) | null

Id do grupo de variação; null se o produto não tem grupo.

featuresarray

Eixos do grupo: id, group_id, feature_id, purpose.

Erros (ler eixos)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
400	Id que não é UUID.	`{"error":"invalid id"}`
404	Produto não existe.	`{"error":"product not found"}`

Definir eixos

Define quais características diferenciam as versões do produto (os eixos, como Cor e Tamanho). A primeira chamada cria o grupo; as seguintes substituem os eixos. O produto não pode ser, ele mesmo, uma variação.

PUT/api/v1/vendor/products/{id}/variation-group-featuresSeller

Definir os eixos de variação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

featuresarrayobrigatório

Eixos, ao menos um.

feature_idstring (uuid)obrigatório

Característica do eixo. Veja GET /api/v1/vendor/features.

purposestringpadrão: group_catalog_item

group_catalog_itemgroup_variation_catalog_item

Papel do eixo. Vazio vale group_catalog_item.

Exemplo de requisição (definir eixos)

bash

curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/variation-group-features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "features": [
    {
      "feature_id": "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b",
      "purpose": "group_catalog_item"
    }
  ]
}'

Resposta (definir eixos)

200Grupo definido

json

{
  "group_id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a"
}

Campos da resposta

group_idstring (uuid)

Id do grupo.

Erros (definir eixos)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	Lista de eixos vazia, produto que já é variação, ou característica inexistente.	`{"error":"failed to set variation group","detail":"at least one feature is required"}`

Gerar variações

Cria de uma vez uma filha para cada combinação enviada. Combinação que já existe é pulada. A operação é tudo ou nada: se uma combinação falhar, nenhuma filha é criada. As filhas nascem com SKU vazio e estoque 0.

POST/api/v1/vendor/products/{id}/variations/generateSeller

Gerar variações por combinação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

combinationsarrayobrigatório

Cada item é um mapa id da característica para id da opção da característica (UUIDs). Ao menos um item.

Exemplo de requisição (gerar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/variations/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "combinations": [
    {
      "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f"
    },
    {
      "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a"
    }
  ]
}'

Resposta (gerar)

201Variações geradas

json

{
  "variations": [
    {
      "id": "c0ffee00-1111-4222-8333-444455556666",
      "name": "Camiseta Básica Algodão Preta - M",
      "parent_product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "is_variation": true
    }
  ],
  "total": 1
}

Campos da resposta

variationsarray

Filhas criadas (as já existentes não entram).

totalinteger

Quantidade criada.

Erros (gerar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	Pai sem grupo de variação, ou combinação inválida.	`{"error":"failed to generate variations","detail":"parent product has no variation group; create one first"}`

Sincronizar

Copia do pai para todas as filhas a descrição, o resumo, a categoria e o SEO (título e descrição). Nome, SKU, preço, estoque, peso, imagens e valores de eixo de cada filha não mudam.

POST/api/v1/vendor/products/{id}/variations/syncSeller

Copiar dados do pai para as variações

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (sincronizar)

bash

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

Resposta (sincronizar)

200Sincronizado

json

{
  "message": "variation data synced"
}

Campos da resposta

messagestring

Confirmação fixa.

Erros (sincronizar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	O produto é, ele mesmo, uma variação.	`{"error":"failed to sync variation data","detail":"parent product not found or is itself a child"}`

Veja também

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

Eixos e geração de variações

Define os eixos de variação de um produto, gera todas as combinações e sincroniza dados do pai para as filhas.

Ler eixos

GET/api/v1/vendor/products/{id}/variation-groupSeller

Ler os eixos de variação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (ler eixos)

bash

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

Resposta (ler eixos)

200Eixos

json

{
  "features": [
    {
      "id": "d1e2f3a4-0001-4b2c-8d3e-4f5a6b7c8d9e",
      "group_id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
      "feature_id": "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b",
      "purpose": "group_catalog_item"
    }
  ],
  "group_id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a"
}

Campos da resposta

group_idstring (uuid) | null

Id do grupo de variação; null se o produto não tem grupo.

featuresarray

Eixos do grupo: id, group_id, feature_id, purpose.

Erros (ler eixos)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
400	Id que não é UUID.	`{"error":"invalid id"}`
404	Produto não existe.	`{"error":"product not found"}`

Definir eixos

PUT/api/v1/vendor/products/{id}/variation-group-featuresSeller

Definir os eixos de variação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

featuresarrayobrigatório

Eixos, ao menos um.

feature_idstring (uuid)obrigatório

Característica do eixo. Veja GET /api/v1/vendor/features.

purposestringpadrão: group_catalog_item

group_catalog_itemgroup_variation_catalog_item

Papel do eixo. Vazio vale group_catalog_item.

Exemplo de requisição (definir eixos)

bash

curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/variation-group-features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "features": [
    {
      "feature_id": "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b",
      "purpose": "group_catalog_item"
    }
  ]
}'

Resposta (definir eixos)

200Grupo definido

json

{
  "group_id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a"
}

Campos da resposta

group_idstring (uuid)

Id do grupo.

Erros (definir eixos)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	Lista de eixos vazia, produto que já é variação, ou característica inexistente.	`{"error":"failed to set variation group","detail":"at least one feature is required"}`

Gerar variações

POST/api/v1/vendor/products/{id}/variations/generateSeller

Gerar variações por combinação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

combinationsarrayobrigatório

Cada item é um mapa id da característica para id da opção da característica (UUIDs). Ao menos um item.

Exemplo de requisição (gerar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/variations/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "combinations": [
    {
      "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f"
    },
    {
      "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a"
    }
  ]
}'

Resposta (gerar)

201Variações geradas

json

{
  "variations": [
    {
      "id": "c0ffee00-1111-4222-8333-444455556666",
      "name": "Camiseta Básica Algodão Preta - M",
      "parent_product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "is_variation": true
    }
  ],
  "total": 1
}

Campos da resposta

variationsarray

Filhas criadas (as já existentes não entram).

totalinteger

Quantidade criada.

Erros (gerar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	Pai sem grupo de variação, ou combinação inválida.	`{"error":"failed to generate variations","detail":"parent product has no variation group; create one first"}`

Sincronizar

Copia do pai para todas as filhas a descrição, o resumo, a categoria e o SEO (título e descrição). Nome, SKU, preço, estoque, peso, imagens e valores de eixo de cada filha não mudam.

POST/api/v1/vendor/products/{id}/variations/syncSeller

Copiar dados do pai para as variações

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (sincronizar)

bash

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

Resposta (sincronizar)

200Sincronizado

json

{
  "message": "variation data synced"
}

Campos da resposta

messagestring

Confirmação fixa.

Erros (sincronizar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	O produto é, ele mesmo, uma variação.	`{"error":"failed to sync variation data","detail":"parent product not found or is itself a child"}`