API analytique et métriques

1) Pourquoi une couche API distincte

Une seule vérité pour KPI : nous excluons le "zoo SQL'.
Vitesse du produit : fronts, panneaux partenaires, clients mobiles reçoivent des agrégats sans accès direct à DWH.
Sécurité et conformité : Tokenization, masques, géo-restrictions, filtres RG/AML.
Mise à l'échelle : Cache, prérendeurs, CDN, contrats stables.

2) Taxonomie : métriques, mesures, faits

Faits : paris, gains, dépôts, événements KYC, interventions RG.
Mesures : date/heure (calendriers), jeu/fournisseur, marque/pays, canal/device, joueur (token).
Métriques : GGR, NGR/NET, ARPPU, rétention de D1/D7/D30, taux de dépôt, antifrood FPR, risque RG.
Unités : devise (FX), temps (TZ), volume/compteurs (idempotent !).
Sémantique KPI : définitions dans les contrats BI, versions KPI sont fixes.

3) Contrats API (Contrats Data & BI)

Schema : champs, types, nullable, enum, unités, devises.
Métriques sémantiques : formule, sources, fenêtres d'agrégation, filtres.
Compatibilité (SEMVER) : MAJOR casse, MINEUR ajoute des champs, PATCH fixe.
DQ/SLA : fraîcheur, exhaustivité, consistance, tolérances de divergence.
Intimité : 'pii : false', 'tokenized : true', interdiction de désintoxication.

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

API Query (agrégations en ligne sur "gold'/cubes/fichestor).
API precompute (Precompute programmé, materialized views).
API Events (compteurs/signaux de flux).
API d'exportation (déchargement signé, WORM pour audit).
Cache : multicouche (in-memory → Redis → CDN), clé = hachage de requête + version.
Cohérence : read-your-writes pour les enregistrements finaux, SLA fraîcheur pour les agrégats.

5) Interface et demandes

5. 1 Filtres/agrégations/fenêtres

'filter' : gammes de dates ('from/to' UTC, timezone aware), pays, marques, jeux, chaînes, devis.
'Group _ by ': mesures.
"metrics' : liste des KPI.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'Currency ':' reporting 'native', stratégie FX : 'eod'intraday 'txn'.
'Sampling ': pour les requêtes heavy (uniquement lorsque c'est permis).

5. 2 Exemple de requête

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 Exemple de réponse

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) Pagination, limites, triage

Pagination : 'limit' (≤10k), 'cursor' (opaque), triage par mesure/date.
Timeout/partial : réponses partielles uniquement pour les indicateurs clés non financiers ; les finances sont soit P200, soit P504.
Limites de taux : global/par clé/par tenant ; la réponse contient « X-RateLimit- ».

7) Idempotence et cache

Idempotent GET/POST-read (avec le corps) avec 'Idempotency-Key'.
Clé cache = hash (paramètres + version du schéma + rôle/tenant/géo).
TTL : KPI-dépendant (par exemple, 'PT15M' pour le revenu, 'PT5M' pour les événements), réinitialisation à un nouveau snapshot.

8) Consistance et monnaie du temps

Drapeau time-travel pour les rapports rétrospectifs (versions de données).
Règles de coupe (fermeture du jour/semaine).
FX : nous enregistrons la stratégie, la date du cours dans la réponse.
Clock : tous les temps sont des ISO-8601, indication TZ obligatoire.

9) Sécurité et vie privée

mTLS/TLS1. 3, Signature HMAC du corps de la demande/réponse (protection MITM/replay).
RBAC/ABAC/ReBAC : rôle + pays + marque + objectif ; masques par défaut.
Pluralité (multi-tenant) : Isolation des schémas/clés/quotas.
Tokénisation des identifiants ; l'interdiction des IPI dans les réponses.
Audit : Invariable Request Logs (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR : filtres sur les attributs marketing ; l'indicateur « subject erased ».

10) RG/AML/Antifrod restrictions

Politiques RG : interdiction d'émettre des indicateurs « agressifs » pour les segments à risque élevé ; les engins sont sûrs.
AML/Antifrod : accès limité aux indicateurs clés sensibles, zonage par rôle ; endpoints séparés pour les enquêtes.
Explainability : dictionnaire d'explications KPI/signaux pour Sappport.

11) Observabilité et API SLO

SLO : p95 latency (par exemple, ≤ 300 ms pour les cash-hits ; ≤ 2 s pour les lourds), success-rate ≥ 99. 5%.
DQ : fraîcheur/exhaustivité/intégrité ; les marques dans la réponse.
Utilisation : QPS, cache hit-rate, clés chaudes, erreurs de validation.
Alerts : dégradation de la fraîcheur, croissance de 4xx/5xx, anomalies selon les KPI (zeros/peaks unexpected).
Tracing : 'trace _ id' de bout en bout jusqu'à DWH/fichestor.

12) Versioning et compatibilité

Voies : '/v1 ', '/v2' ; deprecate avec fenêtre de migration.
Schémas : 'schema _ version' dans la réponse ; MAJOR → dual-read, hydes migratoires.
Version KPI : dans la réponse 'kpi _ definitions' avec un lien dans le catalogue ; interdiction des modifications cachées des formules.

13) Erreurs et statuts

