API atual/Referência completa/Venddor Intelligence

Alertas e histórico

Dicas proativas da VI para a tela do seller e o histórico de sugestões da loja.

A VI pode tomar a iniciativa: quando o seller abre uma tela, ela avalia o que vale dizer e, se houver algo, grava uma dica na conversa. Esta página tem três rotas: a dica proativa dentro da conversa, a avaliação de alertas por tela e o histórico de sugestões da loja. Para a tela do seller (caminhos /vendor/...), a dica sai sempre dos dados do seu seller: pedidos pendentes, estoque crítico de produtos que vendem, capital parado em produtos sem venda e um resumo da loja.

Dica proativa na conversa

Escolhe uma dica para a tela (alternando entre as candidatas, sem repetir a última mensagem da conversa) e a grava como mensagem da VI. Cria a conversa se session_id não vier. Para o seller sempre há ao menos o resumo da loja, então a resposta costuma trazer uma mensagem. O texto é reescrito pela VI com tom variado, mas os números vêm do seu seller. Quando a requisição traz entity_kind e entity_id (tela de um registro específico) e esse registro tem algo a apontar, a dica é uma análise do registro, e o trigger_id não começa com vendor.inicio..

POST/api/v1/vendor/intelligence/triggers/proactive-messageSeller

Dica proativa na conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

session_iduuid

Conversa onde gravar a dica. Sem valor (ou com um id que não existe), uma nova é criada. O corpo inteiro é opcional.

urlstring

Caminho da tela, como /vendor/products.

entity_kindstring

Tipo do registro aberto. Valores: product, order, customer, vendor.

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.

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/vendor/intelligence/triggers/proactive-message" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "/vendor/orders",
  "title": "Pedidos"
}'

Resposta

200Dica gravada

json

{
  "session_id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "message": {
    "id": "6e3f1a2b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
    "role": "assistant",
    "content": "Você tem 3 pedidos pendentes aguardando processamento. Quer que eu abra a lista?",
    "trigger_id": "vendor.inicio.pedidos_pendentes",
    "cta_url": "/vendor/orders?status=pending",
    "created_at": "2026-10-11T21:20:00Z"
  }
}

200Nada a dizer

json

{
  "session_id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "message": null
}

Campos da resposta

session_iduuid

Conversa usada.

messageobject

Mensagem gravada (id, role, content, trigger_id, cta_url, created_at), ou null quando a única candidata repetiria a última mensagem da conversa ou o recurso está desligado.

message.trigger_idstring

Qual regra gerou a dica. Para o seller, começa com vendor.inicio. (por exemplo vendor.inicio.pedidos_pendentes, vendor.inicio.estoque_critico_giro, vendor.inicio.estoque_parado_capital, vendor.inicio.loja_vazia_onboarding, vendor.inicio.saudacao_resumo).

message.cta_urlstring

Caminho do painel para agir. Pode faltar (o resumo da loja não tem).

memory_proposalsarray

Propostas de memória sugeridas a partir de dicas que o usuário recusou várias vezes. Só aparece quando há alguma.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`

Alertas para a tela

Avalia as regras de alerta da tela e devolve os que disparam, o mais importante em principal e os demais em others. O mecanismo só funciona com proactive_nudges_enabled ligado (padrão: desligado). As regras de alerta existentes são das telas do administrador; para telas /vendor/... a resposta é normalmente principal: null. Para o seller, prefira a dica proativa acima.

POST/api/v1/vendor/intelligence/triggers/evaluateSeller

Alertas para a tela atual

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

urlstring

Caminho da tela, como /vendor/products.

entity_kindstring

Tipo do registro aberto. Valores: product, order, customer, vendor.

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.

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/vendor/intelligence/triggers/evaluate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "/vendor/products"
}'

Resposta

200Sem alertas

json

{
  "principal": null,
  "others": [],
  "total": 0
}

Campos da resposta

principalobject

Alerta de maior prioridade, ou null. Quando existe: id, trigger_id, domain, feature, title, body, severity, mode (sugere ou executa), cta_url, route, executed.

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 token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`

Histórico de sugestões

Devolve as sugestões proativas recentes da loja, inclusive as dispensadas, da mais nova para a mais antiga. O histórico serve no máximo 100 itens ao todo.

GET/api/v1/vendor/intelligence/insights/historySeller

Histórico de sugestões

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

daysintegerpadrão: 90

Janela em dias. Padrão 90; acima de 365 volta a 90.

limitintegerpadrão: 20

Itens por página. Padrão 20; valor acima de 100 é ignorado e vale o padrão.

offsetintegerpadrão: 0

Itens a pular. Com offset 100 ou mais a lista vem vazia.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/insights/history?days=30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Histórico

json

{
  "days": 30,
  "insights": [
    {
      "id": "9dc40175-6dec-4b8c-aaba-013b258c0455",
      "target_user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "topic": "returning_customer_rate",
      "title": "Taxa de clientes recorrentes em 0%",
      "body": "Em 7 dias, 0 das 3 vendas foram de clientes recorrentes.",
      "severity": "warning",
      "cta_url": "/admin/customers",
      "created_at": "2026-10-11T12:05:19.232149Z"
    }
  ],
  "total": 1
}

