> ## 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.

# Red de inteligencia Clausum

> Contribuye y consume señales compartidas de fraude — guía de integración para bancos y PSP

**Inteligencia Clausum** combina feeds gestionados y la red colaborativa. Ambas aplican durante `POST /api/v1/assess` y `POST /api/v1/assess/payout`:

| Capa | Contrato | Quién la opera | Qué haces |
| - | - | - | - |
| **Feeds gestionados** | CLM-ADD-INTEL | Staff Clausum | Nada — feeds y blocklists de plataforma aplican con entitlement |
| **CIN (red colaborativa)** | CLM-ADD-NET-C (consumo) + opt-in contribuir | Bancos, PSP y comercios participantes | Publica señales; recibe hits **exactos / agregados** de peers en assess |
| **CEG (Entity Graph)** | Incluido con consumo CIN (**CEG Coverage**) | Misma red, capa de grafo | Actívalo **después** de estabilizar CIN — [guía Entity Graph](/es/guides/entity-graph-ceg) |

<Note>
  **CIN vs CEG:** CIN es la red colaborativa base (hits de listas). **CEG es la capa premium / extendida** — relaciones 1-hop entre entidades co-observadas. Mismo SKU de consumo; flag de modo aparte (`graph_assess_mode`). Índice de integración: [Configuración → Servicios](/es/guides/settings-services).
</Note>

<Warning>
  La red **aumenta** assess — no reemplaza tus reglas locales, blocklists ni la llamada síncrona a assess. [Prevención primero](/es/concepts/capabilities).
</Warning>

<Note>
  **¿Legal / compliance primero?** Lee [Red colaborativa — confianza y enrolamiento](/es/guides/collaborative-network-guarantees) — ruta enrollment-first, garantías de privacidad y compromisos mutuos antes de integración API.
</Note>

## Para quién es esta guía

| Segmento | Rol típico | Perfil de integración |
| - | - | - |
| **Banco** (`banco`) | Core bancario, tesorería, ops de fraude | `financial_institution` — contribuir + consumir cuando esté contratado |
| **PSP** (`psp`) | Middleware adquirente, orquestación sub-comercio | `partner` — contribuir señales agregadas; consumir cuando esté contratado |
| **Comercio** | Contribuidor peer opcional | `merchant` — solo contribuir salvo que staff habilite consumo |

Planes por segmento: [Banco](/es/segments/bank) · [PSP](/es/segments/psp) · [Comercio](/es/segments/merchant)

## Cómo encaja en tu stack

```mermaid theme={null}
sequenceDiagram
  participant Core as Your core / PSP middleware
  participant CL as Clausum assess
  participant Net as Collaborative network
  participant M as Managed feeds (Clausum)

  Core->>CL: POST /assess or /assess/payout
  CL->>M: Match managed intel (if entitled)
  CL->>Net: Match peer signals (if consume enabled)
  CL->>CL: Local rules + blocklists
  CL-->>Core: decision + session_id + signals
```

| Capacidad | Endpoint | Propósito |
| - | - | - |
| **Gate en tiempo real** | `POST /api/v1/assess` | Decisión pay-in antes del capture |
| **Gate payout** | `POST /api/v1/assess/payout` | Decisión de dispersión antes del release |
| **Publicación en red** | `POST /api/v1/network/intelligence` | Señales compartidas bulk para otros participantes |
| **Webhooks / ingest** | `clm_wh_*` | Eventos post-pago — **no** sustituto de assess |

***

## Inicio rápido — banco (5 pasos)