« 400 » validation (métrique/mesure/combinaison de filtres inexistante).
'401/403' authentification/autorisation.
'409' incompatibilité des versions/stratégies.
« 422 » violation de la confidentialité/consentement.
« 429 » quotas.
'5xx'défaillances de la plate-forme (avec trace_id et retry-pool) .

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

14) Intégrations et interfaces

BI : modèles semantic pré-décrits, connecteurs (Looker/Power BI/Tableau) → API comme source.
ML : lightweight endpoints pour les engins fich (point-in-time, sans PII).
Partenaires : clés/quotas limités, filtres géo, rapports uniquement par blocs d'agrégats.
Webhook/Push : notations « snapshot prêt », « SLO/gamme KPI perturbée ».

15) Exemples d'endpoints de ressources

15. 1 Chiffre d'affaires/rendement

'POST/v2/metrics/revenue '→ GGR/NGR, paris/gains, selon les mesures' date, marque, pays, fournisseur, jeu '.

15. 2 Maintien et entonnoir

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

15. 3 Paiements

'POST/v2/metrics/payments '→ dépôts/retraits, chèque moyen, taux de charge.

15. 4 Responsible Gaming

'POST/v2/metrics/rg '→ nombre d'interventions, proportion de risque élevé, temps de réaction moyen.

15. 5 Antifrod

'POST/v2/metrics/antifraud '→ FPR/TPR, cas, pertes évitées.

16) Test et qualité

Tests contractuels : enum/nullable/type, cohérence des monnaies/fuseaux horaires.
Tests DQ : contrôle des gammes, de la monotonie et de l'intégrité.
Régression : comparaison v1/v2 par tolérances.
Charge : profils de pointe (tournois/fournisseurs).
Sécurité : signatures, anti-replay, requêtes fuzzing, Zero-PII dans les logs.

17) La vie privée par défaut

Agrégats avec seuils « minimum N enregistrements » (k-anonymat).
Pas d'identifiants raw ; seulement les tokens/catégories.
DSAR : API pour le déchargement/retrait par jeton via une boucle privilégiée.

18) Indicateurs de succès (API KPI)

Adoption : proportion de rapports/widgets utilisant l'API plutôt que le SQL direct.
Cohérence : divergence entre BI et API ≤ tolérances.
SLO : respect de latency/success/freshness.
Sécurité : zéro cas de PII dans les réponses/logs.
Cost : cache hit-rate, coût de la demande, % des pré-rendeurs.

19) RACI (exemple)

Product/Analytics (A) - définitions de KPI, besoins.
Data Platform (R) - implémentation, cache, SLA, observability.
Domain Owners (R) - sources/contrats.
Sécurité/DPO (A/R) - vie privée, accès, audits.
SRE (R) - quotas, auto-ski, incidents.
Finance (C) est la sémantique financière de GGR/NGR/NET.

20) Feuille de route pour la mise en œuvre

0-30 jours (MVP)

1. Sélectionnez 3-5 KPI (GGR, dépôts, rétention D7).
2. Décrire les contrats et la sémantique KPI ; Inclure DQ/SLA.
3. Implémenter '/v1 'API Query + cache + mTLS/HMAC.
4. Dashboards SLO (latency/success/freshness), audit/trace _ id.

30-90 jours

1. Precompute (Precompute) des vitrines populaires, cache CDN.
2. Versioning '/v2 ', double lecture, hyde de migration.
3. Exporte l'API avec les décharges signées et WORM.
4. Intégration avec BI/ML ; quotas/tenants/géo-isolants.

3-6 mois

1. Taxonomie complète KPI et bibliothèque de widgets.
2. Conseils intelligents/plaque de filtre automatique, linter de requête.
3. Notes de sortie automatiques KPI, contrôle des tolérances v1/v2.
4. Circuit d'affiliation externe avec clés limitées et stratégies RG.

21) Anti-modèles

Changement caché de formule KPI sans nouvelle version et notes de sortie.
Retour PII/matières premières au lieu d'agrégats/tokens.
L'absence de cache/avant-garde est → coûteuse et lente.
Référence rigide à une base de données spécifique (pas d'abstraction de couche).
Les TZ/FX incohérents → des chiffres non comparables.
Il n'y a pas de taux limite/quota → « DDOS à vous ».

22) Modèles (prêts à l'emploi)

22. 1 Stratégie d'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 Checklist de sortie

• Mise à jour de la sémantique KPI et mise à niveau de la version
• Contrat/schéma dans le catalogue ; les tests DQ/régression sont verts
• Clés cache/TTL, prérendeurs configurés
• Documentation et exemples de demandes/réponses
• Alerts par SLO et quotas inclus
• Restrictions RG/AML vérifiées

23) Sections connexes

Pratiques DataOps, Audit et versionalité, Sécurité et cryptage, Contrôle d'accès, Tokenization des données, Politiques de stockage, Origine et chemin des données, MLOps : exploitation des modèles, Éthique des données.

Résultat

L'API analytique et métrique est une couche contractuelle, sûre et rapide d'accès aux données « or » et aux KPI. Il garantit une sémantique unique, des versions stables, la confidentialité par défaut et des performances au niveau du produit - des dashboards internes aux panneaux partenaires et aux ML.