Campos da resposta

daysinteger

Janela usada.

totalinteger

Quantidade devolvida nesta página.

insights[].iduuid

Id da sugestão.

insights[].target_user_iduuid

Usuário a quem a sugestão se destinava.

insights[].topicstring

Assunto (código).

insights[].titlestring

Título.

insights[].bodystring

Texto.

insights[].severitystring

Gravidade.

insights[].cta_urlstring

Caminho do painel para agir. Pode faltar.

insights[].created_atstring

RFC 3339.

insights[].seen_atstring

RFC 3339. Quando foi vista. Pode faltar.

insights[].dismissed_atstring

RFC 3339. Quando foi dispensada. Pode faltar.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
500	Falha ao consultar o histórico.	`{"error":"..."}`

Veja também

API atual/Referência completa/Venddor Intelligence

Alertas e histórico

Dicas proativas da VI para a tela do seller e o histórico de sugestões da loja.

Dica proativa na conversa

POST/api/v1/vendor/intelligence/triggers/proactive-messageSeller

Dica proativa na conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

session_iduuid

Conversa onde gravar a dica. Sem valor (ou com um id que não existe), uma nova é criada. O corpo inteiro é opcional.

urlstring

Caminho da tela, como /vendor/products.

entity_kindstring

Tipo do registro aberto. Valores: product, order, customer, vendor.

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.

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/vendor/intelligence/triggers/proactive-message" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "/vendor/orders",
  "title": "Pedidos"
}'

Resposta

200Dica gravada

json

{
  "session_id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "message": {
    "id": "6e3f1a2b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
    "role": "assistant",
    "content": "Você tem 3 pedidos pendentes aguardando processamento. Quer que eu abra a lista?",
    "trigger_id": "vendor.inicio.pedidos_pendentes",
    "cta_url": "/vendor/orders?status=pending",
    "created_at": "2026-10-11T21:20:00Z"
  }
}

200Nada a dizer

json

{
  "session_id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "message": null
}

Campos da resposta

session_iduuid

Conversa usada.

messageobject

Mensagem gravada (id, role, content, trigger_id, cta_url, created_at), ou null quando a única candidata repetiria a última mensagem da conversa ou o recurso está desligado.

message.trigger_idstring

message.cta_urlstring

Caminho do painel para agir. Pode faltar (o resumo da loja não tem).

memory_proposalsarray

Propostas de memória sugeridas a partir de dicas que o usuário recusou várias vezes. Só aparece quando há alguma.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`

Alertas para a tela

POST/api/v1/vendor/intelligence/triggers/evaluateSeller

Alertas para a tela atual

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

urlstring

Caminho da tela, como /vendor/products.

entity_kindstring

Tipo do registro aberto. Valores: product, order, customer, vendor.

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.

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/vendor/intelligence/triggers/evaluate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "/vendor/products"
}'

Resposta

200Sem alertas

json

{
  "principal": null,
  "others": [],
  "total": 0
}

Campos da resposta

principalobject

Alerta de maior prioridade, ou null. Quando existe: id, trigger_id, domain, feature, title, body, severity, mode (sugere ou executa), cta_url, route, executed.

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 token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`

Histórico de sugestões

Devolve as sugestões proativas recentes da loja, inclusive as dispensadas, da mais nova para a mais antiga. O histórico serve no máximo 100 itens ao todo.

GET/api/v1/vendor/intelligence/insights/historySeller

Histórico de sugestões

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

daysintegerpadrão: 90

Janela em dias. Padrão 90; acima de 365 volta a 90.

limitintegerpadrão: 20

Itens por página. Padrão 20; valor acima de 100 é ignorado e vale o padrão.

offsetintegerpadrão: 0

Itens a pular. Com offset 100 ou mais a lista vem vazia.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/insights/history?days=30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Histórico

json

{
  "days": 30,
  "insights": [
    {
      "id": "9dc40175-6dec-4b8c-aaba-013b258c0455",
      "target_user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "topic": "returning_customer_rate",
      "title": "Taxa de clientes recorrentes em 0%",
      "body": "Em 7 dias, 0 das 3 vendas foram de clientes recorrentes.",
      "severity": "warning",
      "cta_url": "/admin/customers",
      "created_at": "2026-10-11T12:05:19.232149Z"
    }
  ],
  "total": 1
}

Campos da resposta

daysinteger

Janela usada.

totalinteger

Quantidade devolvida nesta página.

insights[].iduuid

Id da sugestão.

insights[].target_user_iduuid

Usuário a quem a sugestão se destinava.

insights[].topicstring

Assunto (código).

insights[].titlestring

Título.

insights[].bodystring

Texto.

insights[].severitystring

Gravidade.

insights[].cta_urlstring

Caminho do painel para agir. Pode faltar.

insights[].created_atstring

RFC 3339.

insights[].seen_atstring

RFC 3339. Quando foi vista. Pode faltar.

insights[].dismissed_atstring

RFC 3339. Quando foi dispensada. Pode faltar.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
500	Falha ao consultar o histórico.	`{"error":"..."}`