API di analisi e metriche

1) Perché un singolo livello API

Una sola verità per il KPI è escludere lo zoo SQL.
Velocità del prodotto: fronti, pannelli di partnership, clienti mobili ricevono unità senza accesso diretto a DWH.
Sicurezza e compilazione: tornitura, maschere, vincoli geo, filtri RG/AML.
Scalabilità: cache, prenders, CDN, contratti stabili.

2) Tassonomia: metriche, misurazioni, fatti

I fatti sono: scommesse, vincite, depositi, eventi KYC, interventi RG.
Misure: data/ora (calendari), gioco/provider, marchio/paese, canale/device, giocatore (token).
Metriche: GGR, NGR/NET, ARPPU, ritenzione D1/D7/D30, frequenza di depositi, FPR antifrode, rischio RG.
Unità: valuta (FX), tempo (TZ), volume/contatori (idempotent!).
Semantica KPI - Le definizioni nei contratti BI, le versioni KPI vengono registrate.

3) Contratti API (Data & BI Contracts)

Schema: campi, tipi, nullable, enum, unità, valute.
Semantica metriche: formula, sorgenti, finestre di aggregazione, filtri.
COMPATIBILITÀ (SEMVER) - MAGGIORE rompe, MINOR aggiunge campi, PATCH registra.
DQ/SLA: freschezza, completezza, consistenza, tolleranza di discrepanze.
Privacy: «pii: false», «tokenized: true», divieto di detonazione.

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) Architettura

Query API (aggregazioni online sopra «gold «/cc/phichestor).
Precompute API (Prenders pianificati, materialization views).
API Events (contatori/segnali in streaming).
Esport API (download firmati, WORM per il controllo).
Cache: multi-livello (in-memory → Redis → CDN), chiave = hash query + versione.
Coerenza: read-your-writes per i record finali, SLA freschezza per le unità.

5) Interfaccia e query

5. 1 Filtri/aggregazioni/finestre

«filter»: intervalli di date («from/to» UTC, timezone aware), paesi, marchi, giochi, canali, device.
«group _ by» - Misurazioni.
«metrics» è una lista di KPI.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
"currency": "reporting" native ", strategia FX:" eod "intraday" txn ".
«sampling»: per le query heavy (solo se consentite).

5. 2 Esempio di query

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 Esempio di risposta

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) Paginazione, limiti, ordinamento

Paginazione: 'limit' (≤10k), 'cursor' (opache), ordinamento per misura/data.
Timeout/partial: risposte parziali solo per KPI non finanziari; la finanza è P200 o P504.
Rate limits: globale/per chiave/per tenante; La risposta è «X-RateLimit -».

7) Idampotenza e cache

Idempotent GET/POST-read con «Idempotency-Key».
Chiave cache = hash (opzioni + versione schema + ruolo/tenante/geo).
TTL: dipendente da KPI (ad esempio, «PT15M» per la revenue, «PT5M» per gli eventi), reimpostato con il nuovo snap.

8) Consistenza e valuta del tempo

Time-travel flag per i report retrospettivi (versione dati).
Cut-off regole (chiusura giorno/settimana).
FX: fissiamo la strategia, la data del corso è la risposta.
Clock: tutte le timeline sono ISO-8601, l'indicazione TZ è obbligatoria.

9) Sicurezza e privacy

mTLS/TLS1. 3, firma HMAC del corpo di richiesta/risposta (protezione da MITM/replay).
RBAC/ABAC/ReBAC: ruolo + paese + marchio + obiettivo; maschere predefinite.
Multi-tenant: isolamento di schemi/chiavi/quote.
Tornitura degli identificatori Proibire il PII nelle risposte.
Controllo: loghi di query invariati (WORM), 'trace _ id '/' attore '/' purpose'.
Consent/DSAR: filtri per gli attributi di marketing il flag «subject erased».

10) RG/AML/Restrizioni antifrode

Criteri RG: impedisce l'emissione di indicatori «aggressivi» per i segmenti high-risk; le apparecchiature sono sicure.
AML/Antifrode: accesso limitato a KPI sensibili, zoning per ruolo; endpoint separati per le indagini.
Esplainability: dizionario di spiegazioni KPI/segnali per lo zapport.

11) Osservabilità e API SLO

SLO: p95 latency (ad esempio, 300 ms per la cache; 2 c per quelle pesanti), success-rate 99. 5%.
DQ: freschezza/completezza/integrità; Le etichette sono nella risposta.
Usage: QPS, hit-rate cache, chiavi hot, errori di convalida.
Alert: degrado della freschezza, crescita 4xx/5xx, anomalie per KPI (unexpected zeros/peaks).
Tracing: «trace _ id» passante fino a DWH/fischiestore.

12) Versioning e compatibilità

Percorsi: '/v1 ', '/v2'; deprecate con finestra di migrazione.
Schemi: 'schema _ version'nella risposta; MAJOR, dual-read, gate migratorie.
Versione KPI: nella risposta «kpi _ definition» con riferimento nella directory; impedisce modifiche nascoste alle formule.

