VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Características

Opções de uma característica

Lista, cria, altera e exclui as opções (variantes) de uma característica de lista, como as cores, os tamanhos ou as marcas.

Uma característica de lista (select, multi_select, color, brand, author) só aceita como valor uma das opções que você cadastrou antes. Na API as opções se chamam variantes (variants, ou feature variants): para a característica "Tamanho", as variantes são "P", "M" e "G"; para "Cor", são "Vermelho" e "Azul", cada uma com uma cor em hexadecimal. Cada produto aponta para a opção pelo variant_id. Essas opções também são as caixas de seleção que aparecem no filtro da vitrine, com a contagem de produtos.

Esta página agrupa as quatro operações sobre opções. Elas valem para características de lista; o valor de cada produto aponta para uma destas opções (veja Consultar característica).

Como o texto da opção é tratado

Ao criar uma opção, a plataforma normaliza o texto antes de gravar: remove tags HTML, passa para minúsculas, junta espaços repetidos e troca pelo valor oficial qualquer palavra cadastrada como sinônimo. "Vermelho Escuro" vira vermelho escuro. Ao alterar uma opção, o texto é gravado como você enviou. Dentro de uma característica, duas opções não podem ter o mesmo texto, sem diferenciar maiúsculas de minúsculas.

Listar as opções

GET/api/v1/admin/features/{id}/variantsAdmin

Listar as opções de uma característica

Devolve todas as opções, na ordem de position, sem paginação. Exige o privilégio manage_features. Um id que não existe devolve lista vazia (não dá 404).

Parâmetros de caminho

iduuidobrigatório
Id da característica.

Parâmetros de consulta

langstring
Só para característica do tipo brand: código do idioma (pt-BR, en) usado para preencher name e description de cada marca em brands.
include_descriptionsstring
1
Só para brand: com 1, a resposta traz também descriptions, com o nome, a descrição e o SEO de cada marca em todos os idiomas.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/features/a827c238-e0ce-4ff3-9655-478b5e3adf1b/variants" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Opções retornadas
json
{
  "total": 6,
  "variants": [
    {
      "id": "1d13c44c-6575-403b-8ceb-e1cf37a5a862",
      "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
      "value": "PP",
      "code": "xs",
      "position": 1,
      "created_at": "2026-04-29T19:57:53.063048Z",
      "variant_id": "1d13c44c-6575-403b-8ceb-e1cf37a5a862",
      "variant": "PP",
      "timestamp": 1777492673
    }
  ]
}
200Característica do tipo brand
json
{
  "total": 28,
  "variants": [
    { "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd", "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232", "value": "Eco", "code": "eco", "position": 0, "variant_id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd", "variant": "Eco" }
  ],
  "brands": [
    { "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd", "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232", "name": "Eco", "description": "", "code": "eco", "position": 0, "lang_code": "pt-BR" }
  ]
}

Campos da resposta

