Características

Uma característica é um atributo que muitos produtos compartilham e que a loja quer cadastrar, exibir e filtrar de forma padronizada: marca, cor, tamanho, material, peso, voltagem, garantia. Você cria a característica uma vez (por exemplo, "Cor") e depois informa o valor dela em cada produto ("Vermelho"). É isso que alimenta a aba de informações adicionais da página do produto, a tabela de comparação e a barra de filtros da vitrine.

Esta seção documenta as rotas de administração de características (/api/v1/admin/features). Os grupos de características têm uma seção própria: Grupos de características.

Como funciona

Do cadastro ao filtro da vitrine

1. Crie a característica

   Use Criar característica com um nome e um tipo. Para uma característica de lista (cor, tamanho, marca), crie também as opções com Opções de uma característica.

2. Escolha onde ela vale

   Deixe categories_path vazio para valer em todas as categorias, ou informe os ids das categorias separados por vírgula. Se a característica pertence a um grupo, ela herda as categorias do grupo.

3. Informe o valor em cada produto

   O valor mora no produto, não na característica. Você grava os valores de um produto com PUT /api/v1/admin/products/{id}/features (troca todos) ou acrescenta um com POST /api/v1/admin/products/{id}/characteristics. O corpo escolhe o campo certo para o tipo: variant_id para tipos de lista, value_text para texto, value_num para número, value_date para data. Essas rotas fazem parte da seção de produtos.

4. Ligue o filtro

   Com filterable ligado, status ativo e pelo menos um produto com valor, a característica aparece na barra de filtros da categoria na vitrine, com a contagem de produtos por opção.

Tipos de característica

O tipo é sempre um nome, em minúsculas.

A coluna "Aparece como filtro" reflete o que a vitrine monta hoje: os filtros da loja só listam características dos tipos select, multi_select, brand, author e color. O campo filterable pode ser gravado em qualquer tipo, mas nos demais não produz filtro.

Grupos

Um grupo agrupa características parecidas sob um título ("Dimensões" reúne Largura, Altura, Profundidade e Peso). Na página do produto e no cadastro, as características aparecem organizadas por grupo. Um grupo é, no armazenamento, uma característica com feature_type igual a group; as características filhas apontam para ele em group_id. Veja Grupos de características.

Status

O status da característica é uma letra de 1 caractere. A API aceita também a palavra por extenso na escrita e nos filtros.

Como a característica aparece na vitrine

Três botões independentes controlam isso, todos booleanos:

E um quarto, filterable, decide se ela vira filtro (veja acima).

Para que serve purpose

O campo purpose liga a característica ao mecanismo de variações de produto (o mesmo produto em várias cores e tamanhos). Os valores aceitos são três:

Textos em vários idiomas

O name e o description da característica são guardados no idioma padrão da loja. Para traduzir, envie descriptions na criação ou na alteração, um objeto cujas chaves são os códigos de idioma (en, es, pt-BR...) e cujos valores têm name e description. Para ler todas as traduções de uma vez, consulte a característica com ?include_descriptions=1. Um grupo só tem name traduzido. As marcas (opções de uma característica brand) têm descrição própria por idioma, veja Opções de uma característica.

Ids, datas e formatos

• Todo id (característica, opção, grupo, produto) é um UUID em string.
• As datas são RFC 3339 em UTC.
• Os booleanos são true ou false.
• Dinheiro não aparece nesta seção.

Autenticação e permissão

Endpoints

Todas as rotas exigem administrador. O privilégio é manage_features.

Erros comuns

1. Esperar as opções na lista. A lista de características não traz as opções. Para ver as opções, consulte a característica por id ou use GET /api/v1/admin/features/{id}/variants.
2. Mandar um tipo desconhecido. Só valem os tipos da tabela acima (select, multi_select, color, brand, author, text, number, date, bool e group). Um tipo fora da lista volta 500.
3. Esquecer de ligar o filtro. filterable, os botões de exibição e categories_path nascem desligados ou vazios. Informe-os já na criação.
4. Excluir uma característica que ainda está em uso. Se algum produto tem valor nela, a exclusão é recusada com 409. Tire o valor dos produtos primeiro.
5. Cadastrar a mesma opção duas vezes. Nome de característica é único por tipo e valor de opção é único por característica, sem diferenciar maiúsculas de minúsculas. A repetição volta 409.
6. Estranhar as opções em minúsculas. Ao criar uma opção, a plataforma passa o texto para minúsculas, tira espaços repetidos e troca sinônimos cadastrados pela opção oficial. "Vermelho Escuro" vira vermelho escuro. Na alteração, o texto é gravado como você enviou.
7. Mandar id inválido. Um id que não é UUID volta 500 em vez de 400. Valide o id antes de chamar.

Próximos passos