VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: conhecimento do assistente

Busca e índice da base

Testa a busca na base de conhecimento e refaz o índice de busca por significado.

A busca da base acha o texto certo para uma pergunta de cliente. Estas rotas servem para testar essa busca e para refazer o índice que a torna inteligente.

Buscar na base

Testa a busca da base com uma frase, do jeito que o assistente faria. Serve para conferir se um texto novo é encontrado.

POST/api/v1/admin/whatsapp/kb/searchAdmin

Busca na base de conhecimento

Corpo da requisição

querystringobrigatório
Frase a procurar. Obrigatória.
vendor_iduuid
Restringe ao seller (entradas dele e as da loja toda). Omitido, busca em tudo.
top_kintegerpadrão: 5
Quantos resultados devolver. Zero, negativo ou omitido usa 5; acima de 50 vira 50.

Exemplo de requisição (Buscar na base)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/kb/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quanto tempo tenho para trocar",
    "top_k": 3
  }'

Resposta (Buscar na base)

200Resultados
json
{
  "hits": [
    {
      "entry": {
        "id": "6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07",
        "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
        "title": "Política de troca",
        "content_text": "Aceitamos troca em até 7 dias corridos após o recebimento, com a etiqueta original e sem sinais de uso.",
        "embedding_model": "text-embedding-3-small",
        "has_embedding": true,
        "tags": [
          "troca",
          "pós-venda"
        ],
        "status": "A",
        "created_at": "2026-10-11T14:02:10.114233Z",
        "updated_at": "2026-10-11T14:02:10.114233Z"
      },
      "similarity": 0.6,
      "source": "ilike"
    }
  ]
}

Campos da resposta

hitsarray

Resultados, do mais ao menos relevante.

entryobject
A entrada encontrada, com os mesmos campos da listagem.
similaritynumber
Relevância de 0 a 1; quanto maior, melhor.
distancenumber
Distância bruta da busca por significado. Ausente na busca por texto.
sourcestring
vectorilike
Como o resultado foi achado.

Erros (Buscar na base)

StatusQuandoCorpo
400Corpo que não é JSON ou query vazia.{"error":"whatsapp kb: query required"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Dois jeitos de buscar

Com a IA e o índice ligados, a busca é por significado (source = vector). Sem eles, cai numa busca por trecho de texto (source = ilike), que dá nota fixa 0,6 para quem casa no título e 0,3 para quem casa só no texto. Só entradas ativas entram.

Refazer o índice

Refaz o índice de busca por significado das entradas ativas que ainda não têm índice ou que foram indexadas com outro modelo. Rode depois de ligar a IA na loja ou de trocar o modelo.

POST/api/v1/admin/whatsapp/kb/regenerateAdmin

Refaz o índice de busca da base

Corpo da requisição

vendor_iduuid
Refaz só as entradas desse seller. Omitido, refaz todas.
idsarray
Aceito pelo corpo, mas hoje ignorado: a rota sempre refaz tudo que está pendente.

Exemplo de requisição (Refazer o índice)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/kb/regenerate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta (Refazer o índice)

200Índice refeito
json
{
  "regenerated": 3
}

Campos da resposta

regeneratedinteger
Quantas entradas ganharam índice. É 0 quando nada estava pendente ou quando o banco não suporta busca por significado.

Erros (Refazer o índice)

StatusQuandoCorpo
400Corpo presente com tipo errado (por exemplo vendor_id numérico).{"error":"invalid request body: ..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500Falha ao refazer.{"error":"Failed to regenerate embeddings: ..."}
503A loja não tem IA configurada.{"error":"OpenAI key not set in module settings"}
Pode demorar

A chamada fica aberta enquanto cada entrada é indexada, uma a uma. Em bases grandes, prefira filtrar por vendor_id. Falhas em entradas isoladas são puladas em silêncio e só reduzem o número devolvido em regenerated.

Refazer o índice (alias)

É a mesma operação de /kb/regenerate, com o nome mais explícito. As duas rotas fazem exatamente a mesma coisa.

POST/api/v1/admin/whatsapp/kb/regenerate-embeddingsAdmin

Refaz o índice de busca da base (alias)

Corpo da requisição

vendor_iduuid
Refaz só as entradas desse seller. Omitido, refaz todas.
idsarray
Aceito pelo corpo, mas hoje ignorado: a rota sempre refaz tudo que está pendente.

Exemplo de requisição (Refazer o índice (alias))

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/kb/regenerate-embeddings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta (Refazer o índice (alias))

200Índice refeito
json
{
  "regenerated": 3
}

Campos da resposta

regeneratedinteger
Quantas entradas ganharam índice. É 0 quando nada estava pendente ou quando o banco não suporta busca por significado.

Erros (Refazer o índice (alias))

StatusQuandoCorpo
400Corpo presente com tipo errado (por exemplo vendor_id numérico).{"error":"invalid request body: ..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500Falha ao refazer.{"error":"Failed to regenerate embeddings: ..."}
503A loja não tem IA configurada.{"error":"OpenAI key not set in module settings"}
Qual nome usar

Use /regenerate-embeddings em integrações novas. /regenerate continua existindo por compatibilidade.

Veja também

  • Entradas da base
  • Visão geral
Anterior
Entradas da base
Próxima
Correções de marca
Nesta página
  • Buscar na base
  • Exemplo de requisição (Buscar na base)
  • Resposta (Buscar na base)
  • Erros (Buscar na base)
  • Refazer o índice
  • Exemplo de requisição (Refazer o índice)
  • Resposta (Refazer o índice)
  • Erros (Refazer o índice)
  • Refazer o índice (alias)
  • Exemplo de requisição (Refazer o índice (alias))
  • Resposta (Refazer o índice (alias))
  • Erros (Refazer o índice (alias))
  • Veja também