API atual/Referência completa/Venddor Intelligence: memória e conhecimento

Publicar, buscar e reindexar

Publica e arquiva documentos, testa a busca antes de publicar e reindexa a base inteira.

Criar um documento não o coloca no ar. Você testa a busca com o documento ainda em draft, confere que os trechos fazem sentido e só então publica. Arquivar tira o documento de uso sem excluí-lo.

Publicar

Muda o status para published: o documento passa a alimentar as respostas da VI, o atendimento e a loja. A rota não confere o estado atual, então publicar um documento ainda em processing ou failed é aceito; espere ele chegar a draft antes.

POST/api/v1/admin/intelligence/kb/documents/{id}/publishAdmin

Publicar um documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id do documento.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID/publish" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documento publicado

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "published",
  "chunk_count": 1,
  "size_bytes": 39,
  "error": null,
  "created_at": "2026-10-11T21:07:37.540659Z"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`id` inválido ou documento inexistente.	`{"error":"..."}`

Arquivar

Muda o status para archived. O documento sai das respostas e das buscas, mas continua na listagem e pode voltar com Publicar.

POST/api/v1/admin/intelligence/kb/documents/{id}/archiveAdmin

Arquivar um documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id do documento.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID/archive" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documento arquivado

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "archived",
  "chunk_count": 1,
  "size_bytes": 39,
  "error": null,
  "created_at": "2026-10-11T21:07:37.540659Z"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`id` inválido ou documento inexistente.	`{"error":"..."}`

Testar a busca

Faz a busca que a VI faria e devolve os melhores trechos. Diferente da busca real, esta inclui documentos em draft, para você conferir a indexação antes de publicar. Documentos arquivados e excluídos não entram.

POST/api/v1/admin/intelligence/kb/searchAdmin

Testar a busca

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

querystringobrigatório

Pergunta ou palavras-chave. Vazio devolve lista vazia.

vendor_iduuid

Restringe aos documentos desse vendedor mais os da loja inteira.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "em quantos dias posso trocar?"
  }'

Resposta

200Trechos encontrados

json

{
  "degraded": false,
  "results": [
    {
      "document_id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
      "title": "Política de troca",
      "section": "Troca",
      "chunk_text": "# Troca\nAceitamos trocas em até 7 dias.",
      "score": 0.66
    }
  ]
}

Campos da resposta

degradedboolean

true quando a busca por significado estava fora do ar e foi usado um casamento de texto simples.

resultsarray

Até 5 trechos, do mais ao menos relevante.

results[].document_iduuid

Documento de origem.

results[].titlestring

Título do documento.

results[].sectionstring

Cabeçalho Markdown mais próximo do trecho. Pode faltar.

results[].chunk_textstring

Texto do trecho.

results[].scorenumber

Relevância. Maior é melhor; a escala depende do modo (degraded).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo ilegível.	`{"error":"invalid request body"}`

Reindexar

Enfileira a reindexação de todos os documentos draft e published. Use depois de uma mudança no serviço de busca. A resposta volta na hora; o trabalho segue em segundo plano.

POST/api/v1/admin/intelligence/kb/reindexAdmin

Reindexar a base

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/reindex" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Enfileirado

json

{ "queued": 12 }

Campos da resposta

queuedinteger

Quantidade de documentos enfileirados.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`

Veja também

Documentos

API atual/Referência completa/Venddor Intelligence: memória e conhecimento

Publicar, buscar e reindexar

Publica e arquiva documentos, testa a busca antes de publicar e reindexa a base inteira.

Publicar

POST/api/v1/admin/intelligence/kb/documents/{id}/publishAdmin

Publicar um documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id do documento.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID/publish" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documento publicado

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "published",
  "chunk_count": 1,
  "size_bytes": 39,
  "error": null,
  "created_at": "2026-10-11T21:07:37.540659Z"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`id` inválido ou documento inexistente.	`{"error":"..."}`

Arquivar

Muda o status para archived. O documento sai das respostas e das buscas, mas continua na listagem e pode voltar com Publicar.

POST/api/v1/admin/intelligence/kb/documents/{id}/archiveAdmin

Arquivar um documento

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id do documento.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID/archive" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documento arquivado

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "archived",
  "chunk_count": 1,
  "size_bytes": 39,
  "error": null,
  "created_at": "2026-10-11T21:07:37.540659Z"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`id` inválido ou documento inexistente.	`{"error":"..."}`

Testar a busca

POST/api/v1/admin/intelligence/kb/searchAdmin

Testar a busca

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

querystringobrigatório

Pergunta ou palavras-chave. Vazio devolve lista vazia.

vendor_iduuid

Restringe aos documentos desse vendedor mais os da loja inteira.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "em quantos dias posso trocar?"
  }'

Resposta

200Trechos encontrados

json

{
  "degraded": false,
  "results": [
    {
      "document_id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
      "title": "Política de troca",
      "section": "Troca",
      "chunk_text": "# Troca\nAceitamos trocas em até 7 dias.",
      "score": 0.66
    }
  ]
}

Campos da resposta

degradedboolean

true quando a busca por significado estava fora do ar e foi usado um casamento de texto simples.

resultsarray

Até 5 trechos, do mais ao menos relevante.

results[].document_iduuid

Documento de origem.

results[].titlestring

Título do documento.

results[].sectionstring

Cabeçalho Markdown mais próximo do trecho. Pode faltar.

results[].chunk_textstring

Texto do trecho.

results[].scorenumber

Relevância. Maior é melhor; a escala depende do modo (degraded).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo ilegível.	`{"error":"invalid request body"}`

Reindexar

Enfileira a reindexação de todos os documentos draft e published. Use depois de uma mudança no serviço de busca. A resposta volta na hora; o trabalho segue em segundo plano.

POST/api/v1/admin/intelligence/kb/reindexAdmin

Reindexar a base

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/reindex" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Enfileirado

json

{ "queued": 12 }

Campos da resposta

queuedinteger

Quantidade de documentos enfileirados.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`

Veja também

Documentos