Operações via API

(Seção Operações e Gerenciamento)

1) Atribuição e princípios

A API é uma «camada de operação» do ecossistema: tudo o que não é automatizado através do contrato se transforma em trabalho manual e riscos.

• Contract-first: primeiro a especificação (OpenAPI/JSON Schema/AsyncAPI), depois a implementação.
• Secure-by-default: escopos mínimos, TTL curtos, mutual-TLS/assinaturas.
• Observável: traçado end-to-end e métricas SLA.
• Idempotent: repetição segura.
• Backwards-compatível: evolução sem alterações «quebrantes».
• Auditível: dados criptograficamente confirmados (recibos).

2) Contrato e modelo (árbitro)

OpenAPI para consultas sync; AsyncAPI para eventos/webhooks.
Os campos obrigatórios de cada recurso são «id», «version», «created _ at», «updated _ at», «tenant», «region», «trace _ id».

Exemplo de fragmento de contrato

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Autenticação, permissão, escopos

OAuth2/OIDC para usuários/parceiros; client-credentials/JWT для S2S.
Papéis/recursos: 'payments. write`, `catalog. read`, `audit. export`.
ReBAC: acesso «por domínio» (conta/tenante/conta sáb).
Segredos JIT: tokens de curta duração, alinhamento ao dispositivo/subrede/região.
Device posture & mTLS para transações críticas (pagamentos, chaves).

4) Idempotidade e «Exatamente um dia»

Idempotency-Key (cabeçalho) + deadup por '(key, score, road)' na janela TTL.
Outbox/CDC para publicação de eventos - entrega garantida.
Exactly-once-effects: os efeitos secundários são registrados através de um registro transacional; a repetição leva ao mesmo «recibo» ('receipt _ hash').
Políticas Retry: back-off exponencial, jitter, janelas máximas.

5) Limites, quotas, prioridade

Rate limits: per-key/tenant/route/region; «macios» (429) e «rígidos» (recorte).
Quotas/orçamentos: caps mensais/diários, webhooks 'QuotaCapReached'.
Fair-use: prioridade dos tenentes de serviço (Gold/Silver/Bronze).
Burst-buffers: picos curtos sem degradação dos vizinhos.

6) Paginação, filtros, amostra

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Time-sliced amostra ('from', 'to', 'watermark') para registros/transações.
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency cints: 'snapshot _ at '/' as _ of' para API de reportagem.

7) Versionização e compatibilidade

