Red de inteligencia Clausum

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

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.

La red aumenta assess — no reemplaza tus reglas locales, blocklists ni la llamada síncrona a assess. Prevención primero.

¿Legal / compliance primero? Lee Red colaborativa — confianza y enrolamiento — ruta enrollment-first, garantías de privacidad y compromisos mutuos antes de integración API.

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 · PSP · Comercio

Cómo encaja en tu stack

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)

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.

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

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.

3. Publicar señales

Envía indicadores de fraude confirmados desde tu core o plataforma de fraude (hasta 500 entradas por solicitud):

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

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
Payout: Evaluación de payout

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

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

Inicio rápido — PSP (5 pasos)

1. Completar onboarding PSP

Registra comercios antes de assess en vivo — Comercios PSP. Cada assess pay-in debe incluir submerchant_id cuando tu registro no esté vacío.

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.

3. Assess antes de liquidación

{
  "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.

4. Opcionalmente contribuir señales agregadas

Publica rangos BIN, correos o IPs observados en tu portafolio (con aprobación legal):

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.

5. Enrutar webhooks por sub-comercio

Los eventos salientes incluyen metadata para enrutamiento — Recibir webhooks. Canaliza eventos del adquirente vía Ingestión de eventos como complemento a assess.

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:

{
  "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 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.

{
  "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).

`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).

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.

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:

Core recibe solicitud de transferencia
Middleware llama POST /api/v1/assess/payout
En decline → retiene transferencia, abre expediente
En approve / review → sigue tu matriz de política (Resiliencia de assess)

Combina con blocklists payout (flow_scope: payout) — 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. Reportar fraude 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:

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

Consulta diagrama de arquitectura en Integración 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 y Screening regulatorio 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)
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

Integración banco

Plan institucional payout-first

Integración PSP

Plan de enrutamiento sub-comercio

Assess en tiempo real

API pay-in

Assess payout

API dispersión

Claves API

Permisos y prefijos

Capacidades

Catálogo de módulos por segmento

Soporte: api@clausum.ai

​Para quién es esta guía

​Cómo encaja en tu stack

​Inicio rápido — banco (5 pasos)

​Inicio rápido — PSP (5 pasos)

​Referencia API

​Publicar señales

​Estadísticas de red (partner)

​Membresía del panel (sesión)

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

​Tipos de señal soportados (28)

​Destacados de mapeo assess

​Entity Graph / CEG (off / shadow / live)

​Privacidad y compliance

​Confianza y consumo

​Patrones de integración bancaria

​Core bancario / SPEI

​Jobs batch de feed de fraude

​Expedientes y flujo regulatorio

​Patrones de integración PSP

​El middleware posee la orquestación

​Contribución de señales multi-tenant

​Add-ons institucionales

​Feeds gestionados (CLM-ADD-INTEL)

​Checklists go-live

​Banco

​PSP

​Solución de problemas

​Guías relacionadas

Integración banco

Integración PSP

Assess en tiempo real

Assess payout

Claves API

Capacidades

Para quién es esta guía

Cómo encaja en tu stack

Inicio rápido — banco (5 pasos)

Inicio rápido — PSP (5 pasos)

Referencia API

Publicar señales

Estadísticas de red (partner)

Membresía del panel (sesión)

Revocar señales (sesión del panel)

Tipos de señal soportados (28)

Destacados de mapeo assess

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

Privacidad y compliance

Confianza y consumo

Patrones de integración bancaria

Core bancario / SPEI

Jobs batch de feed de fraude

Expedientes y flujo regulatorio

Patrones de integración PSP

El middleware posee la orquestación

Contribución de señales multi-tenant

Add-ons institucionales

Feeds gestionados (CLM-ADD-INTEL)

Checklists go-live

Banco

PSP

Solución de problemas

Guías relacionadas