API de cumplimiento e informes

1) Asignación

• Recopilación y validación de eventos (juego/pago/autenticación) para AML/Juego responsable (RG).
• Realización de inspecciones (KYC/KYB, sanciones/RR, fuentes de fondos, edad).
• Elaboración de informes regulatorios (periódicos y ad-hoc) sobre los mercados.
• Mantenimiento de registros de auditoría y ejecución de Legal Hold.
• Intercambio de datos con proveedores (PSP, intercambios KYC, listas de sanciones) y portales de gos.

Resultado: se reduce la carga operativa, se acelera la preparación de informes, se garantiza la rastreabilidad y el cumplimiento de las normas locales.

2) Alcance (scope)

Identificación y verificación: KYC/KYB estados, niveles de verificación, documentos.
AML/sanciones/PEP: cribado, monitoreo de transacciones, NAT/SAR, alertas.
Juego responsable (RG): límites, autoexclusión, «cool-off», escalas de riesgo conductual.
Pagos y transacciones: depósitos/retiros, chargeback, mecánicas de bonificación.
Informes: GGR/impuestos, registros de jugadores/sesiones, restricciones de marketing, incidentes de seguridad.
Auditoría y almacenamiento: registros inmutables (WORM), Legal Hold, DSAR/RTBF.

3) Consumidores y productores de datos

Usuarios: reguladores, Compliance/Risk interno, BI/DWH, SecOps, finanzas.
Fabricantes: frentes/respaldo iGaming, PSP/Aquiring, proveedores KYC, antifraude, CRM, redes de afiliados.

4) Referencia arquitectónica

1. Edge/API-шлюз (mTLS, OAuth2/OIDC, rate-limit, WAF).
2. Servicio de cumplimiento (reglas de negocio, orquestación de proveedores, normalización).
3. El bus de eventos (Kafka/Redpanda) es un fan out en SIEM/DWH/archivo.

• En línea (PostgreSQL/ClickHouse) para consultas/agregaciones rápidas.
• Archivo (Object Storage + WORM) para artefactos e informes inmutables.
• 5. Auditoría y Observabilidad: OpenTelemetry (trace_id), indexación de registros, dashboards.
• 6. Conectores de proveedores: KYC, sanciones, módulos RG, portales gos con firma electrónica.

5) Endpoints principales (v1)

5. 1 KYC/KYB y sanciones

'POST/v1/kyc/check' es una solicitud de verificación KYC (idempotente).
'GET/v1/kyc/{ user _ id }/status' es el nivel actual y la fecha de caducidad.
'POST/v1/sanctions/screen' - cribado sancionador/RER.
'GET/v1/sanctions/{ user _ id }/hits' - coincidencias/escaladas.

5. 2 AML y monitoreo de transacciones

