Analytics and Metrics API

1) De ce un strat API separat

Un singur adevăr pentru KPI: excludeți „SQL zoo”.
Viteza produsului: fronturi, panouri partenere, clienții mobili primesc agregate fără acces direct la DWH.
Securitate și conformitate: tokenizare, măști, geo-restricții, filtre RG/AML.
Scalare: cache, prerenders, CDN, contracte stabile.

2) Taxonomie: metrici, dimensiuni, fapte

Fapte: pariuri, câștiguri, depozite, evenimente KYC, intervenții RG.
Dimensiuni: data/ora (calendare), joc/furnizor, brand/tara, canal/dispozitiv, jucator (token).
Valori: GGR, NGR/NET, ARPPU, retenție D1/D7/D30, frecvența depozitelor, FPR antifraudă, risc RG.
Unități: valută (FX), timp (TZ), volum/contoare (idempotent!).
Semantica KPI: definițiile din contractele BI, versiunile KPI sunt fixe.

3) Contracte de date și BI

Schema: domenii, tipuri, nullable, enum, unități, valute.
Semantica metricii: formulă, surse, ferestre de agregare, filtre.
Compatibilitate (SEMVER): pauze majore, câmpuri MINOR adaugă, corecții PATCH.
DQ/SLA: prospețime, completitudine, consistență, toleranțe de discrepanță.
Confidențialitate: 'pii: false', 'tokenized: true', interzicerea detokenizării.

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

Query API (agregare online peste „aur „/cuburi/fichestore).
Precompute API (prerenders programate, vizualizări materializate).
Evenimente API (contoare de flux/semnale).
Export API (încărcări semnate, WORM pentru audit).
Cache: în memorie → Redis → CDN, cheie = interogare hash + versiune.
Consistență: citiți-vă-scrie pentru înregistrări finale, SLA prospețime pentru agregate.

5) Interfață și cereri

5. 1 Filtre/agregări/ferestre

„filter”: intervale de date („de la/la” UTC, fus orar conștient), țări, mărci, jocuri, canale, dispozitive.
'group _ by': dimensiuni.
„metrică”: lista KPI-urilor.
'window': 'DAY' WEEK 'MONTH ROLLING _ 7D' ROLLING _ 28D '.
"monedă": "raportarea" nativă ", strategia FX:" eod "intraday 'txn'.
„eșantionare”: pentru interogări grele (numai acolo unde este permis).

5. 2 Example de cerere

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 Exemplu de răspuns

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) Paginare, limite, sortare

Paginare: „limită” (≤10k), „cursor” (opac), sortare după dimensiuni/dată.
Timeout/parțial: răspunsuri parțiale numai pentru KPI-urile nefinanciare; finanțe - fie P200, fie P504.
Limite de tarif: global/pe cheie/pe chiriaș; răspunsul conţine „X-RateLimit-”.

7) Idempotența și memoria cache

Idempotent GET/POST-read (cu corp) cu 'Idempotency-Key'.
Cheie cache = hash (parametri + versiune schema + rol/chiriaș/geo).
TTL: dependentă de KPI (de ex. „PT15M” pentru venituri, „PT5M” pentru evenimente), resetați cu un nou instantaneu.

8) Coerența și moneda timpului

Steag de călătorie în timp pentru rapoarte retrospective (versiuni de date).
Reguli de întrerupere (închidere zi/săptămână).
FX: stabilim strategia, data cursului în răspuns.
Ceas: toate marcajele de timp sunt ISO-8601, TZ este necesar.

9) Securitate și confidențialitate

mTLS/TLS1. 3, semnătura HMAC a organismului de solicitare/răspuns (protecție MITM/reluare).
RBAC/ABAC/ReBAC: rol + țară + brand + scop; măști implicite.
Multi-chiriaș - Izolați scheme/chei/cote.
Tokenizarea identificatorilor; Interdicția PII în răspunsuri.
Audit: jurnale de cerere imuabile (WORM), 'trace _ id'/' actor '/' scop'.
Consimțământ/DSAR: filtre privind atributele de marketing; „subiect şters” steag.

10) RG/AML/Restricție antifrode

Politici RG: interzicerea emiterii de indicatori „agresivi” pentru segmentele cu risc ridicat; unităţile sunt în siguranţă.
AML/Antifraudă: acces limitat la KPI-uri sensibile, zonare după rol; criterii finale separate pentru investigații.
Explicabilitate: dicționar de explicații ale KPI/semnale pentru suport.

11) Observabilitate și API SLO

SLO: p95 latență (de exemplu, ≤ 300 ms pentru hit-uri cache, ≤ 2 s pentru grele), rata de succes ≥ 99. 5%.
DQ: prospețime/exhaustivitate/integritate; etichete în răspunsul.
Utilizare: QPS, cache hit-rate, hot keys, erori de validare.
Alerte: degradarea prospețimii, creșterea 4xx/5xx, anomalii în funcție de KPI (zerouri/vârfuri neașteptate).
Urmărire: 'trace _ id' end-to-end to DWH/fichestore.

12) Versioning și compatibilitate

Căi: „/v1 ”, „/v2”; se depreciază cu fereastra de migrare.
Scheme: „schema _ versiune” ca răspuns; MAJOR → ghiduri de migrare cu citire dublă.
Versiuni KPI: în răspunsul „kpi _ definitions” cu o legătură în director; Împiedicați modificările formulelor ascunse.

