API atual/Referência completa/WhatsApp Commerce: conhecimento do assistente

Busca e vetores

Testa a busca por significado na base de conhecimento do seller e reconstrói os vetores quando a IA é ligada ou trocada.

Estas rotas são ferramentas de manutenção. search mostra o que o assistente encontraria para uma pergunta, útil para conferir se as entradas estão bem escritas. regenerate recalcula os vetores das entradas que ainda não têm (por exemplo, criadas antes de a IA ser configurada).

Testar a busca

POST/api/v1/vendor/whatsapp/kb/searchSeller

Busca as entradas mais parecidas com uma pergunta

Considera só as entradas active do seller. Com a IA configurada e vetores disponíveis, ordena por proximidade de significado (source: "vector"). Caso contrário, usa busca por trecho de texto (source: "ilike"), que exige palavras presentes na entrada.

Corpo da requisição

querystringobrigatório

A pergunta, como o cliente a escreveria.

top_kintegerpadrão: 5

Quantos resultados devolver. De 1 a 50; acima de 50 vale 50, e zero ou negativo vale 5.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/kb/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "posso trocar se não servir?",
  "top_k": 3
}'

Resposta

200Resultados

json

{
  "hits": [
    {
      "entry": {
        "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
        "title": "Política de troca",
        "content_text": "Aceitamos trocas em até 7 dias corridos, com a nota fiscal e a etiqueta.",
        "has_embedding": true,
        "tags": ["troca", "devolução"],
        "status": "active",
        "created_at": "2026-10-02T13:00:00Z",
        "updated_at": "2026-10-02T13:00:00Z"
      },
      "similarity": 0.82,
      "distance": 0.18,
      "source": "vector"
    }
  ]
}

Campos da resposta

hitsarray

Resultados, do mais ao menos parecido. Lista vazia se nada combina.

hits[].entryobject

A entrada, com os campos de Entradas.

hits[].similaritynumber

De 0 a 1; quanto maior, mais parecido.

hits[].distancenumber

Distância bruta da busca por vetor. Ausente em ilike.

hits[].sourcestring

vectorilike

Como o resultado foi achado.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	`query` vazia	`{"error":"whatsapp kb: query required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas

Reconstruir os vetores

POST/api/v1/vendor/whatsapp/kb/regenerateSeller

Recalcula os vetores das entradas que precisam

Recalcula o vetor das entradas do seller que não têm vetor ou cujo vetor veio de um modelo diferente do atual. Entradas em dia não são tocadas. O corpo é opcional.

Corpo da requisição

idsarray

Aceito, mas hoje não limita a reconstrução: ela cobre todas as entradas do seller que precisam.

vendor_iduuid

Ignorado para sellers: vale o seller do token.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/kb/regenerate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reconstrução concluída

json

{ "regenerated": 4 }

Campos da resposta

regeneratedinteger

Quantas entradas ganharam um vetor novo. 0 quando tudo já estava em dia.

Erros

Status	Quando	Corpo
400	Corpo presente com tipos errados	`{"error":"invalid request body: ..."}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas
503	A loja não tem a chave do serviço de IA	`{"error":"..."}`
500	Falha na reconstrução	`{"error":"Failed to regenerate embeddings: ..."}`

Reconstruir os vetores (alias)

POST/api/v1/vendor/whatsapp/kb/regenerate-embeddingsSeller

Mesmo que regenerate, com o nome longo

É a mesma operação de POST /kb/regenerate, com o mesmo corpo opcional, a mesma resposta e os mesmos erros. Existe por compatibilidade com clientes antigos.

Corpo da requisição

idsarray

Aceito e ignorado, como em regenerate.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/kb/regenerate-embeddings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reconstrução concluída

json

{ "regenerated": 0 }

Erros

Os mesmos de regenerate.

Veja também

API atual/Referência completa/WhatsApp Commerce: conhecimento do assistente

Busca e vetores

Testa a busca por significado na base de conhecimento do seller e reconstrói os vetores quando a IA é ligada ou trocada.

Testar a busca

POST/api/v1/vendor/whatsapp/kb/searchSeller

Busca as entradas mais parecidas com uma pergunta

Corpo da requisição

querystringobrigatório

A pergunta, como o cliente a escreveria.

top_kintegerpadrão: 5

Quantos resultados devolver. De 1 a 50; acima de 50 vale 50, e zero ou negativo vale 5.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/kb/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "posso trocar se não servir?",
  "top_k": 3
}'

Resposta

200Resultados

json

{
  "hits": [
    {
      "entry": {
        "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
        "title": "Política de troca",
        "content_text": "Aceitamos trocas em até 7 dias corridos, com a nota fiscal e a etiqueta.",
        "has_embedding": true,
        "tags": ["troca", "devolução"],
        "status": "active",
        "created_at": "2026-10-02T13:00:00Z",
        "updated_at": "2026-10-02T13:00:00Z"
      },
      "similarity": 0.82,
      "distance": 0.18,
      "source": "vector"
    }
  ]
}

Campos da resposta

hitsarray

Resultados, do mais ao menos parecido. Lista vazia se nada combina.

hits[].entryobject

A entrada, com os campos de Entradas.

hits[].similaritynumber

De 0 a 1; quanto maior, mais parecido.

hits[].distancenumber

Distância bruta da busca por vetor. Ausente em ilike.

hits[].sourcestring

vectorilike

Como o resultado foi achado.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	`query` vazia	`{"error":"whatsapp kb: query required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas

Reconstruir os vetores

POST/api/v1/vendor/whatsapp/kb/regenerateSeller

Recalcula os vetores das entradas que precisam

Recalcula o vetor das entradas do seller que não têm vetor ou cujo vetor veio de um modelo diferente do atual. Entradas em dia não são tocadas. O corpo é opcional.

Corpo da requisição

idsarray

Aceito, mas hoje não limita a reconstrução: ela cobre todas as entradas do seller que precisam.

vendor_iduuid

Ignorado para sellers: vale o seller do token.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/kb/regenerate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reconstrução concluída

json

{ "regenerated": 4 }

Campos da resposta

regeneratedinteger

Quantas entradas ganharam um vetor novo. 0 quando tudo já estava em dia.

Erros

Status	Quando	Corpo
400	Corpo presente com tipos errados	`{"error":"invalid request body: ..."}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas
503	A loja não tem a chave do serviço de IA	`{"error":"..."}`
500	Falha na reconstrução	`{"error":"Failed to regenerate embeddings: ..."}`

Reconstruir os vetores (alias)

POST/api/v1/vendor/whatsapp/kb/regenerate-embeddingsSeller

Mesmo que regenerate, com o nome longo

É a mesma operação de POST /kb/regenerate, com o mesmo corpo opcional, a mesma resposta e os mesmos erros. Existe por compatibilidade com clientes antigos.

Corpo da requisição

idsarray

Aceito e ignorado, como em regenerate.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/kb/regenerate-embeddings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reconstrução concluída

json

{ "regenerated": 0 }

Erros

Os mesmos de regenerate.