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

Análises e revisão

Lista as análises de fraude, consulta uma, registra a decisão manual e vê os totais.

Estas rotas formam a fila de revisão do antifraude: a lista com os filtros, o detalhe de uma análise, a decisão do revisor e os totais do painel.

Listar análises

Lista as análises, da mais recente à mais antiga. Use o filtro status=manual_review para a fila de revisão.

GET/api/v1/admin/fraud/analysesAdmin

Lista as análises de fraude

Autenticação: Authorization: Bearer <token> de um administrador com manage_fraud ou manage_orders. Requer o módulo clearsale ativo.

Parâmetros de consulta

statusstring
pendingapprovedrejectedmanual_reviewcancellederrorblockedchallengereview_expired
Estado, em palavra ou letra. Uma palavra desconhecida vira pending em silêncio.
risk_levelstring
lowmediumhigh
low, medium ou high.
order_iduuid
Só a análise de um pedido.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página. Acima de 100 vale 20.

Exemplo de requisição

Resposta

200Análises devolvidas

Campos da resposta

analysesarray | null
Análises da página. null quando não há nenhuma, não uma lista vazia.
analyses[].idinteger
Identificador numérico da análise (não é UUID).
analyses[].order_iduuid
Pedido analisado. Há no máximo uma análise por pedido.
analyses[].scorenumber
Pontuação de risco de 0 (menor risco) a 100 (maior risco).
analyses[].statusstring
pendingapprovedrejectedmanual_reviewcancellederrorblockedchallengereview_expired
Estado da análise (tabela na página inicial).
analyses[].risk_levelstring
lowmediumhigh
low (até 30), medium (até 60) ou high.
analyses[].analysis_idstring
Identificador da análise no ClearSale.
analyses[].clearsale_order_idstring
Identificador do pedido no ClearSale. Omitido se vazio.
analyses[].reasonstring
Motivo da decisão (do ClearSale ou do revisor). Omitido se vazio.
analyses[].reviewed_bystring
Quem decidiu manualmente. Omitido antes disso.
analyses[].reviewed_atstring
Quando decidiu manualmente.
analyses[].raw_responseobject
Resposta bruta do ClearSale, guardada como veio. Pode ser omitida.
analyses[].created_atstring
Criação, RFC 3339 em UTC.
analyses[].updated_atstring
Última alteração.
totalinteger
Total com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"clearsale"} / {"error":"insufficient privileges","required":"manage_fraud"}
500Falha na consulta{"error":"Failed to list analyses"}

Consultar uma análise

Devolve uma análise pelo identificador numérico, com a resposta bruta do ClearSale.

GET/api/v1/admin/fraud/{id}Admin

Consulta uma análise de fraude

Autenticação: Authorization: Bearer <token> de um administrador com manage_fraud ou manage_orders. Requer o módulo clearsale ativo.

Parâmetros de caminho

idintegerobrigatório
Identificador numérico da análise.

Exemplo de requisição

Resposta

200Análise devolvida

Campos da resposta

idinteger
Identificador numérico da análise (não é UUID).
order_iduuid
Pedido analisado. Há no máximo uma análise por pedido.
scorenumber
Pontuação de risco de 0 (menor risco) a 100 (maior risco).
statusstring
pendingapprovedrejectedmanual_reviewcancellederrorblockedchallengereview_expired
Estado da análise (tabela na página inicial).
risk_levelstring
lowmediumhigh
low (até 30), medium (até 60) ou high.
analysis_idstring
Identificador da análise no ClearSale.
clearsale_order_idstring
Identificador do pedido no ClearSale. Omitido se vazio.
reasonstring
Motivo da decisão (do ClearSale ou do revisor). Omitido se vazio.
reviewed_bystring
Quem decidiu manualmente. Omitido antes disso.
reviewed_atstring
Quando decidiu manualmente.
raw_responseobject
Resposta bruta do ClearSale, guardada como veio. Pode ser omitida.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"clearsale"} / {"error":"insufficient privileges","required":"manage_fraud"}
400id que não é número{"error":"Invalid analysis ID"}
404Análise inexistente{"error":"Analysis not found"}

Decidir uma análise

O revisor registra a decisão: aprovar, reprovar ou cancelar. A plataforma grava o estado novo, quem decidiu e quando. É a saída da fila manual_review.

PUT/api/v1/admin/fraud/{id}Admin

Registra a decisão manual sobre uma análise

Autenticação: Authorization: Bearer <token> de um administrador com manage_fraud ou manage_orders. Requer o módulo clearsale ativo.

Parâmetros de caminho

idintegerobrigatório
Identificador numérico da análise.

Corpo da requisição

statusstringobrigatório
approvedrejectedcancelled
Decisão.
reasonstring
Justificativa. Se vazio, o motivo anterior é mantido.

Exemplo de requisição

Resposta

200Decisão registrada

Campos da resposta

