VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Página de produto

Variações e opções

Lista as opções de personalização, os eixos de variação e as combinações de um produto, e resolve a escolha do comprador em um produto-filho.

Quatro rotas cobrem tudo o que o comprador escolhe antes de comprar. Antes de chamá-las, leia o quadro "Opções, variações de produtos-filhos e variações unificadas" na home da seção: cada loja pode usar um mecanismo diferente por produto.

Nesta página, seller é o lojista dono da oferta, e SKU é o código de estoque de uma combinação.

Opções de personalização

Devolve as opções de um produto: campos que o comprador preenche ou escolhe e que não geram outro produto (sabor, gravação, arquivo de arte). Cada opção tem um tipo e, nas de escolha, uma lista de valores com modificadores de preço e de peso.

GET/api/v1/storefront/products/{id}/optionsPública

Opções de personalização do produto

Parâmetros de caminho

iduuidobrigatório
Id do produto.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/products/34a3bed9-c40d-4519-801f-5cae027eac2a/options"

Resposta

200Opções retornadas (exemplo ilustrativo do formato)
json
{
  "options": [
    {
      "id": "6d0a2f6e-4b2c-4a4a-9a58-5b8d3c1e0001",
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "name": "Sabor",
      "type": "select",
      "required": true,
      "position": 0,
      "settings": {},
      "values": [
        {
          "id": "6d0a2f6e-4b2c-4a4a-9a58-5b8d3c1e0101",
          "option_id": "6d0a2f6e-4b2c-4a4a-9a58-5b8d3c1e0001",
          "value": "Chocolate",
          "price_modifier": 0,
          "price_modifier_type": "absolute",
          "weight_modifier": 0,
          "weight_modifier_type": "absolute",
          "sku_suffix": "-CHO",
          "position": 0
        },
        {
          "id": "6d0a2f6e-4b2c-4a4a-9a58-5b8d3c1e0102",
          "option_id": "6d0a2f6e-4b2c-4a4a-9a58-5b8d3c1e0001",
          "value": "Pistache",
          "price_modifier": 500,
          "price_modifier_type": "absolute",
          "weight_modifier": 0,
          "weight_modifier_type": "absolute",
          "sku_suffix": "-PIS",
          "position": 1
        }
      ]
    }
  ]
}
200Produto sem opções (resposta real da loja de testes)
json
{ "options": null }

Campos da resposta

optionsarray|null
Opções do produto, por position. null (ou [], em caso de falha interna) quando não há.
options[].iduuid
Id da opção.
options[].namestring
Rótulo para exibir.
options[].typestring
selectradiocheckboxtextcolortextareafile
Como o comprador responde: select/radio escolhem um valor, checkbox escolhe vários, color escolhe uma cor, text/textarea são texto livre, file é envio de arquivo.
options[].requiredboolean
true = precisa de resposta para comprar.
options[].settingsobject
Regras do tipo: max_length (textarea, padrão 5000), max_file_size_mb (file, padrão 10), allowed_types (file, padrão jpg, jpeg, png, pdf, doc, docx, ai, eps, svg), min_select e max_select (checkbox: quantas escolhas, 0 = sem limite).
options[].valuesarray
Valores possíveis (nas opções de escolha).
options[].values[].valuestring
Texto do valor.
options[].values[].price_modifierinteger
Acréscimo (ou desconto, se negativo) ao preço. Em centavos quando price_modifier_type é absolute; em pontos-base (100 = 1%) quando é percentage. Zerado para visitante se a loja esconde preços.
options[].values[].price_modifier_typestring
absolutepercentage
Unidade do modificador de preço.
options[].values[].weight_modifierinteger
Ajuste de peso em gramas (absolute) ou pontos-base (percentage).
options[].values[].weight_modifier_typestring
absolutepercentage
Unidade do modificador de peso.
options[].values[].sku_suffixstring
Sufixo acrescentado ao SKU quando o valor é escolhido.

Achar o produto-filho pelos atributos

