API atual/Referência completa/SEO, testes A/B e envio de arquivos

Reordenar produtos para o cliente

Reordena uma lista de produtos conforme o perfil de compra do cliente logado, quando a loja ligou a personalização, ou responde que a ordem original deve ser mantida.

Em uma listagem (home, categoria, busca), a ordem normal é a editorial da loja. A personalização reordena os mesmos produtos para colocar primeiro o que combina com o gosto de cada cliente (marcas, categorias e faixa de preço que ele costuma comprar). Você manda os ids da listagem, o servidor devolve a ordem personalizada, e você apenas reordena a tela. Não adiciona nem remove produtos.

O recurso é opcional: a loja liga ou desliga a personalização por tela (home, category, search). O cliente pode também recusar a personalização na conta (LGPD), e a recusa é verificada antes de qualquer leitura do perfil dele. Uma parte dos clientes pode ficar num grupo de controle, que sempre vê a ordem original (para medir o efeito).

Reordenar

POST/api/v1/storefront/personalize/rerankCliente

Reordena uma lista de produtos para o cliente logado

Exige cliente logado: sem token a API responde 401 missing authorization header. Para um cliente logado, há dois resultados: 200 com a ordem personalizada, ou 204 sem corpo, que significa "mantenha a ordem original". O 204 acontece quando o cliente recusou a personalização, a tela está desligada na loja, ele está no grupo de controle, ainda não há dados suficientes sobre ele ou a lista não pôde ser personalizada.

Produtos fixados (pinned_ids) ficam no lugar. A lista aceita até 96 ids.

Cabeçalhos

Authorizationstringobrigatório

Bearer <token> do cliente.

Content-Typestringobrigatório

application/json.

Corpo da requisição

surfacestringobrigatório

homecategorysearch

Tela onde a lista aparece. Qualquer outro valor equivale a "desligado" e devolve 204.

product_idsarrayobrigatório

Ids (UUID) dos produtos da listagem, na ordem editorial atual. No máximo 96.

pinned_idsarray

Ids (UUID) que devem permanecer na posição original (por exemplo, destaques pagos).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/personalize/rerank" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "surface": "category",
  "product_ids": [
    "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
    "2a6541bf-d5b0-4a2e-ad7b-1183af189d42"
  ],
  "pinned_ids": []
}'

Resposta

200Ordem personalizada

json

{
  "order": [
    "2a6541bf-d5b0-4a2e-ad7b-1183af189d42",
    "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"
  ],
  "personalized": true
}

204Mantenha a ordem original

http

HTTP/1.1 204 No Content

O exemplo de 200 ilustra o formato: o cliente de teste da documentação sempre recebeu 204.

Campos da resposta

orderarray

Os mesmos ids de product_ids, na ordem sugerida.

personalizedboolean

Sempre true quando há corpo.

Erros

Status	Quando	Corpo
204	Manter a ordem original (cliente recusou, tela desligada, controle, sem perfil)	corpo vazio
400	Corpo que não é JSON	`{"error":"invalid body","detail":"invalid character 'x' looking for beginning of value"}`
401	Sem token	`{"error":"missing authorization header"}`
413	Mais de 96 ids	`{"error":"too many ids","detail":"max 96"}`

Veja também