Busca
Como a busca da loja é administrada pela API: busca global do painel, estatísticas de busca, motor e reindexação, redirecionamentos por termo, com o mapa das rotas.
"Busca" tem dois lados na Venddor. O lado do cliente é a caixa de busca da vitrine (documentada na seção de busca da vitrine). Esta seção é o lado do administrador: a busca global do painel (a caixa que acha usuário, pedido e produto de uma vez), as estatísticas do que os clientes procuram, o controle do índice que alimenta a busca e os redirecionamentos por termo, que levam quem busca "frete grátis" direto à página certa.
Como funciona
Do termo digitado ao resultado
O cliente digita na vitrine, a plataforma normaliza o termo (minúsculas, sem acento, espaços colapsados), consulta o motor de busca e responde com produtos. Se existir um redirecionamento ativo para o termo normalizado, a resposta traz também um redirect_url, e a vitrine leva o cliente para lá. Cada busca enviada é registrada (termo, número de resultados, clique), e uma rotina por hora consolida os números do dia anterior.
Motores de busca
engine | Quando | Reindexar |
|---|---|---|
meilisearch | A loja tem um servidor Meilisearch configurado e acessível. | Sim |
vector | Sem Meilisearch, mas com o índice vetorial de produtos ativo. | Sim |
database | Nenhum dos dois: a busca consulta direto a tabela de produtos. | Não, não há índice para reconstruir |
GET /search/meili/status diz qual motor está em uso.
Conceitos-chave
Termo normalizado (term_norm)
Redirecionamentos e estatísticas usam o termo em forma normalizada: minúsculas, sem acentos, espaços repetidos viram um. " Frete Grátis " e "frete gratis" são o mesmo termo.
Taxas são frações
zero_results_pct e ctr vêm como fração de 0 a 1, não percentual: 0.1 é 10%.
Exclusão de redirecionamento
Apagar um redirecionamento é lógico, mas o termo continua ocupado: não é possível criar outro redirecionamento para o mesmo termo depois de apagar o primeiro. Prefira desativar (is_active: false).
Endpoints
| Método | Caminho | Para que serve | Auth |
|---|---|---|---|
| GET | /api/v1/admin/search | Busca global do painel | admin |
| GET | /api/v1/admin/search/analytics/summary | Resumo das buscas da vitrine | admin |
| GET | /api/v1/admin/search/analytics/terms | Termos mais buscados ou sem resultado | admin |
| GET | /api/v1/admin/search/meili/status | Estado do motor de busca | admin |
| POST | /api/v1/admin/search/meili/ensure-index | Cria ou reconfigura o índice do Meilisearch | admin |
| POST | /api/v1/admin/search/meili/reindex | Reconstrói o índice em segundo plano | admin |
| POST | /api/v1/admin/search/reindex | Reconstrói o índice de texto completo (síncrono) | admin |
| GET | /api/v1/admin/search/redirects | Lista os redirecionamentos | admin |
| POST | /api/v1/admin/search/redirects | Cria um redirecionamento | admin |
| PUT | /api/v1/admin/search/redirects/{id} | Altera um redirecionamento | admin |
| DELETE | /api/v1/admin/search/redirects/{id} | Apaga um redirecionamento | admin |
Erros comuns
- Esperar resultados da busca global com uma letra só: com menos de 2 caracteres a resposta é 200 e vazia.
- Interpretar
totalscomo o total de achados: é a quantidade de itens devolvidos (limitada porlimit). - Esperar que um grupo de resultado venha quando o usuário não tem o privilégio: o grupo vem vazio, sem erro.
- Criar um redirecionamento sem
is_activee estranhar que não funciona. - Tentar recriar um redirecionamento depois de apagado: 409
term already exists. - Chamar
meili/reindexe esperar que termine na resposta: é 202, o trabalho segue em segundo plano. Járeindex(semmeili) é síncrono. - Receber 403
module_disablednos controlesmeili/*: o módulosearch-managementestá desligado na loja.