VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Venddor Intelligence: memória e conhecimento

Memórias de negócio

Cria, lista, altera, arquiva, exclui e exporta as memórias que orientam as respostas da VI.

Uma memória é uma instrução ou um fato curto que a VI deve respeitar sempre. Há três naturezas: rule (regra, "nunca dar mais de 15% de desconto"), preference (preferência, "respostas curtas") e fact (fato, "expedimos até as 15h"). Memórias de scope tenant valem para a loja; as de scope user são pessoais de quem as criou.

Listar memórias

Devolve as memórias que o administrador do token pode ver: todas as da loja mais as pessoais dele. Regras e preferências vêm primeiro; dentro de cada grupo, as mais novas primeiro.

GET/api/v1/admin/intelligence/memoriesAdmin

Listar memórias

Cabeçalhos

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

Parâmetros de consulta

scopestring
tenantuser
Filtra por escopo.
kindstring
rulepreferencefact
Filtra por natureza.
statusstring
activearchived
Filtra por estado. Sem filtro, vêm ativas e arquivadas.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/intelligence/memories?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Memórias
json
{
  "memories": [
    {
      "id": "f747c050-9052-4c58-8b44-e594a04694d9",
      "scope": "tenant",
      "kind": "fact",
      "content": "O horário limite de expedição da loja é 15h em dias úteis.",
      "source": "user_explicit",
      "status": "active",
      "surfaces": ["admin", "seller", "site"],
      "created_at": "2026-10-11T21:07:37.478564Z"
    }
  ],
  "total": 1
}

Campos da resposta

memoriesarray
Memórias, com os campos abaixo.
iduuid
Id da memória.
scopestring
tenantuser
Onde vale.
user_iduuid
Dono, quando scope é user.
kindstring
rulepreferencefact
Natureza da memória.
contentstring
Texto da memória.
structuredobject
Só em rule: regra em formato conferível (veja o corpo da criação).
sourcestring
user_explicitvi_suggestedledger_derived
Origem.
statusstring
activearchived
Estado.
surfacesarray
Superfícies onde vale: site, admin, seller.
superseded_byuuid
Presente quando uma regra mais nova a substituiu.
created_atstring
RFC 3339.
totalinteger
Quantidade devolvida.

Erros

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

Criar uma memória

Grava uma nova memória ativa. Para rule, você pode enviar structured com a regra em forma conferível; se existir uma regra ativa com a mesma entity, field e target, a antiga é marcada como substituída.

POST/api/v1/admin/intelligence/memoriesAdmin

Criar uma memória

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

scopestringobrigatório
tenantuser
tenant vale para a loja inteira; user só para você.
kindstringobrigatório
rulepreferencefact
Natureza.
contentstringobrigatório
Texto, em linguagem natural. Não pode ser vazio.
structuredobject
Só para rule. Campos: entity (promotion, product ou coupon), field (discount_pct, price_cents ou margin_pct), operator (max, min ou never), value (número) e target (brand e/ou category_id, ambos opcionais). Exemplo: máximo de 15% de desconto em promoções da marca X.
sourcestringpadrão: user_explicit
user_explicitvi_suggestedledger_derived
Origem. Sem valor, user_explicit.
surfacesarray
siteadminseller
Superfícies onde vale. Vazio ou inválido vira as três.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/intelligence/memories" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "tenant",
    "kind": "fact",
    "content": "O horário limite de expedição da loja é 15h em dias úteis.",
    "surfaces": [
      "admin",
      "site"
    ]
  }'

Resposta

201Memória criada
json
{
  "id": "f747c050-9052-4c58-8b44-e594a04694d9",
  "scope": "tenant",
  "kind": "fact",
  "content": "O horário limite de expedição da loja é 15h em dias úteis.",
  "source": "user_explicit",
  "status": "active",
  "surfaces": ["admin", "seller", "site"],
  "created_at": "2026-10-11T21:07:37.478564Z"
}

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}
400Corpo ilegível, scope ou kind inválido, content vazio ou source inválido.{"error":"intelligence: invalid scope \"x\""}, {"error":"intelligence: invalid kind ..."}, {"error":"intelligence: content required"}
409Já existem 200 memórias ativas na loja.{"error":"intelligence: active memory limit reached (200)..."}

Exportar

Baixa as memórias da loja (scope tenant, ativas e arquivadas) em um arquivo JSON. Serve para backup e para atender pedidos de dados (LGPD).

GET/api/v1/admin/intelligence/memories/exportAdmin

Exportar em JSON

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/memories/export" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo vi-memorias.json
json
{
  "memories": [
    {
      "id": "f747c050-9052-4c58-8b44-e594a04694d9",
      "scope": "tenant",
      "kind": "fact",
      "content": "O horário limite de expedição da loja é 15h em dias úteis.",
      "source": "user_explicit",
      "status": "active",
      "surfaces": ["admin", "seller", "site"],
      "created_at": "2026-10-11T21:07:37.478564Z"
    }
  ],
  "total": 1
}

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}
Memórias pessoais ficam de fora

O arquivo não inclui as memórias de scope user, nem as suas. Para ver as pessoais use a listagem. A resposta traz Content-Disposition: attachment; filename="vi-memorias.json".

Alterar ou arquivar

Altera os campos enviados e deixa os outros como estão. É por aqui que se arquiva (status: archived) e se reativa (status: active) uma memória. O escopo não muda.

PATCH/api/v1/admin/intelligence/memories/{id}Admin

Alterar ou arquivar

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 da memória.

Corpo da requisição

contentstring
Novo texto. Vazio é ignorado.
kindstring
rulepreferencefact
Nova natureza. Outro valor é ignorado.
statusstring
activearchived
Novo estado. Outro valor é ignorado.
structuredobject
Nova regra estruturada.
surfacesarray
siteadminseller
Novas superfícies. Se ausente, não muda.

Exemplo de requisição

bash
curl -X PATCH "$BASE_URL/api/v1/admin/intelligence/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "archived"
  }'

Resposta

200Memória atualizada
json
{
  "id": "f747c050-9052-4c58-8b44-e594a04694d9",
  "scope": "tenant",
  "kind": "fact",
  "content": "O horário limite de expedição da loja é 15h em dias úteis.",
  "source": "user_explicit",
  "status": "archived",
  "surfaces": ["admin", "seller", "site"],
  "created_at": "2026-10-11T21:07:37.478564Z"
}

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}
400Corpo ilegível.{"error":"invalid request body"}
500id inválido ou memória inexistente (a rota não responde 404).{"error":"..."}
Reativar respeita o teto

O teto de 200 memórias ativas é conferido só na criação. Reativar arquivadas via PATCH não é bloqueado.

Excluir

Por padrão faz a exclusão lógica: a memória some das listagens e fica arquivada. Com hard=true apaga de vez (para pedidos de eliminação de dados). Só alcança memórias da loja ou suas.

DELETE/api/v1/admin/intelligence/memories/{id}Admin

Excluir uma memória

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id da memória.

Parâmetros de consulta

hardbooleanpadrão: false
true apaga definitivamente.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/intelligence/memories/$MEMORY_ID?hard=true" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída
json
{ "ok": true, "hard": true }

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}
500id com formato inválido.{"error":"..."}
Exclusão definitiva

Com hard=true não há como recuperar. Um id de outro usuário ou inexistente também responde 200, sem apagar nada.

Veja também

  • Documentos
  • Visão geral
Anterior
Memória e conhecimento
Próxima
Documentos da base
Nesta página
  • Listar memórias
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar uma memória
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exportar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar ou arquivar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também