SEO, testes A/B e envio de arquivos

Esta seção reúne seis rotas que apoiam a vitrine fora do fluxo principal de compra:

• Resolução de URLs: dado um endereço amigável (/camisetas, /moda/roupas/camisetas/camisa-x/p), descobre qual produto, categoria, página, seller ou post de blog ele representa. É o que um front-end headless precisa para decidir o que desenhar em cada URL.
• Testes A/B da página de produto: a loja pode testar duas versões de um elemento (por exemplo o texto do botão de compra). A API diz a qual versão cada visitante pertence e registra que ele viu o teste.
• Reordenação personalizada: reordena uma listagem de produtos conforme o gosto do cliente logado, quando a loja ligou o recurso.
• Envio de arquivos pelo cliente: o cliente logado anexa documentos e arquivos às próprias conversas.

Como funciona

1. Resolva a URL pedida

   Para cada endereço que o visitante abre, chame Resolver URLs. A resposta diz o tipo (product, category, page, vendor, blog, brand) e o identificador para buscar os dados.

2. Aplique os testes A/B

   Ao abrir a página de produto, leia os testes ativos e desenhe a versão (a ou b) de cada elemento testado. Avise a API uma vez por sessão e teste.

3. Personalize listagens (opcional)

   Com cliente logado, envie os ids dos produtos da listagem para Reordenar e use a ordem devolvida, se vier.

Conceitos-chave

Endereço canônico

O caminho canônico é a URL oficial de uma entidade: o produto camisa-flamengo... pode ter o caminho moda/roupas/camisetas/camisa-flamengo.../p quando a loja usa caminhos por categoria. Se o visitante abre o endereço curto, canonical-resolve devolve redirect_to com o oficial, para o front-end redirecionar (301).

Segmentos reservados

Algumas primeiras partes de caminho pertencem à própria vitrine (por exemplo products e admin). Resolver um caminho que começa por elas devolve 409: é erro do chamador, nunca de dados.

Variante

Cada teste tem duas variantes: a (o que a loja tem hoje) e b (o valor novo, em variant_b_value). Um percentual configurado pela loja leva visitantes à b.

Rotas

Erros comuns

• Usar seo/resolve esperando a entidade. Ele devolve um redirecionamento (/products/slug) e só olha o último segmento do caminho. Para o caminho completo, use canonical-resolve.
• Resolver caminhos reservados. canonical-resolve responde 409 quando o primeiro segmento é de uma rota da vitrine; filtre esses caminhos antes.
• Esquecer o X-Session-ID nos testes A/B. Sem token e sem esse cabeçalho, a lista de testes volta vazia e o registro de exposição responde 400.
• Registrar a exposição a cada renderização. Basta uma vez por sessão e teste; chamadas repetidas são aceitas mas não somam.
• Tratar 204 da reordenação como erro. É o resultado normal quando o cliente recusou personalização, não há perfil suficiente ou a tela está desligada.
• Enviar um arquivo para um destino qualquer. O cliente só envia para user_profile_field (com o próprio id) ou message (de uma conversa dele). Outros destinos respondem 403 owner_not_allowed.

Próximos passos