VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Aprendizados do assistente

Lições

Lista as lições do assistente de IA e aprova, rejeita ou desativa cada uma.

Uma lição é uma regra que o assistente de IA da loja aprendeu a partir dos próprios erros (veja a visão geral). Use a lista para ver o que está em teste, o que espera aprovação e o que está valendo, e use as três ações para decidir. Aprovar uma lição a torna ativa por 90 dias; rejeitar a descarta; desativar tira do ar uma lição que estava valendo.

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

Lista as lições da loja e as globais

Devolve as lições da sua loja mais as globais. Não há paginação.

Parâmetros de consulta

statusstring
candidatetestingactivepending_approvalrejectedretired
Um ou mais status separados por vírgula (active,pending_approval). Valores desconhecidos são ignorados; sem filtro válido, vêm todos.
scopestring
storeglobal
Só lições da loja ou só as globais. Outro valor é ignorado.

Exemplo de requisição (listar)

bash
curl "$BASE_URL/api/v1/admin/ai-learning/lessons?status=pending_approval" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Lições retornadas
json
{
  "auto_promote": false,
  "lessons": [
    {
      "id": 62,
      "scope": "store",
      "text": "Quando o cliente pedir o status de um pedido, informe o status atual e não prometa prazos que não constam no pedido.",
      "pattern_key": "prazo_nao_prometido",
      "status": "pending_approval",
      "evidence_count": 12,
      "distinct_customers": 9,
      "examples": ["Prometeu entrega em 2 dias sem constar no pedido: informe só o prazo do pedido."],
      "eval_result": {
        "fixed": 4,
        "total": 5,
        "regressions": 0,
        "latency_delta_pct": -1.2,
        "baseline_passed": 6,
        "suite_total": 6,
        "rate_before": 0.07,
        "gate": "ok",
        "evaluated_at": "2026-10-11T06:57:49Z"
      },
      "prevented_errors": 0,
      "created_at": "2026-10-09T06:56:24Z",
      "promoted_at": null,
      "can_manage": true
    }
  ]
}

Campos da resposta

auto_promoteboolean
true se a loja ativa sozinha as lições aprovadas no teste.
lessonsarray

Lições. Cada item tem:

idinteger
Id da lição. Número inteiro, não UUID.
scopestring
storeglobal
store: vale só para esta loja. global: vale para todas as lojas e só a equipe da plataforma administra.
textstring
A regra de comportamento em linguagem natural, como o assistente a seguirá.
pattern_keystring
Identificador curto do tipo de erro que originou a lição.
statusstring
candidatetestingpending_approvalactiverejectedretired
Estado da lição (tabela na visão geral).
evidence_countinteger
Quantas ocorrências do erro sustentam a lição.
distinct_customersinteger
Em quantos clientes diferentes o erro apareceu.
examplesarray
Trechos de exemplo do erro, em texto. Pode ser [].
eval_resultobject
Resultado do teste automático da lição, ou null se ainda não foi testada. Traz fixed/total (casos corrigidos de quantos), regressions (casos que pioraram), latency_delta_pct (variação do tempo de resposta, em %), baseline_passed/suite_total (verificações que já passavam), rate_before (taxa de erro antes), gate, note e evaluated_at (RFC 3339).
prevented_errorsinteger
Quantas vezes a lição evitou o erro depois de ativa.
created_atstring
Criação, RFC 3339 UTC.
promoted_atstring
Quando ficou ativa. null se nunca ficou.
approved_bystring
E-mail (ou id) de quem aprovou, rejeitou ou desativou. Omitido se ninguém agiu.
retired_reasonstring
Motivo de rejeição ou desativação. Omitido quando não se aplica.
expires_atstring
Quando a lição ativa expira (90 dias depois da aprovação). Omitido enquanto não está ativa.
can_manageboolean
true se você pode aprovar, rejeitar ou desativar esta lição. Em lição global só é true para a equipe da plataforma.

