Regras de vitrine

Por padrão a ordem dos produtos numa busca ou numa categoria vem da relevância. Regras de vitrine (merchandising) deixam a loja intervir nessa ordem sem mexer em preço nem em catálogo: fixar produtos no topo, impulsionar os que estão em oferta ou são novos, rebaixar os sem estoque. Uma regra pode valer para um termo de busca específico ("tênis"), para uma categoria, ou para a loja inteira, e pode ter data de início e de fim (uma campanha).

Como funciona

Como a ordem final é montada

Para cada busca ou listagem a plataforma reúne todas as regras ativas que se aplicam (as global, a regra do termo exato, as da categoria e das categorias-mãe com include_children), dentro da janela, em ordem de priority. Então:

1. Os fixados (pins) vão primeiro, na ordem em que foram escritos. Se o mesmo produto é fixado por duas regras, vale a primeira.
2. O restante é ordenado pela soma dos pesos dos boosts que cada produto cumpre (maior primeiro). Empates mantêm a ordem original da busca.
3. Se alguma regra tem bury_out_of_stock, produtos sem estoque vão para o fim. Produtos fixados nunca são rebaixados.

Boosts (boosts[].field)

Um field fora desta lista é aceito, não gera erro e simplesmente nunca casa.

Conceitos importantes

Termo de busca

Em context search a regra vale quando o termo digitado é igual ao search_term, comparando sem acento e sem diferenciar maiúsculas ("Tênis" = "tenis"). Não é busca por trecho: "tenis" não casa com "tenis esportivo".

Escopo e campos descartados

Os campos que não pertencem ao context são zerados: em category o search_term é descartado; em search o category_id; em global os dois.

Rascunho não é validado

Uma regra em draft pode estar incompleta (sem termo, sem categoria). As validações de search_term, category_id, limite de 200 e termo duplicado só rodam quando status é active.

Quando a mudança aparece

A vitrine guarda as regras ativas em cache por até 1 minuto; mudanças feitas por estas rotas limpam o cache, então costumam aparecer em segundos.

Endpoints

Erros comuns

• Mandar PUT parcial. O PUT regrava tudo: omitir status volta a regra para draft, omitir include_children vira false, omitir pins/boosts esvazia as listas. Leia a regra, mude o campo e reenvie o objeto inteiro.
• Ativar sem alvo. Regra search ativa sem search_term, ou category ativa sem category_id, é recusada com 422.
• Duas regras ativas para o mesmo termo. A segunda leva 422 duplicate search term.
• Fixar um produto e não vê-lo. Se ele não passa pelas regras de visibilidade da loja (inativo, oculto, sem estoque onde a loja esconde esgotados), a regra não o traz.
• field com erro de digitação. on-sale ou onsale não dão erro, só não fazem nada.
• Esperar 404. PUT num id inexistente responde 500; DELETE num id inexistente responde 200.
• Status inventado. Fora de draft, active e archived o banco recusa e a resposta é 500.

Próximos passos