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 características da API legada (/api/v1.0/features e a forma sem versão /api/features), o contrato compatível com a Venddor 1.0 (o mesmo contrato que os clientes antigos já usam).

Como funciona

Do cadastro ao filtro da vitrine

1. Crie a característica

   Use Criar característica com um nome (description) e um tipo (feature_type). Para uma característica de lista (cor, tamanho, marca), envie também as opções em variants, na mesma chamada.

2. Informe o valor em cada produto

   O valor mora no produto, não na característica. Para tipos de lista o valor aponta para uma opção pelo variant_id; para texto, número e data o valor é livre. Essas rotas fazem parte da seção de produtos.

3. Confira o resultado

   Use Consultar característica para ler a característica com as opções e confirmar os ids que você vai usar nos produtos.

Tipos de característica

Nesta API o tipo é uma letra, herdada da Venddor 1.0.

Uma característica de autor sai da leitura como T. A coluna "Aparece como filtro" reflete o que a vitrine monta hoje: os filtros da loja só listam características de lista, de marca e de cor.

Grupos

Um grupo agrupa características parecidas sob um título ("Dimensões" reúne Largura, Altura, Profundidade e Peso). Um grupo é uma característica de tipo G: ela aparece na mesma lista, e as características filhas apontam para ele em group_id.

Status

O status da característica é uma letra de 1 caractere.

Na leitura a API informa A para qualquer característica. Na alteração você pode enviar A, H ou D.

Como a característica aparece na vitrine

Três botões independentes controlam isso. Na leitura eles saem como "Y" ou "N":

Ids, datas e formatos

• Em /api/v1.0, todo id (característica, opção, grupo, produto) é um UUID em string. Em /api/features (sem v1.0), os ids saem como números decimais dentro de uma string ("673694264"), no estilo da Venddor 1.0.
• A API não devolve datas de criação das características.
• Os booleanos são "Y" ou "N".
• Dinheiro não aparece nesta seção.

Autenticação e permissão

Endpoints

Todas as rotas exigem administrador.

Erros comuns

1. Esperar as opções na lista. A lista de características não traz as opções (variants vem sempre vazio). Para ver as opções, consulte a característica por id.
2. Mandar o tipo errado. Só existem as letras C, S, M, T, N, O, G e E. Cor se cria com S mais "filter_style":"color". Autor não existe para escrita: T cria uma característica de texto.
3. Querer ligar o filtro. Esta API não grava filterable, categories_path, group_id, purpose, prefix, suffix nem os botões de exibição.
4. Excluir uma característica que ainda está em uso. Se algum produto tem valor nela, a exclusão é recusada com 400. Tire o valor dos produtos primeiro.
5. Cadastrar a mesma opção duas vezes. Nome de característica é único por tipo, sem diferenciar maiúsculas de minúsculas, e a repetição volta 400. Uma opção repetida dentro de variants é ignorada em silêncio.
6. Estranhar as opções em minúsculas. Ao criar uma opção, a plataforma passa o texto para minúsculas e tira espaços repetidos. "Vermelho Escuro" vira vermelho escuro.
7. Mandar id inválido. Um id que não é UUID volta 500 em vez de 400. Valide o id antes de chamar.
8. Usar o id decimal de /api/features em alterações. O id decimal serve para ler (GET). Em PUT e DELETE ele volta 400: use o UUID.

Próximos passos