Para produtos com variações em produtos-filhos: recebe o que o comprador escolheu e devolve o filho que bate. A comparação ignora maiúsculas e minúsculas, e todos os atributos enviados têm de bater com o mesmo filho. Só filhos ativos são devolvidos.

Se o nome do parâmetro for o id da característica, o valor é comparado com a variante daquela característica. Se o nome for qualquer outra coisa (por exemplo cor), o nome é ignorado e o valor é procurado entre os valores de qualquer característica do filho. Para evitar falsos positivos (um tamanho "M" e uma cor "M"), prefira o id da característica.

GET/api/v1/storefront/products/{id}/variantPública

Achar o produto-filho por atributos

Parâmetros de caminho

iduuidobrigatório
Id do produto pai.

Parâmetros de consulta

atributostringobrigatório
Um ou mais pares atributo=valor, por exemplo ?cor=Vermelho&tamanho=M ou ?<id da característica>=Vermelho. Pelo menos um é obrigatório. Todos os parâmetros da query entram na comparação, então não envie parâmetros alheios (como lang).

Exemplo de requisição

bash
curl -G "$BASE_URL/api/v1/storefront/products/$PARENT_ID/variant" \
  --data-urlencode "cor=Vermelho" --data-urlencode "tamanho=M"

Resposta

200Produto-filho (reduzido, exemplo ilustrativo)
json
{
  "id": "9b1f0c52-7a54-4d0b-8a6c-0c6f5f4e2a10",
  "parent_product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
  "name": "Camiseta Básica Vermelha M",
  "sku": "CAM-VER-M",
  "price": 5990,
  "track_inventory": true,
  "quantity": 12,
  "is_variation": true,
  "feature_values": {
    "0b7d7c1e-1f2a-4c55-9d52-111111111111": { "variant_id": "7a1c9d20-3b44-4e0f-8a10-444444444444", "value": "Vermelho" },
    "0b7d7c1e-1f2a-4c55-9d52-555555555555": { "variant_id": "7a1c9d20-3b44-4e0f-8a10-666666666666", "value": "M" }
  },
  "status": "A"
}

Campos da resposta

(produto-filho)object
O produto-filho completo, no formato de Listar produtos. O price e o quantity são os do filho: use-os no lugar dos do pai.
parent_product_iduuid
Id do pai.
feature_valuesobject
Os valores que distinguem este filho: mapa id da característica para variant_id e value.

Esta rota devolve o produto sem o desconto de catálogo, as escadas de preço do grupo do cliente nem a checagem de região de entrega. Para o preço final com desconto, use /products/prices com o id do filho.

Eixos do grupo de variações

Para variações em produtos-filhos, devolve quais características formam os eixos (por exemplo Cor e Tamanho), para você montar os seletores. Os valores possíveis de cada eixo saem das características e dos filhos.

GET/api/v1/storefront/products/{id}/variation-groupPública

Eixos do grupo de variações

Parâmetros de caminho

iduuidobrigatório
Id de um produto do grupo (o pai ou um filho).
200Grupo retornado (exemplo ilustrativo)
json
{
  "group_id": "0f6b8a10-52de-4d7d-9b21-0c0d2b1d9a77",
  "features": [
    {
      "id": "3a1f3a60-8d2e-4c0c-a7c4-aaaaaaaaaaaa",
      "group_id": "0f6b8a10-52de-4d7d-9b21-0c0d2b1d9a77",
      "feature_id": "0b7d7c1e-1f2a-4c55-9d52-111111111111",
      "purpose": "group_variation_catalog_item"
    }
  ]
}
200Produto sem grupo (resposta real da loja de testes)
json
{ "features": [], "group_id": null }

Campos da resposta

group_iduuid|null
Id do grupo de variações. null quando o produto não tem.
featuresarray
Eixos do grupo.
features[].feature_iduuid
Id da característica que é o eixo (use em Consultar uma característica para obter nome e valores). Pode vir option_id no lugar, em grupos antigos.
features[].purposestring
group_catalog_itemgroup_variation_catalog_item
Papel da característica no grupo.

Variações unificadas