13) Erori și stări

'400' validare (combinaţie metrică/de măsurare/filtrare inexistentă).
'401/403' authentication/autorization.
'409' versiune/incompatibilitate politică.
'422' privacy/consimțământ încălcare.
'429' cote.
'5xx' platform failures (trace_id și încercați din nou seq.).

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

14) Integrări și interfețe

BI: modele semantice pre-descrise, conectori (Looker/Power BI/Tableau) → API ca sursă.
ML: criterii finale ușoare pentru unitățile caracteristice (punct în timp, fără PII).
Parteneri: chei/cote limitate, geo-filtre, rapoarte numai în blocuri agregate.
Webhook/Push: notificări „instantaneu gata”, „rupt gama SLO/KPI”.

15) Exemple de puncte finale ale resurselor

15. 1 Venituri/Returnare

„POST/v2/metrici/venituri” → GGR/NGR, pariuri/câștiguri, măsurate prin „data, marca, țara, furnizorul, jocul”.

15. 2 Retenție și pâlnii

'POST/v2/metrics/retention' → когорты D1/D7/D30, 'group _ by = [cohort _ week, brand, country]'.

15. 3 Plăți

"POST/v2/metrics/payments' → depozite/retrageri, verificare medie, rata de chargeback.

15. 4 Joc Responsabil

„POST/v2/metrics/rg” → numărul de intervenții, proporția de risc ridicat, timpul mediu de reacție.

15. 5 Antifraudă

„POST/v2/metrics/antifraudă” → FPR/TPR, cazuri, pierderi prevenite.

16) Testarea și calitatea

Încercări de contract: enum/nullable/type, valută/consistență fus orar.
Teste DQ: controlul intervalelor, monotoniei și integrității.
Regresie: comparație v1/v2 privind toleranțele.
Încărcare: profiluri de vârf (turnee/evenimente furnizor).
Securitate: semnături, anti-reluare, cereri de fuzzing, Zero-PII în jurnalele.

17) Confidențialitate în mod implicit

Agregate cu praguri de „înregistrări minime N” (k-anonimat).
Nu există identificatori bruți; numai jetoane/categorii.
DSAR: API pentru descărcare/ștergere prin token printr-o buclă privilegiată.

18) Măsurători de succes (KPI-uri API)

Adopție: Proporția de rapoarte/widget-uri care utilizează API, mai degrabă decât SQL direct.
Coerența - discrepanța dintre BI și toleranța ≤ API.
SLO: respectarea latenței/succesului/prospețimii.
Securitate: zero cazuri PII în răspunsuri/jurnale.
Cost: rata de succes a memoriei cache, costul cererii,% din prerenders.

19) RACI (exemplu)

Produs/Analytics (A) - definiții KPI, cerințe.
Platforma de date (R) - implementare, cache, SLA, observabilitate.
Proprietarii de domenii (R) - Surse/Contracte.
Securitate/DPO (A/R) - confidențialitate, acces, audituri.
SRE (R) - cote, autoscale, incidente.
Finance (C) este semantica financiară a GGR/NGR/NET.

20) Foaia de parcurs privind implementarea

0-30 zile (MVP)

1. Selectați 3-5 KPI-uri (GGR, depozite, retenție D7).
2. Descrieți contractele și semantica KPI; Activați DQ/SLA.
3. Implementați „/v1 ”interogare API + cache + mTLS/HMAC.
4. Tablouri de bord SLO (latență/succes/prospețime), audit/trace _ id.

30-90 zile

1. Precompute storefronturi populare, cache CDN.
2. Versioning '/v2 ', dual-read, ghid de migrare.
3. Exportați API-uri cu încărcări semnate și WORM-uri.
4. Integrarea cu BI/ML; cote/chiriași/geo-izolatori.

3-6 luni

1. Completați taxonomia KPI și biblioteca widget.
2. Sfaturi inteligente/filtre autocomplete, interogare linter.
3. Note automate de eliberare KPI, controlul toleranțelor v1/v2.
4. Buclă parteneră externă cu taste restricționate și politici RG.

21) Anti-modele

Formula KPI ascunsă se schimbă fără o versiune nouă și note de lansare.
Returnați PII/materii prime în loc de agregate/jetoane.
Lipsa de cache/prerenders → costisitoare și lente.
Legare dură la o bază de date specifică (fără abstracție de strat).
Inconsecvente TZ/FX → numere disparate.
Nu există limite/cote de rată → „DDOS propriu”.

22) Șabloane (gata de utilizare)

22. 1 Politică API SLO (fragment)

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

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 verificare a lansării

• Semantica KPI actualizată și versiunea actualizată
• Contract/schemă în catalog; DQ/încercări de regresie verde
• Chei cache/TTL, prerenders configurate
• Documentație și cereri de probă/răspunsuri
• Alerte SLO și cote incluse
• Constrângeri RG/AML testate

23) Secțiuni conexe

Practici DataOps, audit și versioning, securitate și criptare, controlul accesului, tokenizarea datelor, politici de păstrare, originea și calea datelor, MLOps: model de exploatare, etica datelor.

Total

API-urile de analiză și metrică sunt un strat contractat, sigur și rapid de acces la date de aur și KPI-uri. Acesta garantează semantică uniformă, versiuni stabile, confidențialitate implicită și performanță la nivel de produs - de la tablouri de bord interne la panouri partenere și ML.