variantsarray
Opções da característica.
variants[].iduuid
Id da opção. É o valor de variant_id ao gravar o valor em um produto. O campo variant_id repete o mesmo valor.
variants[].feature_iduuid
Característica dona da opção.
variants[].valuestring
Texto da opção. O campo variant repete o mesmo valor.
variants[].codestring
Código interno da opção. Pode ser vazio. Em marcas, também serve para localizar a página da marca.
variants[].positioninteger
Posição de ordenação.
variants[].image_urlstring
Imagem da opção (amostra, logotipo). Ausente quando não há.
variants[].colorstring
Cor em hexadecimal (#FF0000). Ausente quando não há.
variants[].created_atstring
Criação, RFC 3339 em UTC.
variants[].timestampinteger
Criação em Unix timestamp (segundos).
totalinteger
Quantidade de opções.
brandsarray
Só em característica brand que já tem marcas. Cada item tem id, feature_id, name, description, code, position, lang_code e, quando preenchidos, image_url, slug_url, page_title, meta_description e meta_keywords.
descriptionsobject
Só com include_descriptions=1 em brand. Chave é o id da marca; o valor é um objeto cujas chaves são os idiomas, com lang_code, name, description, page_title, meta_description e meta_keywords.

Criar uma opção

POST/api/v1/admin/features/{id}/variantsAdmin

Criar uma opção em uma característica

Acrescenta uma opção à característica. Responde 201 com a opção criada. Em característica brand, a criação também prepara o nome da marca em cada idioma da loja e o endereço da página dela. Exige o privilégio manage_features.

Parâmetros de caminho

iduuidobrigatório
Id da característica.

Corpo da requisição

valuestringobrigatório
Texto da opção. Veja como ele é normalizado no quadro acima.
codestring
Código interno.
positionintegerpadrão: 0
Posição de ordenação.
image_urlstring
URL da imagem da opção.
colorstring
Cor em hexadecimal (#32CD32), para característica de cor.
descriptionstring
Só em brand: texto da página da marca.
slug_urlstring
Só em brand: parte final do endereço da página da marca.
page_titlestring
Só em brand: título SEO da página.
meta_descriptionstring
Só em brand: descrição SEO.
meta_keywordsstring
Só em brand: palavras-chave SEO.
descriptionsobject
Só em brand: textos por idioma. Chave é o código do idioma; o valor tem name, description, page_title, meta_description e meta_keywords.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877/variants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "Verde", "code": "verde", "position": 3, "color": "#00FF00" }'

Resposta

201Opção criada
json
{
  "id": "2ed2fa86-7903-4743-b610-a1d488476d01",
  "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "value": "verde",
  "code": "verde",
  "position": 3,
  "color": "#00FF00",
  "created_at": "2026-10-11T20:50:10.833744Z",
  "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01",
  "variant": "verde",
  "timestamp": 1791751810
}

Note que value voltou em minúsculas ("Verde" virou "verde"). Os campos da resposta são os mesmos de cada item da lista.

Alterar uma opção

PUT/api/v1/admin/feature-variants/{id}Admin

Alterar uma opção

Alteração parcial: só os campos enviados mudam. O id é o da opção (o id ou variant_id de cada item da lista), não o da característica. O texto é gravado como enviado, sem passar para minúsculas. Exige o privilégio manage_features.

Parâmetros de caminho

iduuidobrigatório
Id da opção.

Corpo da requisição

valuestring
Novo texto. Não pode repetir o de outra opção da mesma característica, sem diferenciar maiúsculas de minúsculas. Vazio volta 400.
codestring
Código interno.
positioninteger
Posição de ordenação.
image_urlstring
URL da imagem da opção.
colorstring
Cor em hexadecimal.
descriptionstring
Só em brand: texto da página da marca.
slug_urlstring
Só em brand: parte final do endereço da página da marca.
page_titlestring
Só em brand: título SEO.
meta_descriptionstring
Só em brand: descrição SEO.
meta_keywordsstring
Só em brand: palavras-chave SEO.
descriptionsobject
Só em brand: textos por idioma, no mesmo formato da criação.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/feature-variants/2ed2fa86-7903-4743-b610-a1d488476d01" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "Verde Limão", "color": "#32CD32", "position": 9 }'

Resposta

200Opção alterada
json
{
  "id": "2ed2fa86-7903-4743-b610-a1d488476d01",
  "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "value": "Verde Limão",
  "code": "verde",
  "position": 9,
  "color": "#32CD32",
  "created_at": "2026-10-11T20:50:10.833744Z",
  "variant_id": "2ed2fa86-7903-4743-b610-a1d488476d01",
  "variant": "Verde Limão",
  "timestamp": 1791751810
}

Excluir uma opção

DELETE/api/v1/admin/feature-variants/{id}Admin

Excluir uma opção

Remove a opção e o valor dela em todos os produtos que a usavam. Diferente da exclusão de uma característica, não há bloqueio de "em uso": a opção some mesmo que haja produtos apontando para ela. Em brand, a página da marca também é retirada da vitrine. Exige o privilégio manage_features.

Parâmetros de caminho

iduuidobrigatório
Id da opção.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/feature-variants/2ed2fa86-7903-4743-b610-a1d488476d01" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Opção excluída
json
{ "message": "feature variant deleted" }

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
400Criação sem value{"error":"value is required"}
400value vazio depois de remover o HTML{"error":"failed to create feature variant","detail":"value_required: variant value must not be empty after sanitization"}
401Sem credenciais ou token expirado{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403Sem o privilégio manage_features{"error":"insufficient privileges","required":"manage_features"}
409Já existe uma opção com esse texto na característica{"error":"failed to create feature variant","detail":"duplicate_variant_value: a variant with value \"verde\" already exists for this feature"} (na alteração, failed to update feature variant)
500Criar em característica que não existe, alterar ou excluir opção que não existe, ou id que não é UUID{"error":"failed to create feature variant","detail":"feature 00000000-0000-0000-0000-000000000000 not found"}, {"error":"failed to update feature variant","detail":"get feature variant: sql: no rows in result set"}, {"error":"failed to delete feature variant","detail":"feature variant not found"}
Excluir uma opção apaga o valor dos produtos

Não há aviso nem recusa: quem tinha "Verde" passa a não ter nenhum valor naquela característica. Uma opção não tem estado "oculta", então exclua só quando tiver certeza e, se precisar reaproveitar os produtos, troque o valor deles antes.

Cores de amostra

Em característica do tipo color, envie color em hexadecimal com # (#FF0000). A vitrine usa esse valor para desenhar a amostra no filtro e na página do produto.

Veja também

  • Criar característica
  • Consultar característica
  • Sinônimos de valores
  • Excluir característica
Anterior
Excluir característica
Próxima
Sinônimos de valores
Nesta página
  • Listar as opções
  • Exemplo de requisição
  • Resposta
  • Criar uma opção
  • Exemplo de requisição
  • Resposta
  • Alterar uma opção
  • Exemplo de requisição
  • Resposta
  • Excluir uma opção
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também