API unificada para provedores: design, versionagem, compatibilidade

Texto completo do artigo

💡 18+. Material técnico para os comandos de integração e plataforma. Não um apelo para o jogo.

1) Por que «API unificada» e o que é isso

Uma única API é a especificação e conjunto de endpoint/eventos através dos quais qualquer provedor de conteúdo (RGS, Live Studio, Jackpot, KYC/AML, afiliados) se comunica com a plataforma com uma única regra:

um único modelo de recursos (players, sessions, bets, senslents, bonuses, jackpots, payments), contratos de eventos compartilhados e identificadores, padrões de segurança e compatibilidade retroativa, SDK/ferramentas para acelerar as integrações.

O objetivo é reduzir o time-to-integrate, reduzir os erros nas «vias monetárias» e fornecer upgrades previsíveis.

2) Princípios de design

1. Domain-first. Primeiro dicionário e invariantes (aposta, setlment, limites RG), depois endpoint.

2. Compatibility by default. Qualquer alteração é compatível com o padrão; as alterações breaking são rigorosas por processo.

3. Idempotency everywhere. Todos os comandos de dinheiro são repetidos sem efeitos colaterais.

4. Events are fonte of truth (na distribuição). Operações → eventos no pneu; escuta um analista de pneu, não bate um OLTP.

5. Least privilege & zero-trust. Tokens, assinaturas, segmentação por marca/região.

6. Observability. «Trace _ id», modelo de erro compreensível, métricas p95/p99.

3) Modelo de recursos (simplificado)

Player: pseudo-ID do jogador do lado da plataforma, geo/moeda/estatais RG.

Sessão: canal entre o provedor e a plataforma ('sessions _ id', TTL, geo/restrição).

Bet: permissão/débito da aposta.

Senslement: resultado da rodada e crédito do ganho.

Bónus/Wager: estado do bónus/saldo do vager.

Jackpot: contribuições/triggers/pagamentos.

Event: eventos de domínio imutáveis (Kafka/similares).

Identificadores: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'sessions _ id', 'round _ id', 'bet _ id', 'senslement _ id'. Todos são de linha, globalmente exclusivos (UUID/KSUID/Snowflake), incluídos nos logs e eventos.

4) Contratos API: pedidos, respostas, erros

4. 1 Autorização e segurança

OAUTh2 Clientes Credentals ou mTLS + assinatura do corpo da solicitação (HMAC/EdDSA).

Скоупы вида: `bets:write`, `settlements:write`, `sessions:read`, `events:publish`.

Cada solicitação tem títulos obrigatórios:

`X-Trace-Id`, `X-Brand-Id`, `X-Region`, `X-Idempotency-Key`.

4. 2 Exemplos de endpoint

Criar sessão


POST /v1/sessions
{
"player_id":"p_19f3",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE",  "constraints":{"max_bet":5,"rg_flags":["self_exclusion":false]}
}
→ 201
{
"session_id":"s_456",  "expires_at":"2025-10-23T19:10:00Z"
}

Autorização de aposta (hold)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 { "status":"authorized","hold_id":"h_zz1" }

Setlment


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14. 60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 { "status":"credited","settlement_id":"st_77" }

4. 3 Erros (modelo único)

`code`: машинное имя (`RG_BLOCK`, `LIMIT_EXCEEDED`, `DUPLICATE`, `IDEMPOTENCY_MISMATCH`, `INVALID_STATE`, `AUTH_FAILED`).

Mensagem: resumida para uma pessoa.

`retryable`: `true/false`.

'trace _ id': para pesquisar nos logs.

Exemplo:


409 CONFLICT
{
"code":"DUPLICATE",  "message":"Bet already authorized with a different amount",  "retryable":false,  "trace_id":"tr_a1b2c3"
}

5) Pneu de evento e circuitos

5. 1 Topics básicos

`player. registered`, `session. started	ended`
`bet. authorized	settled
`bonus. issued	consumed
`wager. progress. updated`
`jackpot. contribution	triggered
`rg. limit. hit`, `rg. reality_check`
`wallet. debit.`, `wallet. credit.`

5. 2 Esquema de evento (Avro/JSON Schema)

json
{
"event_id":"uuid",  "event_type":"bet. settled",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",  "trace_id":"tr_a1b2c3",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1. 00,"currency":"EUR"},   "win":{"amount":14. 60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1",  "schema_version":"1. 2. 0"
}

Regras: backward-compatível evolução dos circuitos, registry + testes contratuais.

6) Versionário API: estratégias e regras

6. 1 Onde armazenar versão

Versão Path: '/v1/... '(apenas cajar/roteirizar).

Versão Header: 'Accept: aplicação/vnd. platform. api+json; version=1. 2`.

Eventos: 'schema _ version' na caixa de evento + registry.

Prática: path para HTTP, schema _ versão para eventos, fichflagra para recursos pontuais.

6. 2 SemVer e tipos de alterações

PATCH (menor) - Novos campos opcionais, novos endpoints, novos tipos de eventos.

MAJOR - breaking: renomear campos, alterar semântica, remover. Só são permitidos através de um novo '/ vN/' e depredação do antigo.

6. 3 Contratos estáveis (o que não pode ser quebrado)

Nomes e tipos de campos-chave de identificação ('_ id', 'idempotency _ key').

Modelo monetário ('amount/currency', precisão).

Semântica de estatais ('autorized', 'credited', 'perfeited', etc.).

