Busca

A busca é o caminho mais usado para um cliente chegar a um produto. Esta seção documenta as rotas que uma loja virtual ou um aplicativo chama quando o cliente digita no campo de busca: a página de resultados com filtros, a lista de sugestões que aparece enquanto ele digita, a busca por vários termos de uma vez, a busca por foto, os termos em alta e os produtos parecidos.

Todas as rotas são públicas: não exigem login e valem para uma loja (tenant) por vez. O cliente logado recebe a mesma resposta, com algumas diferenças descritas abaixo.

Como funciona

O que acontece em uma busca

1. Normalização. O texto é limpo (caracteres inválidos são removidos) e comparado sem acento e sem diferença entre maiúsculas e minúsculas.
2. Regras da loja. O lojista pode cadastrar sinônimos (buscar "tênis" também acha "sapatilha"), redirecionamentos (o termo "frete" leva a uma página) e destaques (fixar, impulsionar ou rebaixar produtos). Quando há redirecionamento, a resposta traz redirect_url e a lista vem vazia.
3. Busca. A busca é textual (nome, descrição e SKU, inclusive o SKU de uma variação). Em lojas com a busca semântica ligada, produtos de sentido próximo completam a primeira página quando há pouco resultado textual.
4. Visibilidade. Saem do resultado os produtos inativos, de seller inativo ou restrito a um grupo de clientes do qual o cliente não faz parte, sem preço ou sem estoque (quando a loja configurou esconder esses casos).
5. Registro. A busca é gravada para o painel de analytics da loja. A resposta devolve log_id e search_event_id, que você reenvia quando o cliente clica em um resultado (Registrar cliques).

Qual rota usar

Conceitos-chave

Dinheiro

Todo valor monetário é inteiro em centavos: price é o preço de venda, list_price é o preço "de" (riscado), quando existe, e catalog_discount é o desconto por unidade, em centavos, que as promoções de catálogo ativas dão ao produto. O preço que o cliente paga é o que o carrinho calcula; price já considera a faixa de preço do cliente logado nas rotas que a aplicam (veja a página de cada rota).

Preço escondido de visitantes

Algumas lojas só mostram preço a quem está logado (configuração da loja). Nesse caso, para um visitante sem token, price vem 0, list_price vem ausente e o campo price_redacted vem true. Mostre "Entre para ver o preço". Se a loja exige login até para navegar (allow_shopping_unlogged desligado), todas as rotas desta seção respondem 401 shopping_requires_login a quem não está logado.

Estoque e disponibilidade

Cada produto traz quantity (estoque disponível), track_inventory (se a loja controla estoque), out_of_stock_action e zero_price_action. Esses dois últimos dizem o que a loja faz nesses casos: letras da configuração da loja, que o seu cliente de vitrine deve repassar à regra de exibição do botão de compra. Um produto com track_inventory: false está sempre disponível.

Paginação

page (a partir de 1) e per_page (1 a 100, padrão 20). Um per_page fora da faixa volta ao padrão de 20, não é cortado em 100. Uma página além do fim devolve products: [] com o total correto. Veja também Paginação.

Cache

Todas as rotas de leitura desta seção respondem com Cache-Control: public, max-age=300, stale-while-revalidate=1800 e ETag. Um CDN ou o navegador pode servir a mesma resposta por 5 minutos. Consequência: o log_id e o search_event_id de uma resposta guardada em cache são compartilhados por quem a recebeu; para análise por cliente, o impacto é pequeno, mas não conte com ids únicos por visitante.

Quem é o cliente

Mandar o cabeçalho Authorization: Bearer $TOKEN (token de um cliente logado, veja Tokens) é opcional e muda: o preço mostrado (faixa de preço do grupo do cliente, na busca ao vivo), a visibilidade de sellers restritos a um grupo e, se a loja ligou a personalização, a ordem da primeira página. Chaves de API (integrações) precisam do escopo storefront:read na rota principal GET /api/v1/storefront/search.

Endpoints

Erros comuns

• Esperar o catálogo inteiro em GET /search sem parâmetros. Sem q e sem filtros a resposta é vazia de propósito. Use category_id para navegar.
• Tratar per_page=500 como 100. Valores acima de 100 voltam ao padrão (20).
• Usar price como se fosse reais. É centavos. Divida por 100 só na hora de exibir.
• Chamar /live-search a cada tecla sem pausa. Espere 200 a 300 ms depois da última tecla e só chame com o mínimo de caracteres da loja (padrão 2). Abaixo do mínimo a resposta é vazia.
• Não tratar redirect_url. Quando o lojista cadastrou um redirecionamento para o termo, a lista vem vazia e a vitrine deve navegar para o endereço indicado.
• Ignorar price_redacted. Mostrar "R$ 0,00" para um visitante em loja com preço restrito engana o cliente.
• Depender de /search/meili. A rota só funciona em lojas que usam Meilisearch; nas demais responde 503. Para qualquer loja, use /search.

Próximos passos