API atual/Referência completa/Venddor Intelligence: conversas

Tela atual e trechos

Informa à VI em que tela do painel o administrador está e recolhe trechos interativos já usados.

Quando o administrador pergunta "o que é este campo?" ou "edite este produto", a VI precisa saber onde ele está. Você envia a estrutura da tela (títulos, rótulos de campos, colunas, botões), nunca os valores digitados. Dados pessoais (e-mail, telefone, CPF, CNPJ) são removidos no servidor antes de qualquer uso.

Informar a tela atual

Grava a tela atual na sessão (chave page do contexto). Chame sempre que o administrador mudar de tela. Um corpo vazio limpa o contexto, o que é o comportamento certo quando o painel lateral é fechado.

PUT/api/v1/admin/intelligence/sessions/{id}/page-contextAdmin

Informar a tela atual

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 sessão.

Corpo da requisição

urlstring

Caminho da tela, como /admin/products/abc-123.

entity_kindstring

productordercustomervendor

Tipo do registro aberto.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro (nunca e-mail, telefone ou documento).

titlestring

Título da página.

headingsarray

Títulos de seção visíveis. Lista de strings.

fieldsarray

Rótulos dos campos do formulário, sem valores.

table_columnsarray

Cabeçalhos das colunas das tabelas.

actionsarray

Botões e links de ação principais.

metricsarray

Valores de indicadores visíveis, em texto (Receita: R$ 15.116,00).

tabsarray

Abas da tela.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/page-context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/admin/products",
    "title": "Produtos",
    "table_columns": [
      "Nome",
      "Preço",
      "Estoque"
    ]
  }'

Resposta

200Gravado

json

{ "status": "ok" }

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 que não é JSON.	`{"error":"invalid request body"}`

Recolher um trecho

Algumas respostas da VI trazem um trecho interativo (por exemplo, um formulário de cadastro aberto dentro da conversa). Depois que o administrador salva dentro dele, esta rota reescreve a mensagem gravada para que o trecho apareça recolhido quando a conversa for reaberta.

POST/api/v1/admin/intelligence/sessions/{id}/snippets/{snippetId}/closeAdmin

Recolher um trecho interativo

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 sessão.

snippetIdstringobrigatório

Identificador do trecho, o mesmo que veio no bloco da mensagem.

Corpo da requisição

actionstring

O que o administrador fez no trecho (por exemplo saved). Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/snippets/$SNIPPET_ID/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "saved"
  }'

Resposta

200Recolhido

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	Trecho não encontrado na conversa ou falha ao reescrever (a rota não distingue os casos).	`{"error":"could not close snippet"}`

Veja também

Tela atual e trechos

Informa à VI em que tela do painel o administrador está e recolhe trechos interativos já usados.

Informar a tela atual

PUT/api/v1/admin/intelligence/sessions/{id}/page-contextAdmin

Informar a tela atual

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 sessão.

Corpo da requisição

urlstring

Caminho da tela, como /admin/products/abc-123.

entity_kindstring

productordercustomervendor

Tipo do registro aberto.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro (nunca e-mail, telefone ou documento).

titlestring

Título da página.

headingsarray

Títulos de seção visíveis. Lista de strings.

fieldsarray

Rótulos dos campos do formulário, sem valores.

table_columnsarray

Cabeçalhos das colunas das tabelas.

actionsarray

Botões e links de ação principais.

metricsarray

Valores de indicadores visíveis, em texto (Receita: R$ 15.116,00).

tabsarray

Abas da tela.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/page-context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/admin/products",
    "title": "Produtos",
    "table_columns": [
      "Nome",
      "Preço",
      "Estoque"
    ]
  }'

Resposta

200Gravado

json

{ "status": "ok" }

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 que não é JSON.	`{"error":"invalid request body"}`

Recolher um trecho

POST/api/v1/admin/intelligence/sessions/{id}/snippets/{snippetId}/closeAdmin

Recolher um trecho interativo

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 sessão.

snippetIdstringobrigatório

Identificador do trecho, o mesmo que veio no bloco da mensagem.

Corpo da requisição

actionstring

O que o administrador fez no trecho (por exemplo saved). Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/snippets/$SNIPPET_ID/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "saved"
  }'

Resposta

200Recolhido

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	Trecho não encontrado na conversa ou falha ao reescrever (a rota não distingue os casos).	`{"error":"could not close snippet"}`