13) Errori e stati

«400» convalida (nessuna metrica/misurazione/combinazione di filtri).
«401/403» autenticazione/autorizzazione.
«409» incompatibilità versione/regole.
«422» violazione della privacy/consent.
quota 429.
«5xx» guasti della piattaforma (con trace _ id e retry- .) .

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

14) Integrazioni e interfacce

BI: modelli semantic predefiniti, connettori (Looker/Power BI/Tableau) → API come origine.
ML: lightweight endpoint per gli aggregati fich (point-in-time, senza PII).
Partner: chiavi/quote limitate, filtri geo, report solo blocchi di aggregazione.
Webhook/Push: notificazioni «snapshot», «disabilitato SLO/intervallo KPI».

15) Esempi di endpoint di risorse

15. 1 Ricavi/rendimenti

'POST/v2/metrics/revenue ', GGR/NGR, puntate/vincite, misurate'date, brand, country, provider, game'.

15. 2 Ritenzione e voragini

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

15. 3 Pagamenti

«POST/v2/metrics/payments» depositi/conclusioni, assegno medio, chargeback rate.

15. 4 Responsible Gaming

'POST/v2/metrics/rg', numero di interventi, quota di high-risk, tempo medio di reazione.

15. 5 Antifrode

'POST/v2/metrics/antifraud' → FPR/TPR, valigette, perdite evitate.

16) Test e qualità

Test contrattuali: enum/nullable/tipo, coerenza valuta/fuso orario.
Test DQ - Controllo degli intervalli, della monotonia e dell'integrità.
Regress: confronto v1/v2 per tolerance.
Carichi: profili di picco (tornei/provider).
Sicurezza: firme, anti-replay, fuzzing query, Zero-PII nei fogli.

17) Privacy predefinita

Aggregazioni con soglie minime N record (k-anonimato).
Nessun ID raw; solo token/categorie.
DSAR: API per scaricare/rimuovere un token attraverso un tracciato privilegiato.

18) Metriche di successo (KPI API)

Adoption: percentuale di report/widget che utilizzano API anziché SQL diretto.
Consistency: discrepanza tra BI e API di tolleranze ≤.
SLO: conformità latency/success/freshness.
Sicurezza: zero casi di PII in risposte/login.
Cost: hit-rate cache, costo richiesta,% prerender.

19) RACI (esempio)

Product/Analytics (A) - definizioni di KPI, esigenze.
Data Platform (R) - Implementazione, cache, SLA, osservabilità.
Domain Owners (R) - fonti/contratti.
Sicurezza/DPO (A/R) - Privacy, accessibilità, verifiche.
SRE (R) - quote, autoscale, incidenti.
Finanza (C) - semantica finanziaria GGR/NGR/NET.

20) Road map di implementazione

0-30 giorni (MVP)

1. Seleziona 3-5 KPI (GGR, depositi, ritenzione D7).
2. Descrivere i contratti e la semantica KPI; includere DQ/SLA.
3. Implementare '/v1 'Query API + cache + mTLS/HMAC.
4. Dashboard SLO (latency/success/freshness), controllo/trace _ id.

30-90 giorni

1. Prenders (Precompute) vetrine popolari, cache CDN.
2. Versioning «/v2 », dual-read, hyde migratorio.
3. Esporta API con download firmati e WORM.
4. Integrazioni con BI/ML; quote/tenanti/geo-isolanti.

3-6 mesi

1. Tassonomia KPI completa e libreria widget.
2. Suggerimenti intelligenti/compilazione automatica filtri, query linter.
3. Release Note KPI automatici, controllo di tolerance v1/v2.
4. Tracciato esterno con chiavi limitate e regole RG.

21) Anti-pattern

Cambio nascosto della formula KPI senza nuova versione e note di uscita.
Restituzione di PII/materie prime invece di unità/token.
La mancanza di cache/prerender è costosa e lenta.
Riferimento rigido a un database specifico (nessuna astrazione di livello).
I numeri non coerenti TZ/FX non sono paragonabili.
Nessun rate limits/quote «DDOS».

22) Modelli (pronto per l'uso)

22. 1 Criterio API SLO (sezione)

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 (sezione)

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 Foglio di assegno di rilascio

• Semantico KPI aggiornato e versione migliorata
• Contratto/schema nella directory; test DQ/regressa verde
• Chiavi cache/TTL, Prenders configurati
• Documentazione e esempi di richieste/risposte
• Gli alert SLO e quote sono inclusi
• Restrizioni RG/AML verificate

23) Partizioni correlate

Utilizzo dei modelli, Etica dei dati, Controllo e versionalità, Protezione e crittografia, Controllo degli accessi, Torning dei dati, Regole di conservazione, Origine e percorso dei dati, MLOps.

Totale

L'API di analisi e metriche è un livello contrattato, sicuro e veloce di accesso ai dati «oro» e KPI. Garantisce un'unica semantica, versioni stabili, privacy predefinita e prestazioni a livello di prodotto, dai dashboard interni ai pannelli associati e ML.