VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Variações e opções

Variações

Lista, cria, altera e desvincula as variações (produtos filhos com SKU, estoque e preço próprios) de um produto do seller.

Variações são a forma de vender o mesmo produto em versões (cor, tamanho) controlando o estoque de cada uma. Antes de criar a primeira, defina os eixos em Eixos e geração. Os ids de {id} e {varID} são UUIDs; um id que não seja UUID volta 400.

Listar

GET/api/v1/vendor/products/{id}/variationsSeller

Listar 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 (listar)

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

Resposta (listar)

200Variações
json
{
  "variations": [
    {
      "id": "c0ffee00-1111-4222-8333-444455556666",
      "display_id": 10664,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
      "name": "Camiseta Básica Algodão Preta - M",
      "slug": "camiseta-basica-algodao-preta-m",
      "sku": "CAM-001-M",
      "barcode": "7891234567895",
      "description": "<p>Camiseta 100% algodão.</p>",
      "short_description": "Camiseta 100% algodão",
      "price": 4990,
      "list_price": 5990,
      "track_inventory": true,
      "quantity": 25,
      "low_stock_alert": 5,
      "min_quantity": 0,
      "max_quantity": 0,
      "quantity_step": 1,
      "sale_unit": "un",
      "zero_price_action": "P",
      "popularity": 0,
      "out_of_stock_action": "N",
      "weight": 0.25,
      "width": 30,
      "height": 2,
      "length": 40,
      "status": "A",
      "intended_status": "A",
      "approval_status": "approved",
      "view_count": 0,
      "sales_count": 0,
      "rating_avg": 0,
      "rating_count": 0,
      "free_shipping": false,
      "shipping_freight": 0,
      "requires_shipping": true,
      "vendor_name": "Loja Seller Teste",
      "vendor_slug": "loja-seller-teste",
      "created_at": "2026-10-11T20:56:24.231132Z",
      "updated_at": "2026-10-11T21:05:40.573283Z",
      "parent_product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "is_variation": true,
      "feature_values": {
        "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": {
          "variant_id": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f",
          "value": "M"
        }
      }
    }
  ],
  "total": 1
}

Campos da resposta

variationsarray
Produtos filhos, no formato de Consultar produto, com parent_product_id, is_variation e feature_values.
totalinteger
Quantidade.

Erros (listar)

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

Criar

Cria uma filha copiando o pai. O nome vira "nome do pai - valor1 / valor2". O produto pai precisa ter o grupo de variação definido antes.

POST/api/v1/vendor/products/{id}/variationsSeller

Criar uma 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

feature_valuesobjectobrigatório
Mapa id do eixo para o valor escolhido (texto), por exemplo {"<id da característica>": "M"}.
priceinteger
Preço da filha em centavos. Padrão: o do pai.
skustring
SKU da filha.
quantityinteger
Estoque da filha. Padrão: o do pai.
weightnumber
Peso em kg. Padrão: o do pai.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/variations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "feature_values": {
    "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": "M"
  },
  "sku": "CAM-001-M",
  "quantity": 12,
  "price": 4990
}'

Resposta (criar)

201Variação criada
json
{
  "id": "c0ffee00-1111-4222-8333-444455556666",
  "display_id": 10664,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "name": "Camiseta Básica Algodão Preta - M",
  "slug": "camiseta-basica-algodao-preta-m",
  "sku": "CAM-001-M",
  "barcode": "7891234567895",
  "description": "<p>Camiseta 100% algodão.</p>",
  "short_description": "Camiseta 100% algodão",
  "price": 4990,
  "list_price": 5990,
  "track_inventory": true,
  "quantity": 25,
  "low_stock_alert": 5,
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 1,
  "sale_unit": "un",
  "zero_price_action": "P",
  "popularity": 0,
  "out_of_stock_action": "N",
  "weight": 0.25,
  "width": 30,
  "height": 2,
  "length": 40,
  "status": "A",
  "intended_status": "A",
  "approval_status": "approved",
  "view_count": 0,
  "sales_count": 0,
  "rating_avg": 0,
  "rating_count": 0,
  "free_shipping": false,
  "shipping_freight": 0,
  "requires_shipping": true,
  "vendor_name": "Loja Seller Teste",
  "vendor_slug": "loja-seller-teste",
  "created_at": "2026-10-11T20:56:24.231132Z",
  "updated_at": "2026-10-11T21:05:40.573283Z",
  "parent_product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "is_variation": true,
  "feature_values": {
    "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": {
      "variant_id": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f",
      "value": "M"
    }
  }
}

