Selos de produto
Como funcionam os selos visuais nos produtos (Novo, Oferta, Últimas unidades), a ligação manual ou por regra automática e o mapa das rotas.
Um selo (sticker) é uma etiqueta desenhada por cima da foto do produto: "Novo", "Oferta", "Frete grátis", "Últimas unidades". Você cria o selo uma vez, define como ele aparece e escolhe em quais produtos ele vale, de duas formas: à mão, produto a produto, ou por regra automática, em que a plataforma decide sozinha quais produtos merecem o selo e atualiza a lista com o tempo.
Como funciona
Ciclo de uso
- Criar o selo
POST /stickerscom o nome interno, o texto que o cliente vê e a aparência (cores, posição, onde mostrar). - Escolher os produtos
À mão, com
POST /stickers/{id}/products; ou por regra, comPUT /stickers/{id}/rule. - Conferir
GET /stickers/{id}/productslista os produtos com o selo;GET /stickers/{id}/assignmentsmostra os que vieram da regra e por que.
Selo manual e selo por regra
Modo (assignment_mode) | Como os produtos entram |
|---|---|
manual | Você liga e desliga cada produto. |
rule | A plataforma avalia uma regra e mantém a lista. Reavalia a cada 15 minutos; low_stock e best_seller também reagem em poucos segundos a mudança de estoque e a novos pedidos. |
Um selo em modo regra pode ter janela de validade (starts_at e ends_at): fora dela, a avaliação remove todos os produtos ligados por regra.
Regras disponíveis
rule_type | Quais produtos recebem o selo | Parâmetros (rule_params) |
|---|---|---|
best_seller | Os mais vendidos de cada categoria raiz na janela, com ao menos 1 unidade vendida. | top_n (1 a 10, padrão 3), window_days (7 a 90, padrão 30) |
low_stock | Produtos com controle de estoque e saldo entre 1 e max_qty. | max_qty (mínimo 1, padrão 3) |
lowest_price_90d | Produtos cujo preço atual é o menor dos últimos 90 dias, com pelo menos 30 dias de histórico e algum preço mais alto no período. | nenhum |
free_shipping | Produtos marcados com frete grátis. | nenhum |
new_arrival | Produtos criados nos últimos days dias. | days (mínimo 1, padrão 14) |
on_promotion | Produtos alcançados por uma promoção de catálogo ativa. | nenhum |
Só entram produtos ativos e não excluídos.
Conceitos-chave
Estilo do selo
style é T (texto, o padrão), I (imagem) ou P (pictograma). O P é aceito pela API mas a vitrine o desenha como texto.
Aparência
appearance é um objeto livre que a vitrine lê para desenhar o selo. Chaves usadas pelo painel: bg_color, text_color, radius, opacity, padding, font_size, position (canto do card, como tl para superior esquerdo) e image_url. A plataforma guarda o objeto sem validar as chaves.
Onde aparece
display_on liga e desliga o selo por contexto: product_card (lista), pdp (página do produto) e quickview (visualização rápida). Todos ligados por padrão.
Textos
name_admin é o nome interno do painel. name_desktop é o texto no computador (se vazio na criação, repete o nome interno) e name_mobile é o texto no celular.
Selos de seller
Um selo pode pertencer a um seller (vendor_id). A lista aceita vendor_id e marketplace_only=true para separar.
Endpoints
| Método | Caminho | Para que serve | Auth |
|---|---|---|---|
| GET | /api/v1/admin/stickers | Lista os selos | admin |
| POST | /api/v1/admin/stickers | Cria um selo | admin |
| GET | /api/v1/admin/stickers/{id} | Consulta um selo | admin |
| PUT | /api/v1/admin/stickers/{id} | Altera um selo | admin |
| DELETE | /api/v1/admin/stickers/{id} | Apaga um selo | admin |
| GET | /api/v1/admin/stickers/{id}/products | Lista os produtos com o selo | admin |
| POST | /api/v1/admin/stickers/{id}/products | Liga um produto ao selo | admin |
| DELETE | /api/v1/admin/stickers/{id}/products/{product_id} | Desliga um produto do selo | admin |
| PUT | /api/v1/admin/stickers/{id}/rule | Define o modo e a regra automática | admin |
| POST | /api/v1/admin/stickers/{id}/evaluate | Reavalia a regra agora | admin |
| GET | /api/v1/admin/stickers/{id}/assignments | Lista os produtos ligados e o motivo | admin |
Erros comuns
- Criar o selo e não ver nada na vitrine: ele precisa de produtos ligados e
statusA. - Esperar que o selo apareça em todo produto da loja de um seller: selo de seller só vale nos produtos dele.
- Ligar à mão um produto que a regra também escolhe: a avaliação passa o vínculo para a regra, e ele some quando a regra deixar de valer.
- Mudar para
manualesperando manter a lista da regra: os produtos ligados por regra são removidos. - Passar
statusem palavras: sóAeDsão aceitos. - Esperar que apagar um selo tenha desfazer: é definitivo.
- Esquecer que a lista de selos não tem paginação: todos vêm de uma vez.