API atual/Referência completa/Venddor Intelligence: insights e dicas

Alertas por tela

Calcula sugestões para a tela que o administrador está vendo e entrega uma dica proativa dentro da conversa.

Um alerta é uma sugestão ligada à tela: ao abrir a lista de produtos, "3 produtos sem estoque"; ao abrir um cliente VIP, "ele não compra há 60 dias". Você envia a estrutura da tela (o mesmo formato de Tela atual) e recebe o que vale mostrar. O mecanismo só funciona quando proactive_nudges_enabled está ligado (padrão: desligado).

Alertas para a tela

Avalia as regras da tela e devolve os alertas que disparam, o mais importante em principal e os demais em others. Com o mecanismo desligado, ou sem regra para a tela, devolve principal: null.

POST/api/v1/admin/intelligence/triggers/evaluateAdmin

Alertas para a tela atual

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

urlstring

Caminho da tela, como /admin/products.

entity_kindstring

productordercustomervendor

Tipo do registro aberto.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro.

titlestring

Título da página.

headingsarray

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

fieldsarray

Rótulos de campos, sem valores.

table_columnsarray

Cabeçalhos de tabelas.

actionsarray

Botões de ação principais.

metricsarray

Indicadores visíveis, em texto.

tabsarray

Abas da tela.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/triggers/evaluate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/admin/products",
    "title": "Produtos",
    "table_columns": [
      "Nome",
      "Estoque"
    ]
  }'

Resposta

200Alertas

json

{
  "principal": {
    "id": "0b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8",
    "trigger_id": "stock_rupture",
    "domain": "catalog",
    "feature": "products",
    "title": "3 produtos sem estoque",
    "body": "Reponha ou desative a venda para não perder pedidos.",
    "severity": "warning",
    "mode": "sugere",
    "cta_url": "/admin/products?stock_filter=out_of_stock",
    "route": "/admin/products"
  },
  "others": [],
  "total": 1
}

Campos da resposta

principalobject

Alerta de maior prioridade, ou nulo.

principal.iduuid

Id do alerta.

principal.trigger_idstring

Identificador da regra que disparou.

principal.domainstring

Área do painel.

principal.featurestring

Recurso dentro da área.

principal.titlestring

Título.

principal.bodystring

Texto.

principal.severitystring

Gravidade.

principal.modestring

sugereexecuta

sugere (só sugere) ou executa (uma leitura já foi feita sozinha).

principal.cta_urlstring

Caminho do painel para agir. Pode faltar.

principal.routestring

Tela em que o alerta disparou.

principal.executedboolean

true se uma leitura automática rodou. Pode faltar.

othersarray

Demais alertas, no mesmo formato. Vazio quando não há.

totalinteger

Total de alertas, principal incluído.

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

Dica proativa

Escolhe uma dica para a tela (alternando entre as que disparam) e a grava como mensagem da VI na conversa. Cria a sessão se session_id não vier. Com um registro aberto (entity_kind + entity_id), a dica é uma análise desse registro. Pode vir também com propostas de memória (veja abaixo).

POST/api/v1/admin/intelligence/triggers/proactive-messageAdmin

Dica proativa na conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

session_iduuid

Conversa onde gravar a dica. Sem valor, uma nova é criada.

urlstring

Caminho da tela, como /admin/products.

entity_kindstring

productordercustomervendor

Tipo do registro aberto.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro.

titlestring

Título da página.

headingsarray

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

fieldsarray

Rótulos de campos, sem valores.

table_columnsarray

Cabeçalhos de tabelas.

actionsarray

Botões de ação principais.

metricsarray

Indicadores visíveis, em texto.

tabsarray

Abas da tela.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/triggers/proactive-message" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/admin/products",
    "title": "Produtos"
  }'

Resposta

200Dica gravada

json

{
  "session_id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "message": {
    "id": "6e3f1a2b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
    "role": "assistant",
    "content": "Notei 3 produtos sem estoque. Quer ver a lista?",
    "trigger_id": "stock_rupture",
    "cta_url": "/admin/products?stock_filter=out_of_stock",
    "created_at": "2026-10-11T21:20:00Z"
  }
}

200Nada a dizer

json

{ "session_id": "", "message": null }

Campos da resposta

session_iduuid

Conversa usada.

messageobject

