API atual/Referência completa/Aprendizados do assistente

Métricas e execução

Lê as métricas diárias do assistente de IA e dispara o ciclo de aprendizado sob demanda.

Duas operações para acompanhar o assistente. metrics mostra, dia a dia, quantas respostas o assistente deu, em quantas ele precisou refazer a resposta, em quantas ficou em silêncio e quanto demorou, além de quantas lições estão ativas ou esperando aprovação. run dispara agora o ciclo que escreve e testa novas lições; sem ele o ciclo roda sozinho uma vez por dia.

GET/api/v1/admin/ai-learning/metricsAdmin

Lê as métricas do assistente

Parâmetros de consulta

daysintegerpadrão: 7

730

Janela em dias. Só 30 muda o padrão; qualquer outro valor vira 7.

Exemplo de requisição (métricas)

bash

curl "$BASE_URL/api/v1/admin/ai-learning/metrics?days=7" \
  -H "Authorization: Bearer $TOKEN"

Resposta (métricas)

200Métricas retornadas

json

{
  "days": 7,
  "turns": 420,
  "recheck_rate": 0.0905,
  "silence_rate": 0.0214,
  "avg_latency_ms": 5320,
  "findings": 31,
  "fixed_by_recheck_rate": 0.7742,
  "active_lessons": 4,
  "pending_approval": 1,
  "auto_promote": false,
  "by_day": [
    { "day": "2026-10-10", "turns": 63, "recheck_rate": 0.0794, "silence_rate": 0.0159, "avg_latency_ms": 5100, "findings": 4 },
    { "day": "2026-10-11", "turns": 0, "recheck_rate": 0, "silence_rate": 0, "avg_latency_ms": 0, "findings": 0 }
  ],
  "run": { "running": false, "finished_at": "2026-10-11T03:10:00Z", "summary": "..." }
}

Campos da resposta

daysinteger

Janela aplicada (7 ou 30).

turnsinteger

Respostas do assistente na janela (conversas com clientes).

recheck_ratenumber

Fração (0 a 1) das respostas em que a verificação mandou o assistente refazer a resposta.

silence_ratenumber

Fração (0 a 1) em que nenhuma resposta saiu ao cliente (erro, IA indisponível ou resposta vazia).

avg_latency_msinteger

Tempo médio de resposta, em milissegundos.

findingsinteger

Erros detectados nas respostas, que alimentam as lições.

fixed_by_recheck_ratenumber

Fração (0 a 1) dos erros detectados que a própria verificação já corrigiu antes de chegar ao cliente.

active_lessonsinteger

Lições ativas (da loja e globais).

pending_approvalinteger

Lições esperando sua aprovação.

auto_promoteboolean

Aprovação automática ligada na plataforma.

by_dayarray

Uma linha por dia da janela, em ordem crescente, inclusive dias sem conversa (zeros). Os dias seguem o fuso de São Paulo. Cada linha: day (YYYY-MM-DD), turns, recheck_rate, silence_rate, avg_latency_ms, findings.

runobject

Situação do ciclo de aprendizado desta loja: running (boolean), started_at e finished_at (RFC 3339, quando houver) e summary (texto do resultado da última execução).

Erros (métricas)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
500	Falha ao calcular (por exemplo, a loja não identificada).	`{"error":"tenant required"}`

POST/api/v1/admin/ai-learning/runAdmin

Dispara o ciclo de aprendizado agora

Inicia em segundo plano o ciclo desta loja: escrever lições novas a partir dos erros recentes e testar as candidatas. Responde 202 na hora. Só uma execução por loja de cada vez. Exige o privilégio manage_settings. Sem corpo.