<Steps>
  <Step title="1. Crear una clave de servidor">
    **Panel de Control → Conexiones → Claves API** — crea `clm_sk_*` con:

    * `assess` — requerido para beneficiarte de señales consumidas
    * `network:contribute` — publicar señales (o `fraud:report` para reportes únicos)

    Consulta [Claves API](/es/guides/api-keys).
  </Step>

  <Step title="2. Habilitar contribución">
    Los bancos usan perfil **`financial_institution`**. La contribución se activa en el panel:

    * **Inteligencia** (`/dashboard/network`) → panel **Inicio rápido** (solo bancos) o pestaña **Configuración** → habilita **Contribuir a la red**

    <Note>
      **Consumir** señales de pares en assess lo habilita Clausum en tu contrato (**CLM-ADD-NET-C**). Contacta a tu account manager — no es self-serve vía API.
    </Note>
  </Step>

  <Step title="3. Publicar señales">
    Envía indicadores de fraude confirmados desde tu core o plataforma de fraude (hasta **500 entradas** por solicitud):

    ```bash theme={null}
    curl -s -X POST "${CLAUSUM_API_BASE}/api/v1/network/intelligence" \
      -H "Authorization: Bearer ${CLAUSUM_SECRET_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "entries": [
          {
            "list_type": "email",
            "value": "confirmed-fraud@example.com",
            "severity": "block",
            "reason_code": "confirmed_fraud",
            "reason_detail": "Internal case #12345",
            "confidence": 90,
            "source": "bank_feed"
          },
          {
            "list_type": "card_bin",
            "value": "411111",
            "severity": "flag",
            "reason_code": "card_testing",
            "source": "bank_feed"
          }
        ]
      }'
    ```
  </Step>

  <Step title="4. Proteger pay-in y payout">
    Cada pago o dispersión debe llamar assess **antes** de que se mueva el dinero:

    * Pay-in: [Evaluación en tiempo real](/es/guides/realtime-assessment)
    * Payout: [Evaluación de payout](/es/guides/payout-assessment)

    Cuando el **consumo** de red está activo, assess hace match de campos normalizados contra señales de pares cuyo trust score cumple tu umbral.
  </Step>

  <Step title="5. Operar y revocar">
    * **Inteligencia → Mis señales** — revisa y revoca falsos positivos
    * **Inteligencia → Participantes** — ve instituciones contribuyentes (cuando consumo está on)
    * **Protección** — estado compacto de capas gestionadas + red
  </Step>
</Steps>

***

## Inicio rápido — PSP (5 pasos)

<Steps>
  <Step title="1. Completar onboarding PSP">
    Registra comercios antes de assess en vivo — [Comercios PSP](/es/guides/psp-submerchants). Cada assess pay-in debe incluir `submerchant_id` cuando tu registro no esté vacío.
  </Step>

  <Step title="2. Crear claves de middleware">
    `clm_sk_*` en tu capa de orquestación PSP con `assess` + opcional `network:contribute`. Nunca incrustes claves secretas en frontends de sub-comercio.
  </Step>

  <Step title="3. Assess antes de liquidación">
    ```json theme={null}
    {
      "amount": 150.00,
      "amount_unit": "major",
      "currency": "MXN",
      "submerchant_id": "uuid-from-registry",
      "order_id": "sm-8842-checkout-001",
      "email": "payer@example.com",
      "device": { "ip": "203.0.113.5" }
    }
    ```

    Tu middleware aplica `decision` antes de liquidar fondos al sub-comercio. Consulta [Integración PSP](/es/segments/psp).
  </Step>

  <Step title="4. Opcionalmente contribuir señales agregadas">
    Publica rangos BIN, correos o IPs observados en tu portafolio (con aprobación legal):

    ```bash theme={null}
    curl -s -X POST "${CLAUSUM_API_BASE}/api/v1/network/intelligence" \
      -H "Authorization: Bearer ${CLAUSUM_SECRET_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "entries": [{
          "list_type": "ip_address",
          "value": "203.0.113.44",
          "severity": "review",
          "reason_code": "velocity_abuse",
          "source": "api"
        }]
      }'
    ```

    Habilita **Contribuir a la red** en **Inteligencia → Configuración**.
  </Step>

  <Step title="5. Enrutar webhooks por sub-comercio">
    Los eventos salientes incluyen metadata para enrutamiento — [Recibir webhooks](/es/guides/receiving-webhooks). Canaliza eventos del adquirente vía [Ingestión de eventos](/es/guides/event-ingestion) como complemento a assess.
  </Step>
</Steps>

***

## Referencia API

### Publicar señales

```
POST /api/v1/network/intelligence
Authorization: Bearer clm_sk_...
Content-Type: application/json
```

**Permisos:** `network:contribute` o `fraud:report` (solo clave secreta).

**Cuerpo:** `entries[]` (máx. 500) o `list_type` + `value` únicos.

| Campo | Requerido | Descripción |
| - | - | - |
| `list_type` | Sí | Tipo de señal (ver tabla abajo) |
| `value` | Sí | Valor raw — normalizado server-side |
| `severity` | Recomendado | `block`, `flag`, o `review` |
| `reason_code` | Recomendado | Código corto machine-readable |
| `reason_detail` | Opcional | Nota humana (no mostrada a otros tenants) |
| `confidence` | Opcional | 0–100 |
| `source` | Opcional | `api`, `bank_feed`, `fraud_report`, … |
| `external_ref` | Opcional | Id estable de tu feed para jobs batch idempotentes |
| `expires_at` | Opcional | Timestamp ISO |