Mensagem gravada (id, role, content, trigger_id, cta_url, created_at), ou null quando nada disparou ou a dica já era a última da conversa.

memory_proposalsarray

Propostas de memória: regras que o administrador recusou três vezes ou mais, sugeridas como {trigger_id, scope, kind, content, reason}. Só vira memória se você criar uma (Memórias).

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

Veja também

API atual/Referência completa/Venddor Intelligence: insights e dicas

Alertas por tela

Calcula sugestões para a tela que o administrador está vendo e entrega uma dica proativa dentro da conversa.

Alertas para a tela

Avalia as regras da tela e devolve os alertas que disparam, o mais importante em principal e os demais em others. Com o mecanismo desligado, ou sem regra para a tela, devolve principal: null.

POST/api/v1/admin/intelligence/triggers/evaluateAdmin

Alertas para a tela atual

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

urlstring

Caminho da tela, como /admin/products.

entity_kindstring

productordercustomervendor

Tipo do registro aberto.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro.

titlestring

Título da página.

headingsarray

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

fieldsarray

Rótulos de campos, sem valores.

table_columnsarray

Cabeçalhos de tabelas.

actionsarray

Botões de ação principais.

metricsarray

Indicadores visíveis, em texto.

tabsarray

Abas da tela.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/triggers/evaluate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/admin/products",
    "title": "Produtos",
    "table_columns": [
      "Nome",
      "Estoque"
    ]
  }'

Resposta

200Alertas

json

{
  "principal": {
    "id": "0b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8",
    "trigger_id": "stock_rupture",
    "domain": "catalog",
    "feature": "products",
    "title": "3 produtos sem estoque",
    "body": "Reponha ou desative a venda para não perder pedidos.",
    "severity": "warning",
    "mode": "sugere",
    "cta_url": "/admin/products?stock_filter=out_of_stock",
    "route": "/admin/products"
  },
  "others": [],
  "total": 1
}

Campos da resposta

principalobject

Alerta de maior prioridade, ou nulo.

principal.iduuid

Id do alerta.

principal.trigger_idstring

Identificador da regra que disparou.

principal.domainstring

Área do painel.

principal.featurestring

Recurso dentro da área.

principal.titlestring

Título.

principal.bodystring

Texto.

principal.severitystring

Gravidade.

principal.modestring

sugereexecuta

sugere (só sugere) ou executa (uma leitura já foi feita sozinha).

principal.cta_urlstring

Caminho do painel para agir. Pode faltar.

principal.routestring

Tela em que o alerta disparou.

principal.executedboolean

true se uma leitura automática rodou. Pode faltar.

othersarray

Demais alertas, no mesmo formato. Vazio quando não há.

totalinteger

Total de alertas, principal incluído.

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

Dica proativa

POST/api/v1/admin/intelligence/triggers/proactive-messageAdmin

Dica proativa na conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

session_iduuid

Conversa onde gravar a dica. Sem valor, uma nova é criada.

urlstring

Caminho da tela, como /admin/products.

entity_kindstring

productordercustomervendor

Tipo do registro aberto.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro.

titlestring

Título da página.

headingsarray

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

fieldsarray

Rótulos de campos, sem valores.

table_columnsarray

Cabeçalhos de tabelas.

actionsarray

Botões de ação principais.

metricsarray

Indicadores visíveis, em texto.

tabsarray

Abas da tela.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/triggers/proactive-message" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/admin/products",
    "title": "Produtos"
  }'

Resposta

200Dica gravada

json

{
  "session_id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "message": {
    "id": "6e3f1a2b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
    "role": "assistant",
    "content": "Notei 3 produtos sem estoque. Quer ver a lista?",
    "trigger_id": "stock_rupture",
    "cta_url": "/admin/products?stock_filter=out_of_stock",
    "created_at": "2026-10-11T21:20:00Z"
  }
}

200Nada a dizer

json

{ "session_id": "", "message": null }

Campos da resposta

session_iduuid

Conversa usada.

messageobject

Mensagem gravada (id, role, content, trigger_id, cta_url, created_at), ou null quando nada disparou ou a dica já era a última da conversa.

memory_proposalsarray

Propostas de memória: regras que o administrador recusou três vezes ou mais, sugeridas como {trigger_id, scope, kind, content, reason}. Só vira memória se você criar uma (Memórias).

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