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

Documentos da base

Lista, cria (texto ou arquivo), lê, altera e exclui os documentos da base de conhecimento da loja.

Cada documento é um texto em Markdown (política de troca, manual, FAQ) que a plataforma divide em trechos e indexa. Quando está published, a VI cita os trechos relevantes e diz de qual documento vieram. Limites da base: 500 documentos e 50 MB no total.

Listar documentos

Devolve todos os documentos não excluídos, do mais novo para o mais antigo, sem o texto (só os metadados).

GET/api/v1/admin/intelligence/kb/documentsAdmin

Listar documentos

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

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

Resposta

200Documentos

json

{
  "documents": [
    {
      "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"
    }
  ],
  "total": 1,
  "vector_online": true
}

Campos da resposta

documentsarray

Documentos, com os campos abaixo.

iduuid

Id do documento.

vendor_iduuid

Vendedor dono do documento. Nulo = loja inteira.

titlestring

Título.

source_typestring

manualfaqpdfdocx

Origem do conteúdo.

statusstring

processingdraftpublishedarchivedfailed

Estado (veja o ciclo de vida na visão geral).

chunk_countinteger

Quantidade de trechos em que o texto foi dividido. Zero enquanto indexa.

size_bytesinteger

Tamanho do texto, em bytes.

errorstring

Motivo da falha, quando status é failed. Nulo nos demais.

created_atstring

RFC 3339.

totalinteger

Quantidade devolvida.

vector_onlineboolean

false quando a busca por significado está indisponível e a busca cai para texto simples.

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"]}`

Criar um documento

Aceita dois formatos. Em JSON, você envia o texto em Markdown. Em multipart/form-data, você envia um PDF ou DOCX (até 30 MB) e a plataforma converte para Markdown. A resposta volta na hora com status: processing; a indexação segue em segundo plano.

POST/api/v1/admin/intelligence/kb/documentsAdmin

Criar documento (texto ou arquivo)

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

titlestring

Título. Obrigatório em JSON. No upload, sem título usa-se o nome do arquivo.

content_mdstring

Só JSON. Texto em Markdown, não vazio.

source_typestringpadrão: manual

manualfaq

Só JSON. Outro valor vira manual.

filefile

Só upload. PDF ou DOCX. Outra extensão é tratada como PDF.

vendor_iduuid

Restringe o documento a um vendedor. Sem valor, vale para a loja.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Política de troca",
    "source_type": "faq",
    "content_md": "# Troca\nAceitamos trocas em até 7 dias após o recebimento."
  }'

Resposta

201Documento recebido

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "processing",
  "chunk_count": 0,
  "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	Título ou conteúdo vazio, corpo ilegível, upload ilegível ou falha ao converter.	`{"error":"title required"}`, `{"error":"content required"}`, `{"error":"falha ao converter o documento"}`
409	Já há 500 documentos ou 50 MB na base, ou o mesmo conteúdo já existe.	`{"error":"intelligence: KB limit reached (500 docs / 50MB) ..."}` ou `{"error":"intelligence: identical document already exists (content hash)"}`
413	Arquivo acima de 30 MB.	`{"error":"arquivo excede o limite"}` (devolvido em português)

Ler um documento

Devolve os metadados de um documento. Use para acompanhar o status depois de criar ou alterar.

GET/api/v1/admin/intelligence/kb/documents/{id}Admin

Ler 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 "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documento

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "draft",
  "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"]}`
404	Documento inexistente ou excluído.	`{"error":"sql: no rows in result set"}`

Alterar um documento

Troca o título e/ou o texto. O documento volta para processing e, se você mandou content_md, é reindexado e termina em draft (ou continua published, se já estava).

PUT/api/v1/admin/intelligence/kb/documents/{id}Admin

Alterar título e texto

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id do documento.

Corpo da requisição

titlestring

Novo título. Vazio mantém o atual.

content_mdstring

Novo texto em Markdown. Vazio mantém o atual e não dispara a reindexação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Política de troca e devolução",
    "content_md": "# Troca\nAceitamos trocas em até 7 dias."
  }'

Resposta

200Documento em reindexação

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca e devolução",
  "source_type": "faq",
  "status": "processing",
  "chunk_count": 0,
  "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	Corpo ilegível.	`{"error":"invalid request body"}`
500	`id` inválido.	`{"error":"..."}`

Excluir um documento

Exclui o documento (exclusão lógica) e remove os trechos indexados dele. A partir daí ele deixa de aparecer em listagens e buscas.

DELETE/api/v1/admin/intelligence/kb/documents/{id}Admin

Excluir 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 DELETE "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído

json

{ "ok": true }

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"]}`
500	`id` inválido.	`{"error":"..."}`

