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

bash

curl "$BASE_URL/api/v1/admin/fraud/analyses?status=manual_review" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Análises devolvidas

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
}

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

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"clearsale"}` / `{"error":"insufficient privileges","required":"manage_fraud"}`
500	Falha 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

bash

curl "$BASE_URL/api/v1/admin/fraud/112" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Análise devolvida

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

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

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"clearsale"}` / `{"error":"insufficient privileges","required":"manage_fraud"}`
400	`id` que não é número	`{"error":"Invalid analysis ID"}`
404	Aná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

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"
  }'

Resposta

200Decisão registrada

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

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

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

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

bash

curl "$BASE_URL/api/v1/admin/fraud/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Totais devolvidos

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
}

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

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

Veja também

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

bash

curl "$BASE_URL/api/v1/admin/fraud/analyses?status=manual_review" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Análises devolvidas

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
}

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

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"clearsale"}` / `{"error":"insufficient privileges","required":"manage_fraud"}`
500	Falha 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

bash

curl "$BASE_URL/api/v1/admin/fraud/112" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Análise devolvida

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

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

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"clearsale"}` / `{"error":"insufficient privileges","required":"manage_fraud"}`
400	`id` que não é número	`{"error":"Invalid analysis ID"}`
404	Aná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

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"
  }'

Resposta

200Decisão registrada

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

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

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

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

bash

curl "$BASE_URL/api/v1/admin/fraud/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Totais devolvidos

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
}

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

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