Pedir recomendações

Você manda o momento, o lugar e o contexto do comprador; volta uma recomendação com os produtos completos, prontos para mostrar.

A requisição

const decision = await crossup.tryGetRecommendations({
  surface: "cart",                        // ao adicionar ao carrinho
  placementKey: "cart-frequently-bought", // sua etiqueta do lugar, para rastreabilidade
  contextItemId: added.id,                // o produto recém-adicionado
  cartItems: cart.lines.map(toCartItem),  // o carrinho, do jeito que está
});

O que cada momento precisa: Os cinco momentos.

RecommendationSurface

obrigatório

pdp, cart (ao adicionar ao carrinho), carousel (a página do carrinho), checkout, in-checkout ou success-page.

string

obrigatório

Uma etiqueta que você define para saber de onde saiu a requisição. Serve para a sua rastreabilidade; não muda a recomendação.

string

O produto de partida. Obrigatório em e .

CartItem[]

{ item_id, variant_id, quantity } por linha. Omitido é o mesmo que vazio. Obrigatório nos momentos de carrinho.

Visitor | false

Um visitante só para esta requisição, ou false para não mandá-lo. Por padrão, o da instância.

isShooterSurface(surface) diz se o momento parte de um produto.

O que volta

Volta a recomendação (na API, Decision: a lista de produtos recomendados para aquele momento).

decision.decision_id   // único por resposta; os sinais o referenciam
decision.results       // em ordem, com position a partir de 1
decision.reason_codes  // por que veio assim
decision.context       // o produto ou o carrinho que você mandou

const { product } = decision.results[0];
product?.item.title                // por idioma: { pt: "Camiseta" }
product?.variants[0]?.price        // valor como texto, ou sem preço
product?.availability[0]?.sellable // um texto, nunca um booleano

product traz item, categorias, variantes com preço e disponibilidade: basta para mostrá-lo. Se não deu para lê-lo, não vem e esse resultado é omitido. Não há pontuação: a ordem é o ranking.

A descrição viaja como a plataforma a manda. A Nuvemshop manda HTML: sanitize antes de inseri-la.

Ler o catálogo

Para um resultado sem product, ou um produto fora da recomendação:

const product = await crossup.tryGetCatalogItem("itm_…"); // ou null

O título é por idioma, sellable é um texto e uma quantidade ausente não é zero: Ler um item do catálogo.

Reportar sinais

O que vem depois de mostrar a recomendação.

Os cinco momentos

O que a requisição de cada momento precisa.

​A requisição

​O que volta

​Ler o catálogo

Reportar sinais

Os cinco momentos

A requisição

O que volta

Ler o catálogo