Para produtos com um cadastro e várias combinações: devolve os eixos (group.features) e uma linha por combinação comprável, com SKU, estoque e diferença de preço.

GET/api/v1/storefront/products/{id}/unified-variationsPública

Eixos e combinações de variação unificada

Parâmetros de caminho

iduuidobrigatório
Id do produto.
200Variações retornadas (exemplo ilustrativo do formato)
json
{
  "group": {
    "id": 17,
    "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
    "name": "Camiseta",
    "features": [
      { "name": "Cor", "values": ["Vermelho", "Azul"] },
      { "name": "Tamanho", "values": ["P", "M", "G"] }
    ],
    "created_at": "2026-10-11T20:54:44Z"
  },
  "variations": [
    {
      "id": 101,
      "group_id": 17,
      "product_id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
      "combination": { "Cor": "Vermelho", "Tamanho": "M" },
      "price_modifier": 0,
      "stock": 12,
      "sku": "CAM-VER-M",
      "image_url": "/uploads/camiseta-vermelha.jpg",
      "is_default": true,
      "sort_order": 0,
      "created_at": "2026-10-11T20:54:44Z",
      "updated_at": "2026-10-11T20:54:44Z"
    }
  ]
}
200Produto sem variações unificadas (resposta real da loja de testes)
json
{ "group": null, "variations": [] }

Campos da resposta

groupobject|null
O grupo de eixos. null quando o produto não usa variações unificadas.
group.idinteger
Id do grupo. Aqui os ids de grupo e de variação são inteiros, não UUIDs.
group.featuresarray
Eixos: name (ex.: "Cor") e values (ex.: ["Vermelho", "Azul"]).
variationsarray
Uma linha por combinação comprável, por sort_order.
variations[].combinationobject
A combinação: eixo para valor ({"Cor": "Vermelho", "Tamanho": "M"}). É a chave para resolver a escolha do comprador.
variations[].price_modifierinteger
Diferença para o preço do produto, em centavos. Pode ser negativa. Preço da combinação: price do produto mais este valor.
variations[].stockinteger
Saldo desta combinação.
variations[].skustring
SKU da combinação.
variations[].image_urlstring
Imagem da combinação. Pode ser vazia.
variations[].is_defaultboolean
Combinação pré-selecionada.
variations[].product_iduuid
O produto ao qual as combinações pertencem (o mesmo do caminho).

Erros

StatusQuandoExemplo de corpo
400/variant sem nenhum atributo na query{"error":"at least one option query parameter is required","detail":"e.g., ?color=Red&size=M"}
404/variant sem filho ativo que bata com todos os atributos{"error":"no matching variant found"}
404/variation-group com produto inexistente{"error":"product not found"}
500/variation-group ou /variant com {id} que não é UUID, ou falha ao consultar{"error":"failed to get product","detail":"..."}

/options e /unified-variations não devolvem erro: em falha interna respondem 200 com lista vazia, para a página do produto não quebrar. Os modificadores de preço de /options ficam zerados para visitante se a loja esconde preços; o price_modifier de /unified-variations não passa por essa regra, então não confie nele para esconder preço.

Atributos de /variant são comparados só por valor

Quando o nome do parâmetro não é um id de característica, apenas o valor conta. Se dois eixos tiverem valores iguais (um eixo "Tamanho" com valor "M" e um eixo "Modelo" com valor "M", por exemplo), a resposta pode ser o filho errado. Envie o id da característica como nome do parâmetro, que tira a ambiguidade.

Estoque por combinação

Em variações unificadas, desabilite no seletor as combinações com stock zero, a menos que o produto aceite encomenda (out_of_stock_action: "B" no produto).

Veja também

  • Consultar produto
  • Listar produtos
  • Características
Anterior
Página de produto
Próxima
Características do produto
Nesta página
  • Opções de personalização
  • Exemplo de requisição
  • Resposta
  • Achar o produto-filho pelos atributos
  • Exemplo de requisição
  • Resposta
  • Eixos do grupo de variações
  • Variações unificadas
  • Erros
  • Veja também