Variações, tags e filtros
Como a plataforma modela variações de produto (cor, tamanho), exceções de combinação, tags e filtros, e quais rotas agem sobre cada um.
Uma variação é uma versão de um produto que muda em algum eixo, como cor ou tamanho: a camiseta vermelha M e a azul G são variações da mesma camiseta. Uma tag é uma etiqueta livre ("Lançamento", "Frete Grátis") que agrupa produtos. Um filtro é uma característica que o cliente usa para refinar uma busca. Esta seção reúne as rotas de edição e exclusão desses itens pelo id deles.
Como funciona
| Modelo | Como é o dado | Id | Rotas desta seção |
|---|---|---|---|
| Variação simples | Uma linha ligada ao produto, com sku, price, quantity e options (par eixo e valor). | UUID | PUT e DELETE /variations/{id} |
| Variação unificada | Uma combinação dentro de um grupo, com price_modifier (diferença sobre o preço do pai), stock, is_default. | inteiro | PUT e DELETE /unified-variations/{id} |
| Produto filho | Cada variação é um produto completo, ligado a um produto pai por um variation_group_id. | UUID do grupo | GET /variation-groups/{id} |
Conceitos-chave
Exceções de opções
Quando um produto tem várias opções (cor e tamanho), nem toda combinação existe. Uma exceção marca uma combinação como proibida ou permitida, conforme o produto esteja em modo "proibidas" (F) ou "permitidas" (A). Esta seção apaga uma exceção pelo id dela; criar e listar fica nas rotas do produto (.../products/{id}/option-exceptions).
Tags e filtros
Uma tag tem id, name e slug. Os filtros da vitrine são características de produto marcadas como filtráveis; a rota GET /filters é um atalho que lista as características.
Endpoints
| Método e caminho | Para que serve | Autenticação | Página |
|---|---|---|---|
PUT /api/v1/admin/variations/{id} | Altera uma variação simples | administrador | Variações |
DELETE /api/v1/admin/variations/{id} | Apaga uma variação simples | administrador | Variações |
PUT /api/v1/admin/unified-variations/{id} | Altera uma variação unificada | administrador | Variações |
DELETE /api/v1/admin/unified-variations/{id} | Apaga uma variação unificada | administrador | Variações |
DELETE /api/v1/admin/option-exceptions/{id} | Apaga uma exceção de opção | administrador | Variações |
GET /api/v1/admin/variation-groups/{id} | Lê um grupo de produtos filhos | administrador | Grupos de variação |
GET /api/v1/admin/tags | Lista as tags da loja | administrador | Tags e filtros |
DELETE /api/v1/admin/tags/{id} | Apaga uma tag | administrador | Tags e filtros |
GET /api/v1/admin/filters | Lista as características (filtros) | administrador | Tags e filtros |
Erros comuns
- Usar o UUID de um produto filho em
/variations/{id}. Produtos filhos não são variações simples. Veja os três modelos. - Mandar UUID para
/unified-variations/{id}. O id é inteiro:400. - Mandar corpo
{}paraPUT /variations/{id}.500comno fields to update. - Tratar
500como falha do servidor ao apagar uma variação ou tag inexistente. Aqui significa "não encontrado". - Esperar que
GET /filtersdevolva só as características filtráveis. Ela devolve todas. - Apagar uma tag achando que só some o rótulo. Ela sai de todos os produtos.