Idempotidade: Comportamento repetido rigorosamente definido.

7) Compatibilidade e evolução

7. 1 Adições (safe)

Novos campos opcionais com default.

Novos eventos/endpoints sem alterar os existentes.

Extensão enum com fallback em 'unknown'.

7. 2 Alterações (risky)

Alterar o tipo de campo (número → linha).

Alteração da obrigatoriedade (optional → required).

Página espelhada da lógica de negócios ('setle' antes 'autorize').

Precisa de uma nova versão maior e de um hyde migratório.

7. 3 Despreceção

O campo/endpoint é marcado por 'deprecated _ since: 1. 7`, `removed_in: 2. 0`.

Comunicação: release de notas, correio, deprecation-headers ('Sunset', 'Deprecation').

Traça o uso de caminhos «obsoletos» para notificações proativas de parceiros.

8) Idempotidade e coerência

O título 'X-Idempotency-Key' é obrigatório para todas as gravações.

Semântica: repetição com a mesma chave → o mesmo resultado (200 com o anterior body).

As chaves estão ligadas a uma composição de parâmetros (por exemplo, 'bet _ id + amount').

Sagas em processos longos: 'athorize' commit/lock 'setle credit'; compensações por eventos 'rollback'.

9) Paginação, filtros, triagem

Paginação cursor-based (rigorosamente preferível 'page/limit' para grandes fluxos).

Unificação: '? cursor =... & limit = 200 & order = asc'.

Na resposta, 'next _ cursor', 'has _ more'.

Filtros: hora ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Locais, moedas, residência de dados

Moeda em ISO-4217; a precisão é armazenada no padrão ('scale') e os cálculos são em menores-units (cents).

Local - BCP 47 ('en-GB', 'pt-BR').

Cada pedido é 'region'; PII e transações não atravessam regiões.

Camuflagem PII e RLS nas vitrines BI.

11) Observabilidade e limites

Títulos obrigatórios: 'X-Trace-Id', 'X-Provider-Id', correlação com eventos.

Métricas: p50/p95/p99 latency, error rate (por código), throughput, queue lag (por evento).

Rate limits: per provider / per brand; respostas com 'Retry-After'.

A auditoria WORM de alterações críticas (limites, pulos RTP, fórmulas de jackpot).

12) Testes e qualidade dos contratos

Testes contratuais (Pact/outros): provedor ↔ plataforma ↔ consoantes de eventos.

Carga: «tempestade» de apostas/setlems; alvos p95.

Mala de caos, filmagem, out-of-order, atrasos na carteira.

Caixa de areia '/sandbox 'com dinheiro falso e' player _ id 'de teste.

13) SDK, geradores e documentação

OpenAPI/AsyncAPI → SDK (TypeScript/Java/Kotlin/Go/Rust).

Exemplos de código para 'autorize/setle/rollback', retrações e processamento de erros.

Live-doc com exemplos de consulta/resposta (curl + JSON), coleção Postman/Insomnia.

Changelog com tipos de alterações e marcas de compatibilidade.

14) Mapa de trânsito das migrações (exemplo)

1. v1. 6 → v1. 7 (menor): Adicionaram o campo 'bonus _ state' a 'setle' (optional).

2. v1. x EOL anúncio: em 6 meses - carta + 'Deprecation' header + dashboard de uso.

3. v2. 0 (major): individual 'wallet. commit '(antes impliciit), o novo campo' masslement _ id 'é obrigatório.

4. Hide migratório: mapping de campos, timeline, fichflag «duplo» (publicação paralela de «v1 »/« v2» eventos).

5. Sunset v1: bloqueio de novas integrações, extensão apenas com exceções SLA.

15) Folhas de cheque

Para arquitetos de plataforma

Há um único dicionário de entidades de domínio e invariantes.
OpenAPI/AsyncAPI + Schema Registry, semver, processo de depredação.
Idempotidade em todas as operações write; as chaves estão documentadas.
Um único erro de modelo e códigos.
Sagas e outbox/CDC em dinheiro.
Rate-limits, observabilidade, auditoria WORM.
Caixa de areia e testes contratuais estão disponíveis para os parceiros.
Data residency e RLS/disfarce.

Para o provedor

Envio 'X-Trace-Id' e 'X-Idempotency-Key' sempre.
As repetições de solicitação processam com segurança; Não crio dublês.
Processando 'Deprecation/Sunset' e lendo Changelog.
Publico/leio eventos sobre esquemas registry; guardo a versão.
Tenho retry/backoff e dedução do meu lado.

16) Anti-pattern (bandeiras vermelhas)

Edição manual de balanços/setlems na base de dados.

Publicar eventos «passando» outbox/CDC.

Falta de idempotency → duplicações de pagamentos/débitos.

Mistura PII/dinheiro de diferentes regiões sem marcação 'region'.

Mudanças «silenciosas» breaking sem nova versão e depredação.

Geração de SDK manual (à deriva do spack real).

Migração Big bang sem fichflags e duplo e-mail eventos.

Uma única API não é apenas uma «coleção de endpoint», mas um contrato de ecossistema: dicionário alinhado, invariantes monetários estáveis, eventos de versionagem, regras de compatibilidade compreensíveis e depredações controladas. Baseada em versões semânticas, idempotidade, outbox/CDC, observabilidade e segurança rigorosa, a plataforma conecta os provedores rapidamente e indolor, e os upgrades são transformados de risco para rotina.