**Respuesta:**

```json theme={null}
{
  "success": true,
  "accepted": 2,
  "skipped": 0,
  "errors": [],
  "list_types_supported": ["email", "email_domain", "ip_address", "..."]
}
```

**Errores:**

| Código | Significado |
| - | - |
| `NETWORK_CONTRIBUTE_DISABLED` | Habilita contribución en Panel → Inteligencia → Configuración |
| `VALIDATION_ERROR` | `list_type` inválido, batch vacío, o >500 entradas |

### Estadísticas de red (partner)

```
GET /api/v1/network/intelligence
Authorization: Bearer clm_sk_...
```

**Permisos:** `network:signals:read`, `network:contribute`, `fraud:report`, o `assess`.

Devuelve snapshot de membresía, conteo activo contribuido y tamaño del pool de red.

### Membresía del panel (sesión)

```
GET /api/v1/network/membership
PATCH /api/v1/network/membership
```

Autenticado con **sesión del panel** (cookie del navegador tras sign-in), no claves partner.

Los tenants pueden PATCH:

| Campo | Descripción |
| - | - |
| `contribute_enabled` | Opt-in para publicar señales |
| `contribute_list_types` | Allow-list de tipos a publicar (`null` = los 28) |
| `consume_list_types` | Allow-list de tipos a hacer match en assess (`null` = todos) |
| `min_trust_score` | 0–100 — ignora contribuidores bajo este nivel de confianza |

**`consume_enabled`** y **`integration_profile`** los gestiona Clausum según tipo de organización y contrato (**CLM-ADD-NET-C**).

### Revocar señales (sesión del panel)

```
GET /api/v1/network/signals?page=1&limit=25
PATCH /api/v1/network/signals
{ "id": "entry-uuid" }
```

Establece `is_active = false` para la entrada de tu organización. También disponible en **Inteligencia → Mis señales**.

***

## Tipos de señal soportados (28)