Campos da resposta

(corpo)object
A filha criada.

Erros (criar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
400Id inválido ou corpo inválido.{"error":"invalid request body","detail":"..."}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}
500Pai sem grupo de variação, ou pai que já é uma variação.{"error":"failed to create variation","detail":"parent product has no variation group; create one first via SetVariationGroup"}

Alterar

Altera a filha com o mesmo corpo de Alterar produto: estoque, SKU, preço, status e o resto. Só filhas do produto do caminho são aceitas.

PUT/api/v1/vendor/products/{id}/variations/{varID}Seller

Alterar uma 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.
varIDstring (uuid)obrigatório
Id da variação (produto filho).

Corpo da requisição

(campos)object
Qualquer campo de Alterar produto.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/variations/$VARIATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sku": "CAM-001-M",
  "quantity": 20,
  "price": 4990
}'

Resposta (alterar)

200Variação alterada
json
{
  "id": "c0ffee00-1111-4222-8333-444455556666",
  "display_id": 10664,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "name": "Camiseta Básica Algodão Preta - M",
  "slug": "camiseta-basica-algodao-preta-m",
  "sku": "CAM-001-M",
  "barcode": "7891234567895",
  "description": "<p>Camiseta 100% algodão.</p>",
  "short_description": "Camiseta 100% algodão",
  "price": 4990,
  "list_price": 5990,
  "track_inventory": true,
  "quantity": 20,
  "low_stock_alert": 5,
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 1,
  "sale_unit": "un",
  "zero_price_action": "P",
  "popularity": 0,
  "out_of_stock_action": "N",
  "weight": 0.25,
  "width": 30,
  "height": 2,
  "length": 40,
  "status": "A",
  "intended_status": "A",
  "approval_status": "approved",
  "view_count": 0,
  "sales_count": 0,
  "rating_avg": 0,
  "rating_count": 0,
  "free_shipping": false,
  "shipping_freight": 0,
  "requires_shipping": true,
  "vendor_name": "Loja Seller Teste",
  "vendor_slug": "loja-seller-teste",
  "created_at": "2026-10-11T20:56:24.231132Z",
  "updated_at": "2026-10-11T21:05:40.573283Z",
  "parent_product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "is_variation": true,
  "feature_values": {
    "1f2e3d4c-5b6a-4789-8a9b-0c1d2e3f4a5b": {
      "variant_id": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f",
      "value": "M"
    }
  }
}

Campos da resposta

(corpo)object
A filha como ficou.

Erros (alterar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404A variação não é filha deste produto.{"error":"variation not found for this product"}
409Campo travado pelo catálogo mestre.{"error":"master-locked fields cannot be edited","locked_fields":["name"]}

Desvincular

Desvincula a filha do pai: ela deixa de ser variação e passa a ser um produto comum, sem eixos. O produto não é apagado.

DELETE/api/v1/vendor/products/{id}/variations/{varID}Seller

Desvincular uma 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.
varIDstring (uuid)obrigatório
Id da variação (produto filho).

Exemplo de requisição (desvincular)

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/variations/$VARIATION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (desvincular)

200Variação desvinculada
json
{
  "message": "variation unlinked"
}

Campos da resposta

messagestring
Confirmação fixa.

Erros (desvincular)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404A variação não é filha deste produto.{"error":"variation not found for this product"}
Aprovação

Cada filha é um produto e segue as mesmas regras de moderação: com premoderação ligada ela nasce com o status do pai e pode ficar pendente.

Veja também

  • Variações e opções: visão geral
  • Produtos do seller
Anterior
Valores de opção
Próxima
Eixos e geração de variações
Nesta página
  • Listar
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Alterar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Desvincular
  • Exemplo de requisição (desvincular)
  • Resposta (desvincular)
  • Erros (desvincular)
  • Veja também