successboolean
true.
analysisobject
A análise atualizada.
analysis.idinteger
Identificador numérico da análise (não é UUID).
analysis.order_iduuid
Pedido analisado. Há no máximo uma análise por pedido.
analysis.scorenumber
Pontuação de risco de 0 (menor risco) a 100 (maior risco).
analysis.statusstring
pendingapprovedrejectedmanual_reviewcancellederrorblockedchallengereview_expired
Estado da análise (tabela na página inicial).
analysis.risk_levelstring
lowmediumhigh
low (até 30), medium (até 60) ou high.
analysis.analysis_idstring
Identificador da análise no ClearSale.
analysis.clearsale_order_idstring
Identificador do pedido no ClearSale. Omitido se vazio.
analysis.reasonstring
Motivo da decisão (do ClearSale ou do revisor). Omitido se vazio.
analysis.reviewed_bystring
Quem decidiu manualmente. Omitido antes disso.
analysis.reviewed_atstring
Quando decidiu manualmente.
analysis.raw_responseobject
Resposta bruta do ClearSale, guardada como veio. Pode ser omitida.
analysis.created_atstring
Criação, RFC 3339 em UTC.
analysis.updated_atstring
Última alteração.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"clearsale"} / {"error":"insufficient privileges","required":"manage_fraud"}
400id que não é número{"error":"Invalid analysis ID"}
400Corpo inválido ou status fora de approved/rejected/cancelled{"error":"Status must be 'approved', 'rejected', or 'cancelled'"}
500Análise inexistente ou falha ao gravar (a mensagem diz Failed to update analysis: ...){"error":"Failed to update analysis: clearsale: analysis 999 not found"}
Só registra a decisão

Esta rota altera a análise. Ela não aprova nem cancela o pedido. Não há trava de estado: uma análise já approved pode ser trocada para rejected.

Estatísticas

Totais para o painel de antifraude: quantas análises existem em cada estado, a taxa de aprovação e a pontuação média.

GET/api/v1/admin/fraud/statsAdmin

Totais das análises de fraude

Autenticação: Authorization: Bearer <token> de um administrador com manage_fraud ou manage_orders. Requer o módulo clearsale ativo.

Sem parâmetros.

Exemplo de requisição

Resposta

200Totais devolvidos

Campos da resposta

total_analysesinteger
Total de análises.
approved_countinteger
Aprovadas (automática ou manualmente).
rejected_countinteger
Reprovadas.
manual_review_countinteger
Aguardando revisão manual.
pending_countinteger
Aguardando resposta do ClearSale.
error_countinteger
Que o ClearSale não conseguiu concluir.
approval_rate_bpsinteger
Aprovadas sobre (aprovadas + reprovadas), em pontos-base (9230 = 92,30%).
average_scorenumber
Pontuação média de risco.
high_risk_countinteger
Análises de risco alto.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"clearsale"} / {"error":"insufficient privileges","required":"manage_fraud"}
500Falha na consulta{"error":"Failed to get fraud statistics"}
Canceladas e outros estados

Os totais por estado cobrem approved, rejected, manual_review, pending e error. Análises cancelled entram em total_analyses, mas não em contador próprio.

Veja também

  • Analisar um pedido
  • Visão geral do antifraude
Anterior
Analisar um pedido
Próxima
Assinaturas e compras programadas
Nesta página
  • Listar análises
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma análise
  • Exemplo de requisição
  • Resposta
  • Erros
  • Decidir uma análise
  • Exemplo de requisição
  • Resposta
  • Erros
  • Estatísticas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/fraud/analyses?status=manual_review" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/fraud/112" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/admin/fraud/112" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "reason": "Cliente confirmou a compra por telefone"
  }'
bash
curl "$BASE_URL/api/v1/admin/fraud/stats" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "analyses": [
    {
      "id": 112,
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "score": 54.5,
      "status": "manual_review",
      "risk_level": "medium",
      "analysis_id": "CS-8841023",
      "clearsale_order_id": "PEDIDO-20261010-0004",
      "reason": "Divergência entre endereço de cobrança e entrega",
      "created_at": "2026-10-11T21:06:50Z",
      "updated_at": "2026-10-11T21:07:02Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
json
{
  "id": 112,
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "score": 54.5,
  "status": "manual_review",
  "risk_level": "medium",
  "analysis_id": "CS-8841023",
  "clearsale_order_id": "PEDIDO-20261010-0004",
  "reason": "Divergência entre endereço de cobrança e entrega",
  "created_at": "2026-10-11T21:06:50Z",
  "updated_at": "2026-10-11T21:07:02Z"
}
json
{
  "success": true,
  "analysis": {
    "id": 112,
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "score": 54.5,
    "status": "approved",
    "risk_level": "medium",
    "analysis_id": "CS-8841023",
    "clearsale_order_id": "PEDIDO-20261010-0004",
    "reason": "Cliente confirmou a compra por telefone",
    "created_at": "2026-10-11T21:06:50Z",
    "updated_at": "2026-10-11T21:07:02Z",
    "reviewed_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
    "reviewed_at": "2026-10-11T21:30:00Z"
  }
}
json
{
  "total_analyses": 120,
  "approved_count": 96,
  "rejected_count": 8,
  "manual_review_count": 4,
  "pending_count": 2,
  "error_count": 10,
  "approval_rate_bps": 9230,
  "average_score": 21.4,
  "high_risk_count": 6
}