> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clausum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocklists

> Listas dinámicas de denegación y flag para assess pay-in y payout

Las blocklists son listas con alcance de organización que influyen en cada assessment. Cuando una transacción coincide con una entrada activa, Clausum agrega una señal o declina de forma dura con `decision: "decline"`.

## Tipos de entrada (pay-in)

| `list_type` | Coincide con |
| - | - |
| `email` | Dirección de email exacta |
| `email_domain` | Dominio de email (p. ej. `example.com`) |
| `ip_address` | IP única |
| `ip_range` | Rango CIDR |
| `device_fingerprint` | Huella de dispositivo |
| `card_bin` | Primeros 6 dígitos de la tarjeta |
| `card_hash` | Número de tarjeta hasheado |
| `country` | Código de país ISO |
| `phone` | Número de teléfono |
| `customer_id` | Tu id interno de cliente |

## Tipos específicos de payout

Para [payout assess](/es/guides/payout-assessment), agrega entradas con alcance payout:

| `list_type` | Coincide con |
| - | - |
| `clabe` | CLABE mexicana |
| `iban` | IBAN |
| `account_hash` | Número de cuenta hasheado |
| `swift_bic` | SWIFT / BIC |
| `beneficiary_id` | Tu identificador estable de beneficiario |

Los tipos compartidos (`email`, `ip_address`, `country`, `customer_id`) pueden aplicar a ambos flujos cuando se configuran correctamente.

## Alcance de flujo

Cada entrada tiene **`flow_scope`**:

| Valor | Aplica durante |
| - | - |
| `payin` | Solo checkout / captura de tarjeta |
| `payout` | Solo dispersiones |
| `all` | Pay-in y payout |

Configura el alcance en **Panel de Control → Protección → Blocklists** al crear o editar una entrada. Payout assess ignora entradas solo payin y viceversa.

## Severidad

| Severidad | Efecto en el assessment |
| - | - |
| `block` | Decline duro (`risk_score` = 100) |
| `flag` | Agrega peso significativo |
| `review` | Agrega peso moderado, enruta a revisión |

## Gestionar entradas

El CRUD de blocklists usa un **JWT de sesión del panel** (usuario autenticado), no claves partner API.

<CodeGroup>
  ```bash Agregar entrada theme={null}
  curl -X POST "$CLAUSUM_API_BASE/api/v1/blocklists" \
    -H "Authorization: Bearer $DASHBOARD_JWT" \
    -H "Content-Type: application/json" \
    -d '{
      "list_type": "clabe",
      "value": "012180001234567890",
      "severity": "block",
      "flow_scope": "payout",
      "reason": "Confirmed mule account"
    }'
  ```

  ```bash Listar entradas theme={null}
  curl "$CLAUSUM_API_BASE/api/v1/blocklists?list_type=email&severity=block" \
    -H "Authorization: Bearer $DASHBOARD_JWT"
  ```

  ```bash Desactivar entrada theme={null}
  curl -X PATCH "$CLAUSUM_API_BASE/api/v1/blocklists" \
    -H "Authorization: Bearer $DASHBOARD_JWT" \
    -H "Content-Type: application/json" \
    -d '{ "id": "8f3c...e21", "is_active": false }'
  ```
</CodeGroup>

<Note>
  Agregar entradas requiere `admin`, `analyst` o `compliance_officer`. Eliminar entradas requiere `admin`.
</Note>

## Población automática

Cuando llamas [`report-fraud`](/es/guides/report-fraud), Clausum auto-bloquea el email (`block`), BIN de tarjeta (`flag`) e IP (`block`) — etiquetados `source: "fraud_report"` y vinculados al expediente.

## Entradas con expiración

Define `expires_at` para bloqueos temporales (p. ej. ban de velocidad 24 h):

```json theme={null}
{
  "list_type": "ip_address",
  "value": "201.150.10.22",
  "severity": "block",
  "flow_scope": "all",
  "reason": "Card-testing burst",
  "expires_at": "2026-06-01T00:00:00Z"
}
```

## Normalización

Los valores se normalizan al escribir: emails en minúsculas, países en mayúsculas. Duplicados (misma org + tipo + valor + alcance) devuelven **409 Conflict**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.