APIs de análisis y métricas

1) Por qué una capa de API separada

Verdad unificada para KPI: excluimos el «zoológico SQL».
Velocidad del producto: frentes, paneles de afiliados, clientes móviles obtienen unidades sin acceso directo a DWH.
Seguridad y cumplimiento: tokenización, máscaras, restricciones geográficas, filtros RG/AML.
Escalar: caché, prendedores, CDN, contratos estables.

2) Taxonomía: métricas, medidas, hechos

Hechos: apuestas, ganancias, depósitos, eventos KYC, intervenciones RG.
Medidas: fecha/hora (calendarios), juego/proveedor, marca/país, canal/dispositivo, jugador (token).
Métricas: GGR, NGR/NET, ARPPU, retención de D1/D7/D30, frecuencia de depósito, FPR antifraude, riesgo RG.
Unidades: moneda (FX), tiempo (TZ), volumen/contadores (idempotent!).
KPI semántica: definiciones en contratos BI, versiones de KPI fijadas.

3) Contratos de API (Contratos de Data & BI)

Schema: campos, tipos, nullable, enum, unidades, monedas.
métricas semánticas: fórmula, fuentes, ventanas de agregación, filtros.
Compatibilidad (SEMVER): MAJOR rompe, MINOR agrega campos, PATCH fija.
DQ/SLA: frescura, plenitud, consistencia, tolerancias de discrepancia.
Privacidad: 'pii: false', 'tokenized: true', prohibición de desintoxicación.

yaml api: analytics. v2 resource: /metrics/revenue kpi: GGR schema_version: 2. 1. 0 dimensions: [date, brand, country, provider, game]
metrics: [ggr, stakes, wins, bets_count]
sla: {freshness: PT15M, completeness: ">=99. 9%"}
privacy: {pii: false, tokenized: true}

4) Arquitectura

Query API (agregaciones en línea sobre "gold'/cubos/ficheros).
API de preconcomputo (preemergentes programados, vistas materializadas).
API de eventos (contadores/señales de streaming).
API de exportación (descargas firmadas, WORM para auditoría).
Caché: multicapa (in-memory → Redis → CDN), clave = hash de consulta + versión.
Consistencia: read-your-writes para las grabaciones finales, frescura SLA para las unidades.

5) Interfaz y consultas

5. 1 Filtros/agregaciones/ventanas

'filter': rangos de fechas ('from/to' UTC, timezone aware), países, marcas, juegos, canales, dispositivos.
'group _ by': medidas.
'metrics': lista de KPI.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency': 'reporting' native ', estrategia de FX:' eod 'intraday' txn'.
'sampling': para consultas heavy (sólo donde es admisible).

5. 2 Ejemplo de consulta

json
POST /v2/metrics/revenue
{
"range": {"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"group_by": ["date","brand","country"],
"metrics": ["ggr","bets_count","net_revenue"],
"filters": {"country":["EE","LT","LV"],"brand":["alpha","beta"]},
"currency": "reporting",
"window": "DAY"
}

5. 3 Ejemplo de respuesta

json
{
"schema_version":"2. 1. 0",
"kpi_definitions":["ggr@1. 7. 0","net_revenue@1. 3. 2"],
"range":{"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"data":[
{"date":"2025-10-01","brand":"alpha","country":"EE","ggr":12450. 72,"bets_count":182342,"net_revenue":10732. 11},
{"date":"2025-10-01","brand":"beta","country":"EE","ggr":...}
],
"fx":{"strategy":"eod","rate_date":"2025-10-31"},
"dq":{"freshness_sec":420,"completeness":0. 9992},
"trace_id":"3d1a-...-c79"
}

6) Paginación, límites, clasificación

Paginación: 'limit' (≤10k), 'cursor' (opaque), ordenamiento por medida/fecha.
Timeout/partial: respuestas parciales sólo para KPI no financieros; finanzas, ya sea P200 o P504.
Rate limits: global/por clave/por tenant; la respuesta contiene 'X-RateLimit-'.

7) Idempotencia y caché