'POST/v1/aml/transaction' es el envío de un evento (depósito/withdraw/bet/payout).
`GET /v1/aml/alerts? state = open '- alertas/casos abiertos.
'POST/v1/aml/aprox' - Formación y presentación de RTE/RAE (por mercado).

5. 3 Responsible Gaming (RG)

'POST/v1/rg/self-exclusion' - instalación/eliminación de la autoexclusión.
'GET/v1/rg/limits/{ user _ id}' - límites (depósito/apuesta/tiempo).
'POST/v1/rg/assess' - evaluación del riesgo de comportamiento.

5. 4 Informes y registros

'POST/v1/reports/generate' - generación de informe (tipo, período, jurisdicción).
'GET/v1/reports/{ report _ id}' - estado, carga del artefacto (PDF/CSV/JSON), hash.
'GET/v1/registries/{ type}' - registros (jugadores, sesiones, bonos, GGR) con paginación.

5. 5 Auditorías y operaciones legales

'GET/v1/audit/events' es una muestra de eventos (filtro por campos ECS/OCSF).
'POST/v1/legal/hold' - Instalación/desactivación de Legal Hold por objeto/carpeta.
'POST/v1/privacy/dsar' - ejecutar DSAR, estados, exportar paquetes.

6) Modelos de datos (abreviado)

6. 1 Evento de transacción (JSON)

json
{
"idempotency_key": "trx-8b1a9953",
"timestamp": "2025-11-01T16:02:11Z",
"user": {"id":"U-12345","dob":"1999-04-21","country":"EE"},
"transaction": {
"id": "T-778899",
"type": "deposit",
"amount": {"value": 200. 00, "currency": "EUR"},
"method": "card",
"psp_ref": "PSP-222-ABC"
},
"context": {
"ip": "198. 51. 100. 10",
"device_id": "d-9af0",
"session_id": "s-2233",
"trace_id": "f4c2..."
},
"labels": {"market": "EE", "affiliate": "A-77"}
}

6. 2 Resultado KYC

json
{
"user_id": "U-12345",
"level": "L2",
"status": "verified",
"expires_at": "2026-04-21",
"checks": [
{"type":"document","result":"pass"},
{"type":"liveness","result":"pass"},
{"type":"pep_sanctions","result":"no_hit"}
],
"provider": {"name":"KYCX","reference":"KYCX-4455"}
}

6. 3 Descripción del informe

json
{
"report_id": "RPT-EE-GGR-2025Q3",
"type": "ggr_quarterly",
"jurisdiction": "EE",
"period": {"from":"2025-07-01","to":"2025-09-30"},
"status": "ready",
"artifact": {
"format": "CSV",
"size_bytes": 183442,
"sha256": "c9b1f...e21",
"download_url": "urn:reports:RPT-EE-GGR-2025Q3"
},
"notes": "Rounded to cents; FX=ECB daily"
}

7) Seguridad y acceso

Autenticación: OAuth2/OIDC (clientes credentials, JWT), opcional mTLS.
Autorización: RBAC/ABAC; scopes individuales por dominios ('aml: write', 'kyc: read', 'reports: generate').
Cifrado: TLS 1. 2+ in-transit; a través de KMS/CMK; JWE para campos sensibles.
PII-minimización: almacenar el mínimo; enmascarar PAN/IBAN; alias 'user. pseudo_id`.
Registro de acceso: auditar todas las lecturas de endpoints «sensibles», alertas para descargas masivas.
Legal Hold and Retenshing: almacenamiento de información WORM para Reporting y NAT; política de retención 5-7 años (por mercados).

8) Versificación e interoperabilidad

Versión URI: '/v1 ', '/v2'; cambios menores - a través de campos extensibles.
Deprecation-policy: ≥ 6-12 meses de soporte; títulos 'Sunset', 'Deprecation'.
Esquemas: JSON Schema + OpenAPI; los contratos se validan en CI.
Migraciones: adaptadores/banderas de función, interoperabilidad bidireccional para el período de transición.

9) Confiabilidad: idempotencia y «exactamente una vez»

Idempotency-Key en 'POST' (almacenar las llaves ≥ 24-72 h).
Entrega a través del bus + deduplicación en recepción (event id/hash).
Outbox/Inbox-pattern para integraciones, retraídas con pausa exponencial y jitter.
Orden: claves de partición 'user _ id '/' account _ id' para determinismo.

10) Paginación, filtros, búsqueda

Paginación: cursor-basado ('page _ token', 'limit <= 1000').
Filtros: por jurisdicción, período, estado, proveedor, evaluación de riesgos.
Búsqueda de texto completo: para auditorías/registros (subconjunto limitado de campos).
Exportación: asíncrono, límite de tamaño, preparación del archivo con firma hash.

11) Restricciones y cuotas

Rate-limits per client/route (por ejemplo, 100 rps burst, 1000 rpm sustentados).
Budget-limits para informes pesados (créditos/día).
Protección contra N + 1: batches y endpoints agregados.
Limitar la profundidad de las muestras históricas (por ejemplo, ≤ 24 meses en línea, en adelante archivo).

12) Dashboards y SLO

Ingest lag p95 <30 segundos; El éxito de KYC> 99%; NAT-SLA - Envío ≤ 24 h.
Disponibilidad de la API ≥ 99. 9%; Latency p95 <300 ms para leer; <800 ms para grabar.
Costo/GB de almacenamiento de informes; Ack-rate notificaciones a los reguladores.
Widgets: Tarjeta de calor de alertas AML, embudo KYC, publicación de informes por país, cola NAT.

13) Jurisdicciones: mapping y plantillas

Plantillas de informes de mercado (campos, formatos, frecuencia): 'EE', 'LT',' LV ',' RO ',' MT ',' UK ', etc.
Términos de mapeo (GGR/NGR, bonificaciones, límites de depósitos, control de edad).
Localización de temporizadores/calendarios; fijación de la fuente FX; etiqueta de influencia DST.
Directorio de esquemas: 'reports/{ jurisdiction }/{ type }/{ version} .schema. json`.

14) Manejo de errores (formato único)

json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"request_id": "req-7f91",
"hint": "Reduce RPS or request higher quota",
"retry_after": 30
}
}

