API — AML

El módulo AML filtra nombres contra listas de sanciones y vigilancia (OFAC-SDN, EU, UN, UK-OFSI). El motor solo reporta hits: nunca decide la aprobación. Un hit fuerza la revisión manual de la sesión aguas arriba (in_review).

Prefijo: /v1/aml. Requiere API key (X-API-Key: zkyc_...).

Endpoints

Método	Ruta	Auth	Descripción
POST	/v1/aml/screen	API key	Screening de un nombre contra listas
POST	/v1/aml/refresh	Operador	Recargar todas las listas habilitadas
GET	/v1/aml/status	API key	Conteo por fuente + último refresh

Screening

POST /v1/aml/screen
X-API-Key: zkyc_...
Content-Type: application/json

{
  "fullName": "John Doe",
  "dateOfBirth": "1990-05-12",
  "nationality": "US",
  "entityType": "person"
}

Campo	Tipo	Requerido	Descripción
fullName	string 2–200	Sí	Nombre a filtrar
dateOfBirth	string ≤40	No	Fecha de nacimiento
nationality	string ≤120	No	Nacionalidad
entityType	person | entity	No	Tipo de entidad

Respuesta:

{
  "ok": true,
  "match": true,
  "score": 0.92,
  "hits": [
    {
      "name": "JOHN DOE",
      "source": "OFAC-SDN",
      "score": 0.92,
      "programs": ["SDGT"],
      "entityType": "person"
    }
  ]
}

Campo	Descripción
match	true si hay al menos un hit por encima del umbral
score	Mejor puntuación de coincidencia (0–1)
hits[]	Coincidencias: name, source, score, programs, entityType

Fuentes (source): OFAC-SDN, EU, UN, UK-OFSI.

curl -X POST https://kyc.zentto.net/v1/aml/screen \
  -H "X-API-Key: $KYC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"John Doe","entityType":"person"}'

const { match, score, hits } = await kyc.aml.screen({
  fullName: "John Doe",
  entityType: "person",
});

Si fullName tiene menos de 2 caracteres, la API responde 400 invalid_payload.

Refrescar listas (operador)

Recarga (descarga + parseo + UPSERT) todas las listas habilitadas. Operación pesada, pensada para cron o administración. Requiere rol operador.

POST /v1/aml/refresh
X-API-Key: zkyc_<operador>

{ "ok": true, "counts": { "OFAC-SDN": 12000, "EU": 3400, "UN": 1100, "UK-OFSI": 2600 } }

Estado de las listas

GET /v1/aml/status
X-API-Key: zkyc_...

{
  "ok": true,
  "entities": [
    { "source": "EU", "count": 3400 },
    { "source": "OFAC-SDN", "count": 12000 },
    { "source": "UK-OFSI", "count": 2600 },
    { "source": "UN", "count": 1100 }
  ],
  "lastRefresh": [
    {
      "source": "OFAC-SDN",
      "entities": 12000,
      "status": "ok",
      "message": null,
      "created_at": "2026-06-21T03:00:00.000Z"
    }
  ]
}

Campo	Descripción
entities[]	Conteo de entidades por fuente
lastRefresh[]	Último refresco por fuente (entities, status, message, created_at)

Flujo del usuario

Vista no técnica: qué listas revisa el screening y qué ocurre según el resultado.

Editable en draw.io: descarga el SVG → en draw.io: File → Import from → Device → selecciona el SVG. Cada nodo queda editable.

Flujo técnico

Vista técnica: POST /v1/aml/screen → pg_trgm sobre aml_entities (OFAC/EU/UN/UK) → hits → decisión in_review si match.

Componente	Tipo	Ubicación
POST /v1/aml/screen	Route Express	src/aml/routes.ts
POST /v1/aml/refresh	Route Express (rol operador)	src/aml/routes.ts
GET /v1/aml/status	Route Express	src/aml/routes.ts
src/aml/aml.service.ts	Motor de screening pg_trgm	src/aml/aml.service.ts
aml_entities	Tabla sanciones (OFAC/EU/UN/UK, índice GIN pg_trgm)	src/db/migrations/
aml_refresh_log	Historial de refresco por fuente	src/db/migrations/
session_results	Tabla (aml_match, aml_score, aml_hits jsonb)	src/db/migrations/
sessions.orchestrator.ts	Regla: hit → in_review forzado	src/sessions/sessions.orchestrator.ts

Editable en draw.io: descarga el SVG → File → Import from → Device.