Insights e dicas
O que a Venddor Intelligence avisa sem ser perguntada: insights sobre os números, o briefing diário, alertas por tela e a análise de um registro.
Além de responder perguntas, a VI observa a loja e avisa o administrador do que merece atenção: estoque baixo, queda de receita, clientes que não voltaram. Há quatro mecanismos, com rotas próprias: os insights (cartões curtos por assunto), o briefing diário (a mensagem "Dicas do Dia", chamada de Venddor Pulse nas rotas), os alertas por tela (sugestões que aparecem conforme a página aberta) e a análise de um registro (produto, pedido ou cliente).
Como funciona
Quatro mecanismos
| Mecanismo | Quem recebe | Como chega | Páginas |
|---|---|---|---|
| Insights | Um administrador (target_user_id) | Lista de cartões com assunto, gravidade e link | Insights, Ações |
| Briefing diário | Todos os administradores da loja | Uma mensagem por dia, lida ou não lida por usuário | Briefing, Gerar |
| Alertas por tela | O administrador na tela aberta | Sugestões calculadas na hora, a partir da tela | Alertas |
| Análise de registro | Quem pediu | Lista de sugestões para um produto, pedido ou cliente | Analisar |
Gravidades
Um insight tem severity info (informativo), warning (atenção) ou opportunity (oportunidade).
Conceitos-chave
Privilégios
Insights, alertas e análise aceitam intelligence_use_chat ou view_reports. O briefing aceita view_reports ou manage_settings; gerar ou refazer o briefing exige manage_settings.
Datas
A data de um briefing (analysis_date) é uma data civil AAAA-MM-DD no fuso America/Sao_Paulo, não um instante em UTC. Os campos created_at são RFC 3339 em UTC.
Dados pessoais
A estrutura de tela enviada aos alertas passa por um filtro que remove e-mail, telefone, CPF e CNPJ antes de qualquer uso.
Rotas
Todas exigem Authorization: Bearer $TOKEN de um administrador.
| Método | Caminho (após /api/v1/admin/intelligence) | Para que serve | Página |
|---|---|---|---|
| GET | /insights | Listar os insights de quem chama | insights |
| GET | /insights/history | Histórico da loja | insights |
| GET | /insights/topics | Assuntos disponíveis | insights |
| POST | /insights/run-now | Gerar agora | insights-actions |
| PATCH | /insights/{id}/seen | Marcar como visto | insights-actions |
| PATCH | /insights/{id}/dismiss | Dispensar | insights-actions |
| GET | /venddor-pulse | Listar o briefing diário | pulse |
| GET | /venddor-pulse/{id} | Ler uma edição | pulse |
| GET | /venddor-pulse/unread-count | Contar não lidas | pulse |
| POST | /venddor-pulse/{id}/read | Marcar como lida | pulse |
| DELETE | /venddor-pulse/{id}/read | Marcar como não lida | pulse |
| POST | /venddor-pulse/run | Gerar uma edição | pulse-run |
| POST | /venddor-pulse/backfill | Gerar dias anteriores | pulse-run |
| POST | /triggers/evaluate | Alertas para a tela atual | triggers |
| POST | /triggers/proactive-message | Dica proativa na conversa | triggers |
| GET/POST | /analyze-entity | Analisar um registro | analyze-entity |
Erros comuns
- Chamar
run-nowcom o recurso desligado. Semenable_proactive_insightsa rota responde403. - Esperar alertas por tela de uma loja nova.
proactive_nudges_enablednasce desligado;evaluatedevolve lista vazia até alguém ligar. - Tratar o briefing como lista só de pronto. A lista inclui edições ainda em geração (
generating) ou que falharam (failed). Filtre porgeneration_status. - Chamar
venddor-pulse/runsem querer perder a edição do dia. Por padrãoforceétruee a edição do dia é apagada e refeita. - Paginar o histórico de insights além de 100. O histórico tem teto de 100 itens no total;
offseta partir de 100 devolve vazio. - Esperar
404ao marcar um insight inexistente. As marcações respondem200mesmo assim.