Veja também

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

Documentos da base

Lista, cria (texto ou arquivo), lê, altera e exclui os documentos da base de conhecimento da loja.

Listar documentos

Devolve todos os documentos não excluídos, do mais novo para o mais antigo, sem o texto (só os metadados).

GET/api/v1/admin/intelligence/kb/documentsAdmin

Listar documentos

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

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

Resposta

200Documentos

json

{
  "documents": [
    {
      "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"
    }
  ],
  "total": 1,
  "vector_online": true
}

Campos da resposta

documentsarray

Documentos, com os campos abaixo.

iduuid

Id do documento.

vendor_iduuid

Vendedor dono do documento. Nulo = loja inteira.

titlestring

Título.

source_typestring

manualfaqpdfdocx

Origem do conteúdo.

statusstring

processingdraftpublishedarchivedfailed

Estado (veja o ciclo de vida na visão geral).

chunk_countinteger

Quantidade de trechos em que o texto foi dividido. Zero enquanto indexa.

size_bytesinteger

Tamanho do texto, em bytes.

errorstring

Motivo da falha, quando status é failed. Nulo nos demais.

created_atstring

RFC 3339.

totalinteger

Quantidade devolvida.

vector_onlineboolean

false quando a busca por significado está indisponível e a busca cai para texto simples.

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"]}`

Criar um documento

POST/api/v1/admin/intelligence/kb/documentsAdmin

Criar documento (texto ou arquivo)

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

titlestring

Título. Obrigatório em JSON. No upload, sem título usa-se o nome do arquivo.

content_mdstring

Só JSON. Texto em Markdown, não vazio.

source_typestringpadrão: manual

manualfaq

Só JSON. Outro valor vira manual.

filefile

Só upload. PDF ou DOCX. Outra extensão é tratada como PDF.

vendor_iduuid

Restringe o documento a um vendedor. Sem valor, vale para a loja.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/kb/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Política de troca",
    "source_type": "faq",
    "content_md": "# Troca\nAceitamos trocas em até 7 dias após o recebimento."
  }'

Resposta

201Documento recebido

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "processing",
  "chunk_count": 0,
  "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	Título ou conteúdo vazio, corpo ilegível, upload ilegível ou falha ao converter.	`{"error":"title required"}`, `{"error":"content required"}`, `{"error":"falha ao converter o documento"}`
409	Já há 500 documentos ou 50 MB na base, ou o mesmo conteúdo já existe.	`{"error":"intelligence: KB limit reached (500 docs / 50MB) ..."}` ou `{"error":"intelligence: identical document already exists (content hash)"}`
413	Arquivo acima de 30 MB.	`{"error":"arquivo excede o limite"}` (devolvido em português)

Ler um documento

Devolve os metadados de um documento. Use para acompanhar o status depois de criar ou alterar.

GET/api/v1/admin/intelligence/kb/documents/{id}Admin

Ler 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 "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Documento

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca",
  "source_type": "faq",
  "status": "draft",
  "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"]}`
404	Documento inexistente ou excluído.	`{"error":"sql: no rows in result set"}`

Alterar um documento

Troca o título e/ou o texto. O documento volta para processing e, se você mandou content_md, é reindexado e termina em draft (ou continua published, se já estava).

PUT/api/v1/admin/intelligence/kb/documents/{id}Admin

Alterar título e texto

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id do documento.

Corpo da requisição

titlestring

Novo título. Vazio mantém o atual.

content_mdstring

Novo texto em Markdown. Vazio mantém o atual e não dispara a reindexação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Política de troca e devolução",
    "content_md": "# Troca\nAceitamos trocas em até 7 dias."
  }'

Resposta

200Documento em reindexação

json

{
  "id": "58d16a4f-f586-49e7-a1c2-3cdff78fa381",
  "vendor_id": null,
  "title": "Política de troca e devolução",
  "source_type": "faq",
  "status": "processing",
  "chunk_count": 0,
  "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	Corpo ilegível.	`{"error":"invalid request body"}`
500	`id` inválido.	`{"error":"..."}`

Excluir um documento

Exclui o documento (exclusão lógica) e remove os trechos indexados dele. A partir daí ele deixa de aparecer em listagens e buscas.

DELETE/api/v1/admin/intelligence/kb/documents/{id}Admin

Excluir 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 DELETE "$BASE_URL/api/v1/admin/intelligence/kb/documents/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído

json

{ "ok": true }

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"]}`
500	`id` inválido.	`{"error":"..."}`