Idempotent GET/POST-read (con cuerpo) con 'Idempotency-Key'.
Clave caché = hash (opciones + versión del esquema + rol/tenant/geo).
TTL: dependiente de KPI (por ejemplo, 'PT15M' para revenue, 'PT5M' para eventos), restablecimiento en un nuevo snapshot.

8) Consistencia y moneda del tiempo

Indicador de tiempo de viaje para informes retrospectivos (versiones de datos).
Reglas de corte (cierre de día/semana).
FX: fijamos la estrategia, la fecha del curso en la respuesta.
Clock: todos los timestemps son ISO-8601, la indicación TZ es obligatoria.

9) Seguridad y privacidad

mTLS/TLS1. 3, firma HMAC del cuerpo de solicitud/respuesta (protección MITM/respuesta).
RBAC/ABAC/ReBAC: rol + país + marca + objetivo; máscaras predeterminadas.
Multiarrendamiento (multi-tenant): aislamiento de circuitos/claves/cuotas.
Tokenización de identificadores; Prohibición de PII en las respuestas.
Auditoría: Registros de consulta sin cambios (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: filtros en atributos de marketing; la bandera «subject erased».

10) Restricciones RG/AML/antifraude

Políticas de RG: prohibición de emitir indicadores «agresivos» para segmentos de alto riesgo; las unidades son seguras.
AML/Antifraude: acceso limitado a KPI sensibles, zonificación por roles; Endpoints separados para investigaciones.
Explainability: diccionario de explicaciones de KPI/señales para sapport.

11) Observabilidad y API SLO

SLO: p95 latencia (por ejemplo, ≤ 300 ms para hits de caché; ≤ 2 s para heavy), tasa de éxito ≥ 99. 5%.
DQ: frescura/integridad/integridad; etiquetas en la respuesta.
Usage: QPS, hit-rate caché, teclas calientes, errores de validación.
Alertas: degradación de la frescura, crecimiento de 4xx/5xx, anomalías por KPI (zeros/peaks unexpected).
Tracing: 'trace _ id' de extremo a extremo a DWH/fichastor.

12) Versificación e interoperabilidad

Rutas: '/v1 ', '/v2'; deprechate con ventana de migración.
Esquemas: 'schema _ version' en la respuesta; MAJOR → dual-read, gaidas migratorias.
Versiones KPI: en la respuesta 'kpi _ definitions' con un enlace en el directorio; prohibición de cambios ocultos de fórmulas.

13) Errores y estados

'400' validación (métrica/medición/combinación de filtros inexistente).
'401/403' autenticación/autorización.
'409' incompatibilidad de versiones/políticas.
'422' violación de la confidencialidad/consent.
'429' de cuota.
fallas de plataforma '5xx' (con trace_id y retry-aprox.) .

json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}

14) Integraciones e interfaces

BI: modelos semánticos pre-descritos, conectores (Looker/Power BI/Tableau) → API como fuente.
ML: lightweight endpoints para unidades de alimentación (punto en tiempo, sin PII).
Socios: claves/cuotas limitadas, geo-filtros, informes sólo por bloques agregados.
Webhook/Push: notificaciones de «snapshot ready», «SLO/rango de KPI roto».

15) Ejemplos de endpoints de recursos

15. 1 Ingresos/rendimientos

'POST/v2/metrics/revenue' → GGR/NGR, apuestas/ganancias, según las medidas 'date, brand, country, provider, game'.

15. 2 Retención y embudos

`POST /v2/metrics/retention` → когорты D1/D7/D30, `group_by=[cohort_week, brand, country]`.

15. 3 Pagos

'POST/v2/metrics/payments' → depósitos/retiros, cheque medio, tasa de chargeback.

15. 4 Responsible Gaming

'POST/v2/metrics/rg' → número de intervenciones, proporción de alto riesgo, tiempo medio de reacción.

15. 5 Antifraude

'POST/v2/metrics/antifraud' → FPR/TPR, casos, pérdidas evitadas.

16) Pruebas y calidad

Pruebas contractuales: enum/nullable/tipo, consistencia de divisas/zonas horarias.
Pruebas DQ: control de rangos, monotonía e integridad.
Regresión: comparación v1/v2 por tolerancias.
Carga: perfiles de picos (torneos/eventos de proveedores).
Seguridad: firmas, anti-replay, fuzzing solicitudes, Zero-PII en los logs.

