Conteúdo e características do produto

Um produto tem mais do que nome e preço. Esta seção cobre tudo o que descreve e conecta o produto na vitrine: as características (cor, material, peso, marca...), o SEO (endereço, título e descrição para o Google), as tags, os produtos sugeridos (venda cruzada) e os produtos obrigatórios.

Todas as rotas daqui são "por produto": você informa o id do produto no caminho (/products/{id}/...). Para criar o produto, veja Criar produto; para o modelo do produto, ids, dinheiro e status, veja a home de Produtos.

Como funciona

O modelo de características, do zero

Pense numa ficha técnica. A loja define quais linhas a ficha pode ter (a definição), e cada produto preenche as linhas que se aplicam a ele (o valor).

Tipos de característica e como enviar o valor

O feature_type da definição manda no formato do valor. Em PUT /features (e /characteristics) cada item da lista tem feature_id e um destes campos:

Em select, multi_select e color, um texto que não casa com nenhuma opção é recusado, e a mensagem lista as opções aceitas. O casamento ignora maiúsculas e acentos e também reconhece o dicionário de sinônimos da loja. Só brand e author criam a opção que não existe.

Característica ou "característica"? As duas rotas

Para ler as definições das características (nome, tipo e opções), use o cadastro de Características; as rotas desta seção lidam só com os valores gravados em cada produto. Veja Características do produto.

O que aparece onde na vitrine

São quatro marcas na definição da característica (ajustadas no cadastro de Características, fora desta seção):

Além disso, status precisa ser A (ativa) e categories_path (lista de categorias onde a característica vale; vazio significa todas) precisa incluir a categoria do filtro.

SEO, tags, vendas cruzadas e obrigatórios

• SEO do produto são quatro campos: slug (o endereço), seo_title, seo_description e meta_keywords. Dá para escrever à mão ou gerar a partir do nome e da descrição. Trocar o slug cria redirecionamentos automáticos (SEO do produto).
• Tags são rótulos livres ("Lançamento", "Verão 2026") compartilhados pela loja inteira (Tags e vendas cruzadas).
• Venda cruzada é uma lista ordenada de outros produtos que a vitrine sugere ("quem viu este também gostou"). Produto obrigatório é um item que acompanha este, como a pilha de um brinquedo, e pode ser marcado como obrigatório (Produtos obrigatórios).

Autenticação e permissões

Todas as rotas usam Authorization: Bearer <JWT> de um usuário administrador, com ids em UUID e erros no formato {"error":"...","detail":"..."}. O privilégio exigido é manage_features para as características; para o resto, view_catalog ou manage_catalog para ler e manage_catalog para gravar.

Endpoints

Auth: Admin é o administrador (Bearer).

Erros comuns

1. Mandar só o que mudou em PUT /features. A rota troca tudo. Se você enviar só a cor, o produto perde as demais características. Para acrescentar uma, use POST /characteristics, ou leia a lista, altere e devolva inteira.
2. Achar que o erro desfaz a gravação. Não desfaz. Os valores antigos são apagados antes de os novos entrarem; um item inválido deixa o produto com parte dos valores, ou com nenhum.
3. Enviar duas vezes a mesma característica (para simular multi_select). Responde 500 por duplicidade: há um valor por característica em cada produto.
4. Texto que não é uma opção. Em característica de seleção, value_text precisa casar com uma opção existente. Descubra as opções e seus ids nas rotas de Características.
5. Mandar value_num decimal. 1.5 vira 150. Envie sempre inteiro (e use sufixo ou prefixo na definição para a unidade).
6. Gerar o SEO de um produto já publicado. seo/generate sobrescreve o slug com o nome atual do produto; o endereço antigo passa a redirecionar.
7. Esperar que a venda cruzada devolva tudo o que você enviou. A leitura só devolve produtos ativos e visíveis na vitrine.

Próximos passos