Catálogo completo con mapeo de campos assess: consulta referencia de ingeniería [`NETWORK_SIGNAL_CATALOG.md`](https://github.com/ejusticia/clausum-dashboard/blob/main/docs/NETWORK_SIGNAL_CATALOG.md) en el repo.

| Grupo | Valores `list_type` |
| - | - |
| **Identidad** | `national_id`, `customer_name`, `customer_id`, `beneficiary_name` |
| **Contacto** | `email`, `email_domain`, `phone` |
| **Pago** | `bank_account`, `card_bin`, `card_hash`, `card_last4_bin`, `swift_bic`, `routing_number`, `wallet_address` |
| **Dispositivo / red** | `ip_address`, `ip_range`, `device_fingerprint`, `user_agent`, `session_id`, `imei`, `asn`, `country` |
| **Ubicación** | `billing_postal`, `shipping_postal`, `address_hash` |
| **Comercio** | `merchant_domain`, `submerchant_id`, `mcc` |

### Destacados de mapeo assess

| Campo assess | `list_type` de red |
| - | - |
| `email`, `phone`, `customer_id`, `customer_name` | Mismo nombre |
| `payer_identity.document_number` | `national_id` |
| `payer_identity.imei` | `imei` |
| `beneficiary.clabe`, `iban`, `account_hash`, `origin.account_id` | `bank_account` |
| `beneficiary.name` | `beneficiary_name` |
| `device.ip` | `ip_address` (+ match de `ip_range` CIDR publicado) |
| `device.fingerprint`, `session_id`, `user_agent`, `asn` | Mismo nombre |
| `payment_method.card_bin`, `card_hash` | Mismo nombre |
| `merchant.domain`, `merchant.mcc` | `merchant_domain`, `mcc` |
| `submerchant_id` | `submerchant_id` |

**Escape hatch:** envía cualquier tipo del catálogo vía `network_observations: [{ "list_type": "…", "value": "…" }]` sin esperar nuevos campos top-level en assess.

```json theme={null}
{
  "amount": 150000,
  "currency": "MXN",
  "email": "payer@example.com",
  "payer_identity": { "document_number": "12345678-9" },
  "device": { "ip": "203.0.113.10" },
  "network_observations": [
    { "list_type": "bank_account", "value": "012180001234567890" }
  ]
}
```

**Comportamiento de severity:** una señal peer con `block` puede forzar **decline** durante assess, similar a un hit de blocklist local.

***

## Entity Graph / CEG (`off` / `shadow` / `live`)

**CEG** es la **extensión premium de CIN** — no un segundo producto. Con consumo activo, assess puede ejecutar un **lookup de relaciones a 1 hop** sobre entidades co-observadas (p. ej. cuenta ↔ dispositivo ↔ email). Es incremental al exact match y al aggregate — no los reemplaza.

Checklist completo, tabla CIN vs CEG y camino a live: **[Entity Graph (CEG)](/es/guides/entity-graph-ceg)**.

| `graph_assess_mode` | Efecto |
| - | - |
| `off` | Sin lookup del grafo |
| `shadow` (default) | Devuelve `network_intelligence.graph` con **weight 0**; la decisión no cambia; compara con `shadow_would_decision` |
| `live` | Suma al score; puede forzar **review** / hard-block **decline** (≥2 fuentes independientes para hard-block) |

Configura en **Inteligencia → Configuración** o **Configuración → Servicios → Entity Graph** (sesión del panel — no clave Partner).

<Warning>
  `graph_assess_mode` es **distinto** del `assess_mode` del CIN exacto (shadow / advisory / enforcement de listas peer). Valida en **shadow** antes de activar **live** en tráfico productivo.
</Warning>

Nunca se exponen: IDs de instituciones, PII de vecinos ni hashes reconstruibles. Solo **1 hop**, en **paralelo** con CIN exacto, fail-open \~400 ms.

***

## Privacidad y compliance

| Dato | Visualización en panel | Matching cross-tenant |
| - | - | - |
| ID nacional, nombres, correo, teléfono, cuentas bancarias, fingerprints, hashes de tarjeta | Solo etiquetas enmascaradas seguras | Normalizado / hasheado |
| BIN, país, IP, rango IP (CIDR), dominio de correo, SWIFT, MCC | Etiquetas plain | Valores normalizados plain |

**Anonimato del contribuidor:** otros participantes nunca ven el nombre de tu institución — solo alias `Participant INST-…`. Clausum retiene atribución internamente para gobernanza y trust scoring.

**Códigos de motivo:** usa `reason_code` machine-readable (p. ej. `confirmed_fraud`, `mule_account`). `reason_detail` opcional se almacena para tu org y ops Clausum — **nunca** se devuelve a otros tenants.

Antes de contribuir:

* Confirma que tu equipo **legal / compliance** aprueba compartir cada clase de señal (usa `contribute_list_types` para restringir)
* Documenta IDs de caso internos en `reason_detail` — no expuestos a otros tenants
* Mantén un runbook para **revocar** falsos positivos vía **Mis señales**

***

## Confianza y consumo

Cada contribuidor tiene **trust score** (0–100). Cuando **consume** está habilitado, assess aplica señales solo de contribuidores en o sobre tu **`min_trust_score`** (ajustable en **Inteligencia → Configuración**).

Usa **`consume_list_types`** para limitar qué clases de señal haces match durante assess (p. ej. solo identidad + pago, omitir señales de dispositivo).

**Participantes** en el panel lista alias anónimos de contribuidores con contribuciones activas y si cumplen tu umbral.

***

## Patrones de integración bancaria

### Core bancario / SPEI

Llama assess **síncronamente** en la ruta de autorización antes de liberar fondos:

1. Core recibe solicitud de transferencia
2. Middleware llama `POST /api/v1/assess/payout`
3. En `decline` → retiene transferencia, abre expediente
4. En `approve` / `review` → sigue tu matriz de política ([Resiliencia de assess](/es/guides/assess-resilience))

Combina con blocklists payout (`flow_scope: payout`) — [Blocklists](/es/concepts/blocklists).

### Jobs batch de feed de fraude

Programa jobs nocturnos u horarios desde tu data warehouse de fraude:

* Mapea tablas internas → `entries[]`
* Usa `external_ref` estable por fila para updates idempotentes
* Empieza con `severity: review` en UAT; promueve a `block` tras validación

### Expedientes y flujo regulatorio

Vincula hits de red de alta severidad a [Gestión de expedientes](/es/guides/case-management). [Reportar fraude](/es/guides/report-fraud) puede complementar API bulk para confirmaciones ad hoc.

***

## Patrones de integración PSP

### El middleware posee la orquestación

Clausum **no** llama a Stripe, Mercado Pago ni tu adquirente. Tu capa PSP:

1. Recibe intento de pago del checkout sub-comercio
2. Llama assess con `submerchant_id`
3. Ramifica según `decision` antes del capture

Consulta diagrama de arquitectura en [Integración PSP](/es/segments/psp).

### Contribución de señales multi-tenant

Al contribuir señales a nivel portafolio:

* Evita PII de sub-comercio en `reason_detail`
* Prefiere BIN, IP y patrones de velocidad sobre correos raw cuando sea posible
* Separa claves sandbox y producción por entorno

### Add-ons institucionales

PSP con productos de tesorería o dispersión también deben evaluar [Evaluación de payout](/es/guides/payout-assessment) y [Screening regulatorio](/es/guides/regulatory-screening) cuando estén en **CLM-MOD-INST**.

***

## Feeds gestionados (CLM-ADD-INTEL)

Cuando tienes entitlement, feeds de amenazas operados por Clausum aplican automáticamente durante assess — sin setup API.

Revisa estado en **Panel de Control → Protección** (franja Inteligencia Clausum). Staff sincroniza feeds del lado plataforma; los tenants ven conteos de señales y última sincronización solamente.

Esta capa es independiente de la red colaborativa — puedes tener una, ambas o ninguna según contrato.

***

## Checklists go-live

### Banco

* [ ] SQL `044` + `144` + `145` aplicado en Supabase
* [ ] Clave de servidor con `assess` + `network:contribute`
* [ ] Contribución habilitada en **Inteligencia → Configuración**; `contribute_list_types` acordado con legal
* [ ] **`min_trust_score`** y opcional **`consume_list_types`** configurados
* [ ] **CLM-ADD-NET-C** confirmado con account manager si consumes señales de pares
* [ ] Payout assess conectado antes de release SPEI/wire ([Integración banco](/es/segments/bank))
* [ ] UAT: publica señal de prueba desde org staging → verifica match en assess
* [ ] Runbook para revocar falsos positivos en **Mis señales**
* [ ] Sign-off de certificación en `cert.clausum.ai` cuando se proporcione

### PSP

* [ ] Todos los comercios activos registrados con `external_id` estable
* [ ] Cada assess incluye `submerchant_id` cuando el registro no está vacío
* [ ] Middleware aplica decisión antes del capture del adquirente
* [ ] Opcional: contribución habilitada + sign-off legal para señales agregadas
* [ ] Enrutamiento webhook probado por sub-comercio
* [ ] UAT sandbox en `sandbox.clausum.ai` antes de producción

***

## Solución de problemas

| Síntoma | Revisar |
| - | - |
| `403 NETWORK_CONTRIBUTE_DISABLED` | Habilita **Contribuir a la red** en configuración de Inteligencia |
| Las señales de pares nunca hacen match | Confirma **CLM-ADD-NET-C** activo; revisa umbral de confianza con account manager |
| `401` en API de red | Usa `clm_sk_*` con `network:contribute`, no `clm_wh_*` |
| Assess funciona pero sin capa de red | El consumo está gated por contrato — intel gestionada y reglas locales siguen aplicando |
| Señales duplicadas | Usa normalización consistente; revoca entrada antigua en **Mis señales** |

***

## Guías relacionadas

<CardGroup cols={2}>
  <Card title="Integración banco" icon="building-columns" href="/es/segments/bank">
    Plan institucional payout-first
  </Card>

  <Card title="Integración PSP" icon="sitemap" href="/es/segments/psp">
    Plan de enrutamiento sub-comercio
  </Card>

  <Card title="Assess en tiempo real" icon="bolt" href="/es/guides/realtime-assessment">
    API pay-in
  </Card>

  <Card title="Assess payout" icon="money-bill-transfer" href="/es/guides/payout-assessment">
    API dispersión
  </Card>

  <Card title="Claves API" icon="key" href="/es/guides/api-keys">
    Permisos y prefijos
  </Card>

  <Card title="Capacidades" icon="table-list" href="/es/concepts/capabilities">
    Catálogo de módulos por segmento
  </Card>
</CardGroup>

Soporte: **[api@clausum.ai](mailto:api@clausum.ai)**


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