API atual/Referência completa/Antifraude

POSTAnalisar um pedido

Envia um pedido ao ClearSale para pontuar o risco de fraude e grava o resultado.

Chargeback e pedidos fraudulentos custam caro. A plataforma integra o ClearSale, um serviço brasileiro de antifraude, que recebe os dados do pedido e devolve uma pontuação de risco e uma recomendação.

Envia o pedido ao ClearSale e grava a pontuação e a decisão. Normalmente a análise acontece sozinha; use esta rota para analisar um pedido que ficou de fora. Cada pedido só pode ser analisado uma vez.

POST/api/v1/admin/fraud/analyzeAdmin

Envia um pedido para análise de fraude

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

Corpo da requisição

order_iduuidobrigatório

Pedido a analisar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fraud/analyze" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4"
  }'

Resposta

200Pedido analisado

json

{
  "success": true,
  "analysis": {
    "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

successboolean

true.

analysisobject

A análise criada, com os campos abaixo.

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	Corpo inválido ou `order_id` ausente	`{"error":"order_id is required"}`
500	Credenciais do ClearSale não configuradas, análise já existente, pedido inexistente ou falha na chamada ao ClearSale (nesta última a resposta traz também `analysis` com o estado `error`)	`{"error":"Fraud analysis failed: clearsale: analysis already exists for order ..."}`

Veja também