Частые коды: `INVALID_SCHEMA`, `NOT_AUTHORIZED`, `LEGAL_HOLD_ACTIVE`, `PROVIDER_TIMEOUT`, `REPORT_NOT_READY`.

15) Pruebas y certificación

Pruebas contractuales (OpenAPI → generación de clientes de prueba).
Conjuntos de fixtures por jurisdicciones, ficheros de oro para informes.
«Listas negras» de campos PII en los logs; análisis estático de filtraciones de secretos.
Ejercicios regulares de recuperación de archivos de informes DR.

16) Ejemplos

16. 1 Generación de informes

Consulta

http
POST /v1/reports/generate
Content-Type: application/json
Authorization: Bearer <token>

json
{
"type": "ggr_monthly",
"jurisdiction": "EE",
"period": {"from":"2025-10-01","to":"2025-10-31"},
"format": "CSV",
"notify": ["compliance@company"],
"parameters": {"include_bonus_breakdown": true}
}

la Respuesta

json
{"report_id":"RPT-EE-GGR-2025-10","status":"processing","eta_seconds":120}

16. Envío de 2 NAT/SAR

json
{
"case_id": "AML-2025-0091",
"user_id": "U-12345",
"reason": "Structuring deposits under threshold",
"evidence": ["txn:T-778899","txn:T-778900"],
"attachments": ["urn:doc:kyc:U-12345:v3"],
"jurisdiction": "EE"
}

16. 3 Autoexclusión

json
{
"user_id":"U-12345",
"type":"national_register",
"action":"enable",
"effective_from":"2025-11-01",
"effective_to":"2026-11-01"
}

17) Auditoría incorporada e inmutabilidad

Autologia: 'request _ id', 'trace _ id' que llama al cliente, scope.
Firma de paquetes de informes (SHA-256) + registro de hashes; Anclaje periódico.
Archivo WORM para descargas reglamentarias y NAT.
Historial de configuraciones de reglas y plantillas (registro de cambios de directivas ↔ link).

18) Procesos y RACI (brevemente)

R: El equipo de Compliance Platform (desarrollo/operaciones).
R: Head of Compliance/CISO (políticas, presupuestos, prioridades).
C: Legal/DPO, Finanzas, Arquitectura, Datos.
I: Producto, Soporte, Socios (PSP/KYC).

19) Hoja de ruta para la aplicación

1. '/v1/kyc/check ', '/v1/aml/transaction', '/v1/reports/generate '(2-3 plantillas clave).

2. OAuth2 + rate-limit + idempotencia básica.

3. Archivo de informes en Object Storage con firma hash.

4. Dashboard SLO y colas de tareas.

• Plantillas jurisdiccionales (5-8 mercados), NAT/SAR, RG-endpoints, DSAR.
• Proveedor de agregación (CUS/sanciones), retraídas, dedupe.
• Políticas Legal Hold, WORM, roles avanzados.

• Rule-as-Code para informes/reglas AML, simulador de cambios.
• Multi-tenencia (B2B2C, marcas/pieles), cuotas y facturación.
• Sandbox y certificación para integradores externos.

20) Errores estándar y cómo evitarlos

Varios esquemas por mercados: catálogo centralizado, esquemas auto-lint.
Sin idempotencia: escriba 'idempotency _ key' y la ventana de deduplicación.
Secretos en los logs: filtros en ingest, análisis estático.
Informes largos en línea: hacer asíncronos con status-pulling y notificaciones.
RBAC débil: separe 'read _ reports',' generate _ reports', 'admin'.
Moneda/Timesone: fijar 'fx _ source', 'timezone', almacenar UTC.

21) Glosario (breve)

KYC/KYB - Identificación física/jure. Las personas.
AML/AMB/SAR - lucha contra el blanqueo/actividad/comunicación sospechosa.
RG es un juego responsable.
GGR/NGR es el ingreso bruto/neto de los juegos.
WORM - Almacenamiento inmutable (write-once).
Rule-as-Code - Reglas como código con pruebas/versificación.

22) Resultado

La API de cumplimiento y reporting es una capa estable, segura y estandarizada entre las operaciones de iGaming y los requisitos de los reguladores. El cumplimiento de los principios de este artículo (esquemas estrictos, integración segura, idempotencia, auditoría inmutable, plantillas jurisdiccionales y SLO) garantiza la previsibilidad, la rápida aprobación de los controles y la reducción de los riesgos en los mercados clave.