Erros (listar)

StatusQuandoCorpo de exemplo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
500Falha ao consultar.{"error":"..."}
Texto das lições

O texto (text) e os exemplos são gerados em português pelo sistema, a partir das conversas da loja, e assim são devolvidos. Eles podem citar trechos de conversas: trate como dado interno da loja.

POST/api/v1/admin/ai-learning/lessons/{id}/approveAdmin

Aprova uma lição

Muda uma lição de pending_approval para active, registra quem aprovou e define a expiração em 90 dias. Exige o privilégio manage_settings.

Parâmetros de caminho

idintegerobrigatório
Id da lição (número inteiro).

Exemplo de requisição (aprovar)

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-learning/lessons/62/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta (aprovar)

200Lição atualizada
json
{ "lesson": {
  "id": 62,
  "scope": "store",
  "text": "Quando o cliente pedir o status de um pedido, informe o status atual e não prometa prazos que não constam no pedido.",
  "pattern_key": "prazo_nao_prometido",
  "status": "active",
  "evidence_count": 12,
  "distinct_customers": 9,
  "examples": ["Prometeu entrega em 2 dias sem constar no pedido: informe só o prazo do pedido."],
  "eval_result": {
    "fixed": 4,
    "total": 5,
    "regressions": 0,
    "latency_delta_pct": -1.2,
    "baseline_passed": 6,
    "suite_total": 6,
    "rate_before": 0.07,
    "gate": "ok",
    "evaluated_at": "2026-10-11T06:57:49Z"
  },
  "prevented_errors": 3,
  "created_at": "2026-10-09T06:56:24Z",
  "promoted_at": "2026-10-10T12:00:00Z",
  "approved_by": "dono@minhaloja.example.com",
  "expires_at": "2027-01-08T12:00:00Z",
  "can_manage": true
} }

Devolve a lição já no novo estado, no mesmo formato da listagem.

Erros (aprovar)

StatusQuandoCorpo de exemplo
400id não é um número inteiro positivo.{"error":"invalid id"}
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403Sem o privilégio manage_settings.{"error":"insufficient privileges","required":"manage_settings"}
403Lição global e a conta não é da equipe da plataforma.{"error":"only a platform admin manages global lessons"}
404Lição inexistente, ou de outra loja.{"error":"lesson not found"}
409A lição não está em pending_approval.{"error":"action not allowed in this status"}
500Falha interna ao gravar.{"error":"..."}
POST/api/v1/admin/ai-learning/lessons/{id}/rejectAdmin

Rejeita uma lição

Muda uma lição de candidate, testing ou pending_approval para rejected. Sem reason, o motivo gravado é rejeitada pelo dono. Exige manage_settings.

Parâmetros de caminho

idintegerobrigatório
Id da lição (número inteiro).

Corpo da requisição

reasonstring
Motivo, guardado em retired_reason. Opcional. Sem ele fica um texto padrão.

Exemplo de requisição (rejeitar)

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-learning/lessons/62/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Regra já coberta por outra lição." }'

Resposta (rejeitar)

200Lição atualizada
json
{ "lesson": {
  "id": 62,
  "scope": "store",
  "text": "Quando o cliente pedir o status de um pedido, informe o status atual e não prometa prazos que não constam no pedido.",
  "pattern_key": "prazo_nao_prometido",
  "status": "rejected",
  "evidence_count": 12,
  "distinct_customers": 9,
  "examples": ["Prometeu entrega em 2 dias sem constar no pedido: informe só o prazo do pedido."],
  "eval_result": {
    "fixed": 4,
    "total": 5,
    "regressions": 0,
    "latency_delta_pct": -1.2,
    "baseline_passed": 6,
    "suite_total": 6,
    "rate_before": 0.07,
    "gate": "ok",
    "evaluated_at": "2026-10-11T06:57:49Z"
  },
  "prevented_errors": 0,
  "created_at": "2026-10-09T06:56:24Z",
  "promoted_at": null,
  "approved_by": "dono@minhaloja.example.com",
  "retired_reason": "Regra já coberta por outra lição.",
  "can_manage": true
} }

