API de lista de bloqueio

A lista de bloqueio é a mesma lista de Configurações → Prevenção de fraude no painel (veja Lista de bloqueio e detecção de duplicidade). Uma verificação que corresponda a uma entrada ativa é rejeitada ou encaminhada para revisão manual. As entradas são privadas da sua organização.

Os endpoints ficam em /api/v1/kyc/blocklist e usam uma chave de API (Authorization: Bearer ck_live_…) com o escopo kyc:manage. Consulte Autenticação.

Valores bloqueados nunca são retornados: a API devolve o tipo da entrada, uma dica mascarada (um endereço IP ou intervalo é retornado por completo), a ação, o motivo, a expiração e os contadores de correspondências.

Adicionar entradas

POST /api/v1/kyc/blocklist

Bloqueie um valor informado, indicando o tipo:

{
  "kind": "email",
  "value": "fraud@example.com",
  "action": "reject",
  "reason": "Chargeback ring",
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

Ou bloqueie o que uma verificação existente contém:

{
  "fromRequestId": "clx…",
  "kinds": ["face", "device", "ip"],
  "action": "escalate"
}

fromRequestId deve ser uma verificação da sua organização. kinds limita o que é bloqueado (padrão: tudo o que a verificação possui: rosto, número(s) de documento, telefone, e-mail, endereço IP, dispositivo). Tipos para os quais a verificação não tem dados são ignorados.

Resposta 201:

{
  "data": [
    {
      "id": "clx…",
      "kind": "email",
      "valueHint": "f•••@e•••.com",
      "action": "reject",
      "reason": "Chargeback ring",
      "createdByName": null,
      "sourceRequestId": null,
      "expiresAt": "2027-01-01T00:00:00.000Z",
      "expired": false,
      "matchCount": 0,
      "lastMatchedAt": null,
      "createdAt": "2026-10-24T15:00:00.000Z"
    }
  ]
}

Erros: 400 para um valor inutilizável ou uma verificação sem nada a bloquear, 404 quando fromRequestId não for da sua organização, 409 quando já existir uma entrada ativa idêntica.

Listar entradas

GET /api/v1/kyc/blocklist?kind=email&includeExpired=false&page=1&pageSize=50

Retorna { "data": [ … ], "total": 12 }. Entradas expiradas ficam ocultas, a menos que includeExpired=true. pageSize tem no máximo 200.

Remover uma entrada

DELETE /api/v1/kyc/blocklist/:id → { "success": true }. Remover uma entrada que não seja sua retorna 404.

Toda inclusão e remoção é registrada no registro de auditoria, com a chave de API como autora da ação.

Como ler o resultado

Uma verificação que corresponda traz uma entrada blocklist_match em seus sinais de fraude (GET /api/v1/kyc/requests/:id/fraud-signals), com details.kind (o tipo) e details.action, nunca o valor. Seus gatilhos de revisão ou critérios de desqualificação contêm blocklist_match, e regras de políticas e fluxos de trabalho podem testar fraud.blocklistMatch e fraud.blocklistKinds.