Recomendações e compartilhamento
Como a vitrine sugere produtos (para você, quem comprou levou, quem viu também viu, compre junto, listas sugeridas) e como gera links de compartilhamento.
Esta seção reúne as rotas que ajudam o cliente a descobrir produtos sem buscar: os carrosséis da página inicial e da página do produto, o combo "Compre junto", as listas montadas pelo lojista e os links curtos que o cliente compartilha com amigos. Todas são públicas e valem para uma loja (tenant) por vez, exceto onde indicado.
Como funciona
De onde vem cada recomendação
| Rota | Origem do sinal | Quando está vazia |
|---|---|---|
| Para você | Interesse do cliente logado (ou produtos de referência que você envia); sem perfil, os mais vendidos | Nunca por falta de perfil: cai nos mais vendidos |
| Quem comprou também levou | Produtos que aparecem nos mesmos pedidos | Produto novo ou sem pedidos |
| Quem viu também viu | Produtos vistos na mesma sessão de navegação | Produto novo ou sem visitas |
| Compre junto | Combo calculado a partir de pedidos ou montado pelo lojista, com desconto | Recurso desligado ou produto sem combo |
| Produtos parecidos | Semelhança de sentido entre produtos | Produto sem análise e sem visitas |
Fluxo típico de uma página de produto
- Abra a página do produto
Carregue o produto pelas rotas de catálogo da vitrine.
- Avise a visualização
Chame Registrar visualizações. É isso que alimenta o "quem viu também viu".
- Carregue os carrosséis em paralelo
recommendations,also-viewed,fbtesimilar. Cada um é independente: se um vier vazio, esconda só aquele. - Conte a adição do combo
Quando o cliente adiciona o combo ao carrinho, chame
track-addpara o lojista medir a conversão.
Conceitos-chave
Dinheiro
Produtos usam price e list_price em centavos (39990 = R$ 399,90). O combo usa price_cents, total_price_cents, combo_price_cents e savings_cents, também em centavos. Em listas sugeridas, total_price, final_price e kit_price são centavos e discount_pct é um percentual inteiro.
Preço escondido de visitantes
Em lojas que só mostram preço a quem está logado, o visitante recebe price: 0 e price_redacted: true. Se a loja exige login até para navegar, estas rotas respondem 401 shopping_requires_login a quem não tem token.
Cache
As rotas de leitura respondem com Cache-Control: public, max-age=300, stale-while-revalidate=1800: o navegador ou um CDN pode reaproveitar a resposta por 5 minutos. O combo e as listas podem, portanto, demorar alguns minutos para refletir uma mudança do lojista.
Ids e slugs
Os ids de produto são UUID. As rotas recommendations e also-viewed aceitam também o slug do produto no lugar do id. As demais rotas (similar, fbt, view) esperam o UUID.
Endpoints
| Método e caminho | Para quê | Auth | Página |
|---|---|---|---|
GET /api/v1/storefront/recommendations/for-you | Feed "Para você" | Pública | Para você |
GET /api/v1/storefront/products/{id}/recommendations | Quem comprou também levou | Pública | Quem comprou também levou |
GET /api/v1/storefront/products/{id}/also-viewed | Quem viu também viu | Pública | Quem viu também viu |
POST /api/v1/storefront/products/{id}/view | Registrar visualização anônima | Pública | Registrar visualizações |
POST /api/v1/storefront/product-views | Registrar visualização do cliente logado | Cliente | Registrar visualizações |
GET /api/v1/storefront/products/{id}/fbt | Combo Compre junto | Pública | Compre junto |
POST /api/v1/storefront/fbt/{id}/track-add | Contar a adição do combo | Pública | Compre junto |
GET /api/v1/storefront/suggested-lists | Listas sugeridas | Pública (ou cliente) | Listas sugeridas |
GET /api/v1/storefront/suggested-lists/{id} | Uma lista sugerida | Pública (ou cliente) | Listas sugeridas |
POST /api/v1/storefront/share-links | Criar link curto de compartilhamento | Pública | Links de compartilhamento |
GET /api/v1/storefront/share-links/{code}/resolve | Descobrir para onde o link aponta | Pública | Links de compartilhamento |
Erros comuns
- Esperar 404 para um produto inexistente. Com um UUID que não existe,
recommendationsealso-viewedrespondem 200 com lista vazia (recommendations: null). Só um slug desconhecido dá 404. - Chamar
POST /viewcom slug. A rota exige o UUID; slug ou texto qualquer dá 500. - Chamar
POST /product-viewssem token. É a única rota daqui que exige cliente logado (401). - Esquecer o
session_idemPOST /view. Sem o campo e sem o cookiesession_id, a resposta é 400. - Somar
combo_price_centsao carrinho como um item. O combo é só a oferta: você adiciona os produtos dele ao carrinho, um a um. - Ler
discount_pctcomo centavos. É percentual inteiro (10 = 10%). - Mostrar "R$ 0,00" quando
price_redactedétrue. Mostre "Entre para ver o preço".