Exemplo de requisição (executar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-learning/run" \
  -H "Authorization: Bearer $TOKEN"

Resposta (executar)

202Ciclo iniciado

json

{ "status": "started", "run": { "running": true, "started_at": "2026-10-11T14:00:00Z" } }

409Já está rodando

json

{ "status": "running", "run": { "running": true, "started_at": "2026-10-11T14:00:00Z" } }

Campos da resposta

statusstring

startedrunning

started: foi iniciado agora. running: já havia uma execução em andamento.

runobject

Mesmo formato do campo run das métricas.

Erros (executar)

Status	Quando	Corpo de exemplo
400	A requisição não identifica uma loja.	`{"error":"tenant required"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
409	Já existe uma execução em andamento para a loja.	`{"status":"running","run":{"running":true}}`

Veja também

Métricas e execução

Lê as métricas diárias do assistente de IA e dispara o ciclo de aprendizado sob demanda.

GET/api/v1/admin/ai-learning/metricsAdmin

Lê as métricas do assistente

Parâmetros de consulta

daysintegerpadrão: 7

730

Janela em dias. Só 30 muda o padrão; qualquer outro valor vira 7.

Exemplo de requisição (métricas)

bash

curl "$BASE_URL/api/v1/admin/ai-learning/metrics?days=7" \
  -H "Authorization: Bearer $TOKEN"

Resposta (métricas)

200Métricas retornadas

json

{
  "days": 7,
  "turns": 420,
  "recheck_rate": 0.0905,
  "silence_rate": 0.0214,
  "avg_latency_ms": 5320,
  "findings": 31,
  "fixed_by_recheck_rate": 0.7742,
  "active_lessons": 4,
  "pending_approval": 1,
  "auto_promote": false,
  "by_day": [
    { "day": "2026-10-10", "turns": 63, "recheck_rate": 0.0794, "silence_rate": 0.0159, "avg_latency_ms": 5100, "findings": 4 },
    { "day": "2026-10-11", "turns": 0, "recheck_rate": 0, "silence_rate": 0, "avg_latency_ms": 0, "findings": 0 }
  ],
  "run": { "running": false, "finished_at": "2026-10-11T03:10:00Z", "summary": "..." }
}

Campos da resposta

daysinteger

Janela aplicada (7 ou 30).

turnsinteger

Respostas do assistente na janela (conversas com clientes).

recheck_ratenumber

Fração (0 a 1) das respostas em que a verificação mandou o assistente refazer a resposta.

silence_ratenumber

Fração (0 a 1) em que nenhuma resposta saiu ao cliente (erro, IA indisponível ou resposta vazia).

avg_latency_msinteger

Tempo médio de resposta, em milissegundos.

findingsinteger

Erros detectados nas respostas, que alimentam as lições.

fixed_by_recheck_ratenumber

Fração (0 a 1) dos erros detectados que a própria verificação já corrigiu antes de chegar ao cliente.

active_lessonsinteger

Lições ativas (da loja e globais).

pending_approvalinteger

Lições esperando sua aprovação.

auto_promoteboolean

Aprovação automática ligada na plataforma.

by_dayarray

runobject

Situação do ciclo de aprendizado desta loja: running (boolean), started_at e finished_at (RFC 3339, quando houver) e summary (texto do resultado da última execução).

Erros (métricas)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
500	Falha ao calcular (por exemplo, a loja não identificada).	`{"error":"tenant required"}`

POST/api/v1/admin/ai-learning/runAdmin

Dispara o ciclo de aprendizado agora

Exemplo de requisição (executar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-learning/run" \
  -H "Authorization: Bearer $TOKEN"

Resposta (executar)

202Ciclo iniciado

json

{ "status": "started", "run": { "running": true, "started_at": "2026-10-11T14:00:00Z" } }

409Já está rodando

json

{ "status": "running", "run": { "running": true, "started_at": "2026-10-11T14:00:00Z" } }

Campos da resposta

statusstring

startedrunning

started: foi iniciado agora. running: já havia uma execução em andamento.

runobject

Mesmo formato do campo run das métricas.

Erros (executar)

Status	Quando	Corpo de exemplo
400	A requisição não identifica uma loja.	`{"error":"tenant required"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
409	Já existe uma execução em andamento para a loja.	`{"status":"running","run":{"running":true}}`