SemVer: `v1`, `v1. 1 '(extensões),' v2 '- apenas por novos caminhos/neymspace.
Regras de evolução: apenas adição de campos/valores, «deprecate → remove» através da janela.
Compatibility tests: «contratos-como-teste» (consumer-driven).

8) Eventos, webhooks e recibos

AsyncAPI descreve os temas/payload/assinaturas.
Legenda: HMAC/EdDSA, cabeçalho 'X-Mensagem', 'X-Nince', 'X-Timestamp' (janela estreita).
Recibos (receipts): 'receipt _ hash' e assinatura DSSE em eventos críticos (pagamentos, alterações de RTP/limites, folhas de price).
Retraias e dedups: Idempotidade por 'idempotency _ key '/' event _ id'.
DLQ/quarentena: Mensagens de má saúde/repetição com causas.

9) Observabilidade e qualidade

Traces: obrigatórios 'trace _ id/span _ id' através de gateway/eventos de negócios/webhooks.
Metrics: disponibilidade, p50/p95/p99, error-rate, retry-rate, cost per 1k.
Logs: estruturados, sem segredos/PII; marcas de 'tenant/region/version'.
SLO/alertas: Condições de orientação SLO e runas automáticas (pause/re-road/rollback).

10) Erros e semântica de estatais

2xx - Sucesso (202 para operações asincrônicas).
4xx - vinhos do cliente (422 - validação, 409 - conflito/idempotidade, 429 - limites).
5xx - problemas temporários.
O corpo do erro é «código», «mensagem», «trace _ id», «hint», «retry _ after?».
UX para associados: tabela «o que fazer» para cada erro.

11) Políticas-como-código (OPA/ABAC)

Autorização centralizada: «quem/o/o/o/o/o/o/porquê».
Políticas em Git, código, testes CI (pré-flight: "Será que a política resolve? »).
Cheque SoD: «criar um pagamento» ≠ «aprovar».

12) Segurança, privacidade, complacência

Minimização PII: Toquenização/máscaras, acesso ao primário apenas através de jobs aprovados.
Segredos Vault/KMS, TTL curtos, rotativos; a proibição de segredos shared.
Criptografia: mTLS/TLS 1. 3, AES-GCM at-rest, HSTS/PKP onde for apropriado.
Jurisdition-aware: localização de dados/chaves per region.
Registros de auditoria: WORM, Corte de Merkle, assinaturas DSSE.

13) Exploração: SLI/SLO e dashboards

• Disponibilidade per-road/region.
• Latitude p95 (read/write).
• O sucesso dos webhooks (recibos), a linha de entrega.
• Error-rate/Retry-rate.
• Vale por 1k consultas e egress.

SLO (exemplo): 99. 95% de disponibilidade; p95 ≤ 120/250 ms; webhooks ≥ 99. 5 %/5-min; P1 MTTR ≤ 60 min

14) Gerenciamento de alterações (lançamentos/reversões)

Blue-Green/Canary para passeios e rotas críticas.
Ficheflags para comportamento sem lançamento.
Expand→Migrate→Contract para circuitos e payload.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefactos: imagens assinadas/manifestos, registro de versões.

15) SDK, clientes, «barras de areia»

SDK oficial (TS/Java/Python/Go) com a mesma semântica de erros e retais.
Ambientes Sandbox com chaves de teste/certificados e simuladores PSP/KYC/provedores de conteúdo.
Contracto-testes incluídos em SDK CI, nightly-compatibilidade.

16) Modelo de dados (simplificado)

`api_key` `{id, tenant, scopes[], ttl, created_by}`

`rate_plan` `{tenant, quotas{route→cap}, burst, priority}`

`request_log` `{trace_id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}`

`webhook_receipt` `{event_id, endpoint, status, attempts, receipt_hash, signature}`

`policy` `{version, rules, signer, dsse}`

17) RACI

18) Métricas de qualidade

Contract Drift: 0 alterações de quebra sem depredação.
Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, p95 ≤ 60 s.
Auth Fail vs Abuse: proporção de blocos maliciosos, ruído ≤ nível de destino.
Costa/1k: Controle de rotas e regiões (orçamentos/caps-alerts).
SDK Adopção: proporção de tráfego via SDK oficial.

19) Playbooks incidentes

Spike 429/limites: levantar o capá para Gold, trottling «barulhentos» chaves, comunicação com o parceiro.
WebhookLag: Aumentar os browcers/batches, priorizar as filas, desligar temporariamente os webhooks opcionais.
PriceMismatch (catalog/FX/Tax): Confecção de versões, deficiente de força, reversão de artefato, compensação.
PSP Outage: mudança de rota, quarentena de transações cinzentas, réplicas.
Compromise API-key: revisão imediata, rotação, auditoria dos últimos 30 dias.

20) Especificidades do iGaming/fintech

RTP/Limits API: apenas unidades e versões de perfis; alterações - com recibos.
Pagamentos/pagamentos: 202 + webhooks com assinaturas; Idimpotência para a chave de encomenda.
Filiais, conversões de dedução, esquetes de controvérsia, relatórios assinados.
Jogo responsável: Exponha «guardrails API» para os limites e eventos RG.

21) Folha de cheque de implementação

• É descrito o contrato (OpenAPI/AsyncAPI), validação CI e testes de consumo.
• São configurados OAuth2/OIDC, escopos, segredos JIT e mTLS para rotas críticas.
• Foram introduzidas idempotidade, retraí, DLQ e quarentena.
• Limites/quotas/prioridades e alertas por capas.
• Paginação com cursores, amostras consistentes 'as _ of'.
• Versionização e Política de Deprecação.
• Webhooks com assinaturas/recibos, réplicas e deduções.
• Traçado/métricas/logs, SLO e runas.
• Registros WORM, assinaturas DSSE, cortes Merkle.
• SDK, sandbox, simuladores, exemplos de código e «how-to».

22) FAQ

Porquê 202 para operações longas?
Para não manter a conexão e fornecer um retro/recibo confiável através do webhook.

Ambos precisam de OpenAPI e AsyncAPI?
Sim: sync para comandos/solicitações, async para eventos/concordância de estados.

Como evitar alterações de quebra?
Regra «apenas adição», deprecate → outserve → remove, teste de contrato do cliente.

Onde guardar os recibos?
Em uma área WORM com assinaturas; 'receipt _ hash' é devolvido ao cliente e revisto quando solicitado.

Resumo: As transações via API são uma disciplina de contrato e operação: modelo rigoroso de acesso e idempotidade, limites e versões, observabilidade e SLO, assinaturas e recibos. Adicione barras de areia e SDK - e os parceiros se integrarão de forma rápida, segura e previsível, enquanto o negócio será escalado sem perdas de qualidade e complacência.