17) Privacidad predeterminada

Agregados con umbrales «mínimo N registros» (k-anonimato).
No hay identificadores raw; sólo tokens/categorías.
DSAR: API para descargar/eliminar por token a través de un bucle privilegiado.

18) Métricas de éxito (API de KPI)

Adopción: proporción de informes/widgets que utilizan la API en lugar de SQL directa.
Consistencia: discrepancia entre BI y API ≤ tolerancias.
SLO: cumplimiento de latencia/éxito/freshness.
Seguridad: cero casos de PII en respuestas/logs.
Costo: hit-rate caché, costo de la consulta,% de los prerrenders.

19) RACI (ejemplo)

Product/Analytics (A) - definiciones de KPI, necesidades.
Plataforma de datos (R): implementación, caché, SLA, observabilidad.
Domain Owners (R) - Fuentes/Contratos.
Seguridad/DPO (A/R) - privacidad, accesos, auditorías.
SRE (R) - cupos, autocaravana, incidentes.
Finance (C) es la semántica financiera de GGR/NGR/NET.

20) Hoja de ruta para la implementación

0-30 días (MVP)

1. Elija 3-5 KPI (GGR, depósitos, retención D7).
2. Describir contratos y KPI-semántica; habilitar DQ/SLA.
3. Implementar '/v1 'Query API + caché + mTLS/HMAC.
4. SLO (latency/success/freshness), auditoría/trace _ id.

30-90 días

1. Precomputadores (Precompute) de escaparates populares, caché CDN.
2. Versioning '/v2 ', dual-read, hyde migratorio.
3. Exportación de API con descargas firmadas y WORM.
4. Integraciones con BI/ML; cupos/tenantes/geo-aisladores.

3-6 meses

1. Taxonomía completa de KPI y biblioteca de widgets.
2. Consejos inteligentes/autocompletar los filtros, linter de las consultas.
3. Notas automáticas KPI Release, control de tolerancias v1/v2.
4. Un circuito de socios externos con claves limitadas y políticas RG.

21) Anti-patrones

Cambio oculto de la fórmula KPI sin nueva versión y notas de lanzamiento.
Devolución de PII/materias primas en lugar de unidades/tokens.
La ausencia de caché/prerrenders es → costosa y lenta.
Ajuste rígido a un DAB específico (sin abstracción de capa).
TZ/FX inconsistentes → números incomparables.
No hay rate limits/cuotas → «DDOS propios».

22) Plantillas (listas para usar)

22. 1 Política de API de SLO (fragmento)

yaml api: analytics. v2 slo:
p95_latency_ms: 300 success_rate: 0. 995 freshness_sec_max: 900 quotas:
per_key_qps: 50 burst: 200 privacy:
min_group_size: 25 pii_in_response: false

22. 2 OpenAPI (fragmento)

yaml paths:
/v2/metrics/revenue:
post:
requestBody:
content:
application/json:
schema: {$ref: '#/components/schemas/RevenueQuery'}
responses:
'200': {description: 'OK', content: {application/json: {schema: {$ref:'#/components/schemas/RevenueResponse'}}}}
'422': {description:'Privacy/Consent violation'}

22. 3 Lista de comprobación de lanzamiento

• KPI-semántica actualizada y versión mejorada
• Contrato/esquema en el catálogo; pruebas verdes del DQ/de la regresión
• Claves de caché/TTL, preconfigurados
• Documentación y ejemplos de consultas/respuestas
• Alertas de SLO y cuotas incluidas
• Restricciones RG/AML verificadas

23) Secciones relacionadas

Prácticas de DataOps, Auditoría y Versionabilidad, Seguridad y Cifrado, Control de Acceso, Tokenización de Datos, Políticas de Retención, Origen y Ruta de Datos, MLOps: Explotación de Modelos, Ética de Datos.

La API de análisis y métricas es una capa contratada, segura y rápida de acceso a datos «dorados» y KPI. Garantiza una sola semántica, versiones estables, privacidad predeterminada y rendimiento a nivel de producto, desde dashboards internos hasta paneles de afiliados y ML.