API analistas e métricas

1) Por que uma camada de API separada

Uma verdade para o KPI, excluímos o «zoológico SQL».
Velocidade do produto: frentes, painéis de parceria, clientes móveis recebem unidades sem acesso direto ao DWH.
Segurança e complicação: toquenização, máscaras, limitações geo, filtros RG/AML.
Escala: dinheiro, prensadores, CDN, contratos estáveis.

2) Taxonomia: métricas, medidas, factos

Factos: apostas, ganhos, depósitos, eventos KYC, intervenções RG.
Medições: data/hora (calendários), jogo/provedor, marca/país, canal/device, jogador (token).
Métricas: GGR, NGR/NET, ARPPU, retenção D1/D7/D30, taxa de depósito, FPR antifrode, risco RG.
Unidades: moeda (FX), tempo (TZ), volume/contadores (idempotent!).
Semântica KPI: Definições em contratos BI, versões KPI são captadas.

3) Contratos API (Data & BI Contracts)

Schema: campos, tipos, nullable, enum, unidades, moedas.
Semântica de métricas: fórmula, fontes, janelas de agregação, filtros.
Compatibilidade (SEMVER): MAJOR quebra, MENOR adiciona campos, PATCH capta.
DQ/SLA: Frescura, abrangência, consistência, permissões.
Privacidade: 'pii: falso', 'tocenized: true', proibição de detonação.

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

Query API (agregações online acima de «gold «/cubos/fitchestor).
Precompute API (prensadores de horário, materializações views).
API Events (contadores de streaming/sinais).
Export API (downloads assinados, WORM para auditoria).
Dinheiro: em camadas (in-memory → Redis → CDN), chave = hash de consulta + versão.
Coerência: read-your-writes para os registros finais, SLA frescura para as unidades.

5) Interface e consultas

5. 1 Filtros/agregações/janelas

'filter': faixas de datas ('from/to' UTC, timezone aware), países, marcas, jogos, canais, slides.
'group _ by': medidas.
'metrics': lista KPI.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency': 'reporting' native ', estratégia FX:' eod 'intraday' txn '.
'sampling': para solicitações heavy (somente onde for permitido).

5. 2 Exemplo 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 Exemplo de resposta

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) Paginação, limites, ordenação

Paginação: 'limit' (≤10k), 'cursor' (opaque), ordenação por medida/data.
Timeout/partial: Respostas parciais apenas para KPI não financeiros; finanças - ou P200 ou P504.
Rate limits: global/por chave/por tenante; a resposta contém «X-RateLimit -».

7) Idempotidade e dinheiro

Idempotentes GET/POST-read com 'Idempotency-Key'.
Chave de dinheiro = hash (parâmetros + versão de esquema + rol/tenante/geo).
TTL: Dependente KPI (por exemplo, 'PT15M' para revenue, 'PT5M' para eventos), reiniciado com o novo snapshot.

8) Consistência e moeda do tempo

Time-travel bandeira para relatórios retrospectivos (versões de dados).
Cut-off regras (encerramento dia/semana).
FX: Registramos a estratégia, a data do curso na resposta.
Clock: Todos os times são ISO-8601, a indicação TZ é obrigatória.

9) Segurança e privacidade

mTLS/TLS1. 3, HMAC-assinatura corpo de pedido/resposta (proteção contra MITM/replay).
RBAC/ABAC/ReBAC: papel + país + marca + objetivo; máscaras padrão.
Multiplicidade (multi-tenant): isolamento de esquemas/chaves/quotas.
Torneamento de identificadores; a proibição do PII nas respostas.
Auditoria: logs de consulta inalterados (WORM), 'trace _ id '/' ator '/' purpose'.
Consent/DSAR: filtros para atributos de marketing; a bandeira «subject erased».

10) RG/AML/Restrições antifrod

Políticas RG: proibição da emissão de indicadores «agressivos» para os segmentos high-risk; As máquinas são seguras.
AML/Antifrod: acesso limitado a KPI sensíveis, zoneamento por papéis; endpoints separados para investigações.
Expainability: dicionário de explicação KPI/sinais de safort.

11) Observabilidade e API SLO

SLO: p95 latency (por exemplo, ≤ 300 ms para hits em dinheiro; ≤ 2 s para hits pesados), sucess-rate ≥ 99. 5%.
DQ: frescura/integralidade/integridade; as marcas estão na resposta.
Usage: QPS, hit-rate, chaves quentes, erros de validação.
Alerts: degradação do frescor, crescimento de 4xx/5xx, anomalias por KPI (unexpected zeros/peaks).
Tracing: 'trace _ id' passa para DWH/fichador.

12) Versionização e compatibilidade

Caminhos: '/v1 ', '/v2'; deprekate com janela de migração.
Esquemas: 'schema _ versão' na resposta; MAJOR → dual-read, guindastes migratórios.
Versões KPI: na resposta 'kpi _ definições' com referência no diretório; impedir alterações ocultas de fórmulas.