Devolve a lição já no novo estado, no mesmo formato da listagem.

Erros (rejeitar)

StatusQuandoCorpo de exemplo
400id não é um número inteiro positivo.{"error":"invalid id"}
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403Sem o privilégio manage_settings.{"error":"insufficient privileges","required":"manage_settings"}
403Lição global e a conta não é da equipe da plataforma.{"error":"only a platform admin manages global lessons"}
404Lição inexistente, ou de outra loja.{"error":"lesson not found"}
409A lição não está em candidate, testing nem pending_approval.{"error":"action not allowed in this status"}
500Falha interna ao gravar.{"error":"..."}
POST/api/v1/admin/ai-learning/lessons/{id}/retireAdmin

Desativa uma lição

Muda uma lição de active para retired: o assistente deixa de segui-la. Sem reason, o motivo gravado é desativada pelo dono. Exige manage_settings.

Parâmetros de caminho

idintegerobrigatório
Id da lição (número inteiro).

Corpo da requisição

reasonstring
Motivo, guardado em retired_reason. Opcional. Sem ele fica um texto padrão.

Exemplo de requisição (desativar)

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-learning/lessons/62/retire" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Regra já coberta por outra lição." }'

Resposta (desativar)

200Lição atualizada
json
{ "lesson": {
  "id": 62,
  "scope": "store",
  "text": "Quando o cliente pedir o status de um pedido, informe o status atual e não prometa prazos que não constam no pedido.",
  "pattern_key": "prazo_nao_prometido",
  "status": "retired",
  "evidence_count": 12,
  "distinct_customers": 9,
  "examples": ["Prometeu entrega em 2 dias sem constar no pedido: informe só o prazo do pedido."],
  "eval_result": {
    "fixed": 4,
    "total": 5,
    "regressions": 0,
    "latency_delta_pct": -1.2,
    "baseline_passed": 6,
    "suite_total": 6,
    "rate_before": 0.07,
    "gate": "ok",
    "evaluated_at": "2026-10-11T06:57:49Z"
  },
  "prevented_errors": 3,
  "created_at": "2026-10-09T06:56:24Z",
  "promoted_at": "2026-10-10T12:00:00Z",
  "approved_by": "dono@minhaloja.example.com",
  "retired_reason": "Regra já coberta por outra lição.",
  "expires_at": "2027-01-08T12:00:00Z",
  "can_manage": true
} }

Devolve a lição já no novo estado, no mesmo formato da listagem.

Erros (desativar)

StatusQuandoCorpo de exemplo
400id não é um número inteiro positivo.{"error":"invalid id"}
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403Sem o privilégio manage_settings.{"error":"insufficient privileges","required":"manage_settings"}
403Lição global e a conta não é da equipe da plataforma.{"error":"only a platform admin manages global lessons"}
404Lição inexistente, ou de outra loja.{"error":"lesson not found"}
409A lição não está em active.{"error":"action not allowed in this status"}
500Falha interna ao gravar.{"error":"..."}
Decida com o teste na mão

Antes de aprovar, olhe eval_result: regressions maior que zero significa que a lição piorou algum caso que antes funcionava. Prefira aprovar lições com fixed alto e regressions zero.

Veja também

  • Métricas e execução
  • Visão geral
Anterior
Aprendizados do assistente
Próxima
Métricas e execução
Nesta página
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Exemplo de requisição (aprovar)
  • Resposta (aprovar)
  • Erros (aprovar)
  • Exemplo de requisição (rejeitar)
  • Resposta (rejeitar)
  • Erros (rejeitar)
  • Exemplo de requisição (desativar)
  • Resposta (desativar)
  • Erros (desativar)
  • Veja também