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

Insights proativos

Lista os insights do administrador, o histórico da loja e os assuntos que a VI acompanha.

Um insight é um cartão curto gerado pela VI a partir dos números recentes da loja: título, texto, gravidade e um link para a tela onde agir. Eles são produzidos por uma rotina diária (e sob demanda, em Ações) e ficam na caixa do administrador até serem dispensados.

Listar os insights

Devolve os insights não dispensados destinados ao administrador do token, do mais novo para o mais antigo. Os já vistos continuam na lista, com seen_at preenchido.

GET/api/v1/admin/intelligence/insightsAdmin

Listar os insights de quem chama

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade máxima. Padrão 50; valores acima de 200 ou abaixo de 1 voltam para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/insights?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Insights

json

{
  "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. Vale abrir a tela de clientes para revisar estratégias de retenção.",
      "severity": "warning",
      "cta_url": "/admin/customers",
      "created_at": "2026-10-11T12:05:19.232149Z"
    }
  ],
  "total": 1
}

Campos da resposta

insightsarray

Insights, com os campos abaixo.

iduuid

Id do insight.

target_user_iduuid

Administrador a quem o insight se destina.

topicstring

Assunto (veja a lista de assuntos), como low_inventory.

titlestring

Título curto.

bodystring

Texto do insight, com os números que o justificam.

severitystring

infowarningopportunity

Gravidade.

cta_urlstring

Caminho do painel para agir (por exemplo /admin/customers). Pode faltar.

created_atstring

RFC 3339.

seen_atstring

RFC 3339. Presente depois de marcado como visto.

dismissed_atstring

RFC 3339. Presente depois de dispensado.

totalinteger

Quantidade devolvida.

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

Histórico

Devolve os insights recentes de todos os administradores da loja, inclusive dispensados, para consulta e auditoria. O histórico serve no máximo 100 itens ao todo.

GET/api/v1/admin/intelligence/insights/historyAdmin

Histórico da loja

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (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; valores acima de 100 ou abaixo de 1 voltam para 20.

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/admin/intelligence/insights/history?days=30&limit=20" \
  -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. Vale abrir a tela de clientes para revisar estratégias de retenção.",
      "severity": "warning",
      "cta_url": "/admin/customers",
      "created_at": "2026-10-11T12:05:19.232149Z"
    }
  ],
  "total": 1
}

Campos da resposta

insightsarray

Mesmos campos da lista.

daysinteger

Janela usada.

totalinteger

Quantidade devolvida nesta página.

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

Assuntos

Lista os assuntos que a VI acompanha e quais deles saem em cada dia da semana. Serve para montar filtros e rótulos.

GET/api/v1/admin/intelligence/insights/topicsAdmin

Assuntos disponíveis

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

Resposta

200Assuntos

json

{
  "topics": [
    {
      "id": "low_inventory",
      "display_name": "Low inventory",
      "severity_hint": "warning",
      "cta_url_template": "/admin/products?stock_filter=low_stock",
      "supports_news_rag": false
    }
  ],
  "day_directives": {
    "monday": ["low_inventory", "revenue_dip_vs_last_week", "top_product_momentum"],
    "sunday": ["new_signups_trend", "returning_customer_rate"]
  }
}

Campos da resposta

topics[].idstring

Identificador do assunto, o mesmo de topic nos insights.

topics[].display_namestring

Nome para exibição (em inglês).

topics[].severity_hintstring

Gravidade usual do assunto.

topics[].cta_url_templatestring

Tela do painel para agir sobre o assunto.

topics[].supports_news_ragboolean

true se o assunto pode citar notícias externas.

day_directivesobject

Para cada dia da semana (monday...sunday, mais month_start e month_end), a lista de assuntos do dia.

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

Veja também

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

Insights proativos

Lista os insights do administrador, o histórico da loja e os assuntos que a VI acompanha.

Listar os insights

Devolve os insights não dispensados destinados ao administrador do token, do mais novo para o mais antigo. Os já vistos continuam na lista, com seen_at preenchido.

GET/api/v1/admin/intelligence/insightsAdmin

Listar os insights de quem chama

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade máxima. Padrão 50; valores acima de 200 ou abaixo de 1 voltam para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/insights?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Insights

json

{
  "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. Vale abrir a tela de clientes para revisar estratégias de retenção.",
      "severity": "warning",
      "cta_url": "/admin/customers",
      "created_at": "2026-10-11T12:05:19.232149Z"
    }
  ],
  "total": 1
}

Campos da resposta

insightsarray

Insights, com os campos abaixo.

iduuid

Id do insight.

target_user_iduuid

Administrador a quem o insight se destina.

topicstring

Assunto (veja a lista de assuntos), como low_inventory.

titlestring

Título curto.

bodystring

Texto do insight, com os números que o justificam.

severitystring

infowarningopportunity

Gravidade.

cta_urlstring

Caminho do painel para agir (por exemplo /admin/customers). Pode faltar.

created_atstring

RFC 3339.

seen_atstring

RFC 3339. Presente depois de marcado como visto.

dismissed_atstring

RFC 3339. Presente depois de dispensado.

totalinteger

Quantidade devolvida.

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

Histórico

Devolve os insights recentes de todos os administradores da loja, inclusive dispensados, para consulta e auditoria. O histórico serve no máximo 100 itens ao todo.

GET/api/v1/admin/intelligence/insights/historyAdmin

Histórico da loja

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (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; valores acima de 100 ou abaixo de 1 voltam para 20.

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/admin/intelligence/insights/history?days=30&limit=20" \
  -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. Vale abrir a tela de clientes para revisar estratégias de retenção.",
      "severity": "warning",
      "cta_url": "/admin/customers",
      "created_at": "2026-10-11T12:05:19.232149Z"
    }
  ],
  "total": 1
}

Campos da resposta

insightsarray

Mesmos campos da lista.

daysinteger

Janela usada.

totalinteger

Quantidade devolvida nesta página.

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

Assuntos

Lista os assuntos que a VI acompanha e quais deles saem em cada dia da semana. Serve para montar filtros e rótulos.

GET/api/v1/admin/intelligence/insights/topicsAdmin

Assuntos disponíveis

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

Resposta

200Assuntos

json

{
  "topics": [
    {
      "id": "low_inventory",
      "display_name": "Low inventory",
      "severity_hint": "warning",
      "cta_url_template": "/admin/products?stock_filter=low_stock",
      "supports_news_rag": false
    }
  ],
  "day_directives": {
    "monday": ["low_inventory", "revenue_dip_vs_last_week", "top_product_momentum"],
    "sunday": ["new_signups_trend", "returning_customer_rate"]
  }
}

Campos da resposta

topics[].idstring

Identificador do assunto, o mesmo de topic nos insights.

topics[].display_namestring

Nome para exibição (em inglês).

topics[].severity_hintstring

Gravidade usual do assunto.

topics[].cta_url_templatestring

Tela do painel para agir sobre o assunto.

topics[].supports_news_ragboolean

true se o assunto pode citar notícias externas.

day_directivesobject

Para cada dia da semana (monday...sunday, mais month_start e month_end), a lista de assuntos do dia.

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