13) Erros e estatais

'400' validação (métrica/medição/combinação de filtros inexistente).
'401/403' autenticação/autorização.
'409' incompatibilidade de versões/políticas.
'422' violação de privacidade/consent.
«429» quotas.
'5xx' falhas de plataforma (com trace _ id e retry- ) .

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

14) Integração e interface

BI: modelos semantic, conectores pré-descritos (Looker/Power BI/Tableau) → API como origem.
ML: lightweight endpoints para unidades de ficção (point-in-time, sem PII).
Associados: chaves/quotas limitadas, geo-filtros, relatórios apenas em blocos agregados.
Webhook/Push: Notificações de «snapshot pronto», «violado SLO/faixa KPI».

15) Exemplos de endpoint de recursos

15. 1 Receita/rendimento

'POST/v2/metrics/revenue' → GGR/NGR, apostas/ganhos, medição 'data, land, country, provider, game'.

15. 2 Retenção e vórtices

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

15. 3 Pagamentos

'POST/v2/metrics/payments' → depósitos/conclusões, cheque médio, chargeback rate.

15. 4 Responsible Gaming

'POST/v2/metrics/rg' → número de intervenções, proporção de high-risk, tempo médio de reação.

15. 5 Antifrode

'POST/v2/metrics/antifraud' → FPR/TPR, malas, perdas evitadas.

16) Testes e qualidade

Testes contratuais: enum/nullable/tipo, coerência de divisas/fusos horários.
Testes DQ, controle de faixa, monotonia e integridade.
Regress: comparação v1/v2 em multidões.
Cargas: perfis de pico (torneios/provedores).
Segurança: assinaturas, anti-replay, consultas de fuzzing, zero-PII nos logs.

17) Privacidade padrão

Aparelhos com liminares «mínimo N registros» (k-anonimato).
Sem identificadores raw; apenas os tokens/categorias.
DSAR: API para carregar/remover por token através de um caminho privilegiado.

18) Métricas de sucesso (KPI API)

Adition: proporção de relatórios/widgets usando API em vez de SQL direto.
Consistency: divergência entre BI e API ≤ permissões.
SLO: cumprimento de latency/sucess/freshness.
Segurança: nulos casos de PII em respostas/logs.
Costa: hit-rate de armazenamento, custo de solicitação,% de preenders.

19) RASI (exemplo)

Produt/Analytics (A) - Definições do KPI, necessidades.
Data Platford (R) - Implementação, dinheiro, SLA, observabilidade.
Domain Owners (R) - fontes/contratos.
Segurança/DPO (A/R) - privacidade, acessibilidade, auditorias.
SRE (R) - quotas, scale automático, incidentes.
Finance (C) - semântica financeira GGR/NGR/NET.

20) Mapa de trânsito de implementação

0-30 dias (MVP)

1. Escolha 3-5 KPI (GGR, depósitos, retenção D7).
2. Descrever contratos e semântica KPI; incluir DQ/SLA.
3. Implementar '/v1 'Query API + dinheiro + mTLS/HMAC.
4. Dashboards SLO (latency/sucess/freshness), auditoria/trace _ id.

30 a 90 dias

1. Prenders (Precompute) vitrines populares, CDN cash.
2. Versioning '/v2 ', dual-read, hide migratório.
3. Exportar API com downloads assinados e WORM.
4. Integração com BI/ML; quotas/tenantes/geo-isolantes.

3-6 meses

1. Taxonomia completa KPI e biblioteca de widgets.
2. Dicas inteligentes/formatação automática de filtros, linter de consultas.
3. Release automático Notas KPI, controle de tolerance v1/v2.
4. Circuito externo de parcerias com chaves limitadas e políticas RG.

21) Anti-pattern

Mudança oculta de fórmula KPI sem nova versão e notas de lançamento.
Restituição do PII/matéria-prima em vez das unidades/tokens.
A falta de dinheiro/prenders → cara e lenta.
Referência rígida a uma base de dados específica (sem abstração de camada).
TZ/FX incoerentes → números não comparáveis.
Não há rate limits/quotas «DDOS seus».

22) Modelos (pronto para uso)

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

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

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 Folha de cheque de lançamento

• Semântica KPI atualizada e versão elevada
• Contrato/esquema no diretório; testes DQ/regressos verdes
• Chaves em dinheiro/TTL, prensadores configurados
• Documentação e exemplos de solicitação/resposta
• Alertas SLO e quotas incluídas
• As restrições RG/AML foram verificadas

23) Seções relacionadas

As Práticas de Ops, Auditoria e Versões, Segurança e Criptografia, Controle de acesso, Tocenização de dados, Políticas de armazenamento, Origem e Caminho de Dados, MLOps: Operação de modelos, Ética de dados.

Resultado

API analistas e métricas é uma camada contábil, segura e rápida de acesso a dados «dourados» e KPI. Ele garante semântica unificada, versões estáveis, privacidade padrão e desempenho no nível do produto - desde dashboards internos até painéis associados e ML.