API de lista de bloqueo

La lista de bloqueo es la misma lista que Configuración → Prevención de fraude en el panel (consulte Lista de bloqueo y detección de duplicados). Una verificación que coincide con una entrada activa se rechaza o se envía a revisión manual. Las entradas son privadas para su organización.

Los endpoints están en /api/v1/kyc/blocklist y usan una clave de API (Authorization: Bearer ck_live_…) con el ámbito kyc:manage. Consulte Autenticación.

Los valores bloqueados nunca se devuelven: la API proporciona el tipo de entrada, una pista enmascarada (una dirección IP o un rango se devuelve completo), la acción, el motivo, la caducidad y los contadores de coincidencias.

Añadir entradas

POST /api/v1/kyc/blocklist

Bloquee un valor concreto:

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

O bien bloquee lo que contiene una verificación existente:

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

fromRequestId debe ser una verificación de su organización. kinds limita lo que se bloquea (por defecto: todo lo que tenga la verificación: rostro, número(s) de documento, teléfono, correo, dirección IP y dispositivo). Los tipos de los que la verificación no tiene datos se omiten.

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

Errores: 400 por un valor no utilizable o una verificación sin nada que bloquear, 404 cuando fromRequestId no es de su organización, 409 cuando ya existe una entrada activa idéntica.

Listar entradas

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

Devuelve { "data": [ … ], "total": 12 }. Las entradas caducadas se ocultan salvo que use includeExpired=true. pageSize es como máximo 200.

Eliminar una entrada

DELETE /api/v1/kyc/blocklist/:id → { "success": true }. Eliminar una entrada que no es suya devuelve 404.

Cada alta y cada baja se registran en el registro de auditoría, con la clave de API como actor.

Interpretar el resultado

Una verificación que coincide incluye una entrada blocklist_match en sus señales de fraude (GET /api/v1/kyc/requests/:id/fraud-signals), con details.kind (el tipo) y details.action, nunca el valor. Sus desencadenantes de revisión o descalificadores contienen blocklist_match, y las reglas de políticas y flujos de trabajo pueden evaluar fraud.blocklistMatch y fraud.blocklistKinds.