Conteúdo e características do produto
Como um produto recebe suas características, o que a API legada devolve sobre elas e sobre as avaliações, e o mapa das rotas dessa área.
Um produto tem mais do que nome e preço. Esta seção cobre, pela API legada compatível com a Venddor 1.0, o que descreve o produto na vitrine: as características (cor, material, peso, marca...) e as avaliações dos clientes.
Todas as rotas daqui são "por produto": você informa o id do produto no caminho (/products/{product_id}/...). 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).
| Peça | O que é | Exemplo |
|---|---|---|
| Característica (feature) | A definição de uma linha da ficha: nome, tipo, onde aparece e se filtra. É da loja, não do produto. | "Material", tipo select |
| Tipo | Como o valor é guardado e mostrado (tabela abaixo). | select, text, number |
| Opção (variant) | Um valor pré-cadastrado de uma característica de seleção. | "Algodão", "Poliéster" |
| Grupo (feature group) | Uma característica do tipo group que serve de "título de seção". As outras apontam para ele em group_id. A vitrine agrupa a ficha por grupo. | "Dimensões" (grupo) com "Peso" e "Largura" |
| Valor no produto | A ligação entre um produto, uma característica e um valor. Um por característica em cada produto. | Camiseta X, Material = Algodão |
Tipos de característica
O feature_type da definição manda no formato do valor:
feature_type | Para que serve | Filtra na vitrine? |
|---|---|---|
select | Uma opção de uma lista fechada (Material) | Sim |
multi_select | Lista fechada, "várias opções" | Sim |
color | Como select, com cor de amostra na opção | Sim |
brand | Marca, lista aberta | Sim |
author | Autor ou criador, lista aberta | Sim |
text | Texto livre | Não |
number | Número inteiro, com prefixo e sufixo da definição (ex.: sufixo kg) | Não |
date | Data | Não |
bool | Sim ou não | Não |
group | Título de seção, não recebe valor | Não |
O que aparece onde na vitrine
São quatro marcas na definição da característica:
| Marca | Efeito |
|---|---|
display_on_product | A característica aparece na ficha técnica da página do produto. |
display_on_catalog | O valor aparece como selo no cartão do produto nas listagens. |
filterable | A característica vira filtro lateral da categoria (só os tipos de seleção da tabela acima, e só se algum produto tem valor). |
comparable | Entra na tabela de comparação de produtos. |
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.
Autenticação
Todas as rotas usam HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>. Os erros saem no formato {"message":"...","status":401}.
Endpoints
Auth: Admin é o administrador (Basic ou Bearer).
| Método | Rota | O que faz | Auth | Página |
|---|---|---|---|---|
| GET | /api/v1.0/products/{product_id}/features | Definições das características do produto | Admin | Características |
| GET | /api/v1.0/products/{product_id}/discussions | Avaliações do produto | Admin | Avaliações (discussions) |
Em /api (sem versão) as duas rotas também respondem, com ids em decimal.
Erros comuns
- Esperar os valores gravados no produto. A rota de características devolve as definições (com todas as opções), não só o valor escolhido para o produto.
- Exibir todas as avaliações aos clientes. A lista de avaliações inclui as pendentes (
N) e as recusadas (D). Filtrestatusigual aAdo seu lado. - Usar o código do produto como
product_id. O id é o UUID (ou o id decimal, na rota sem versão); um valor fora do formato devolve 500. - Esperar 404 para um produto sem características ou sem avaliações. A resposta é
200com lista vazia.