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).
Listar as opções
/api/v1/admin/features/{id}/variantsAdminListar 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órioParâmetros de consulta
langstringbrand: código do idioma (pt-BR, en) usado para preencher name e description de cada marca em brands.include_descriptionsstring1brand: 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
Resposta
Campos da resposta
variantsarrayvariants[].iduuidvariant_id ao gravar o valor em um produto. O campo variant_id repete o mesmo valor.variants[].feature_iduuidvariants[].valuestringvariant repete o mesmo valor.variants[].codestringvariants[].positionintegervariants[].image_urlstringvariants[].colorstring#FF0000). Ausente quando não há.variants[].created_atstringvariants[].timestampintegertotalintegerbrandsarraybrand 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.descriptionsobjectinclude_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
/api/v1/admin/features/{id}/variantsAdminCriar 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órioCorpo da requisição
valuestringobrigatóriocodestringpositionintegerpadrão: 0image_urlstringcolorstring#32CD32), para característica de cor.descriptionstringbrand: texto da página da marca.slug_urlstringbrand: parte final do endereço da página da marca.page_titlestringbrand: título SEO da página.meta_descriptionstringbrand: descrição SEO.meta_keywordsstringbrand: palavras-chave SEO.descriptionsobjectbrand: 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
Resposta
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
/api/v1/admin/feature-variants/{id}AdminAlterar 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órioCorpo da requisição
valuestringcodestringpositionintegerimage_urlstringcolorstringdescriptionstringbrand: texto da página da marca.slug_urlstringbrand: parte final do endereço da página da marca.page_titlestringbrand: título SEO.meta_descriptionstringbrand: descrição SEO.meta_keywordsstringbrand: palavras-chave SEO.descriptionsobjectbrand: textos por idioma, no mesmo formato da criação.Exemplo de requisição
Resposta
Excluir uma opção
/api/v1/admin/feature-variants/{id}AdminExcluir 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órioExemplo de requisição
Resposta
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo que não é JSON | {"error":"invalid request body","detail":"..."} |
| 400 | Criação sem value | {"error":"value is required"} |
| 400 | value vazio depois de remover o HTML | {"error":"failed to create feature variant","detail":"value_required: variant value must not be empty after sanitization"} |
| 401 | Sem credenciais ou token expirado | {"error":"missing authorization header"} ou {"error":"invalid or expired token"} |
| 403 | Sem o privilégio manage_features | {"error":"insufficient privileges","required":"manage_features"} |
| 409 | Já 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) |
| 500 | Criar 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"} |