API ecossistema

(Secção: Ecossistema e Rede)

1) Objetivos e princípios

• Integrações rápidas e previsíveis (time-to-integration ↓).
• Confiabilidade e escalabilidade (SLO, QoS, backpressure).
• Segurança e regulação (direitos mínimos, auditoria).
• Evolução sem falhas (versões, compatibilidade, fichiflags).

Princípios: contracto-first, minimização de dados, idempotidade, observabilidade-by-default, duas velocidades de lançamento (core vs experimental).

2) Taxonomia API

1. REST/HTTP - CRUD sincronizado/operações de comando, idempotency-key, pagination/cursors.
2. gRPC/QUIC - baixa latência, striam, protocolos binários.
3. Events (Pub/Sub) - Eventos de domínio ('deposit', 'payout', 'bridge', 'risk.').
4. Webhooks - notificações reversas com assinaturas e retraias.
5. GraphQL (restrito) - leituras agregadoras acima das vitrines materializadas.
6. Admin/Meta - diretórios, versões, estatais, chaves, quotas.

Níveis de acesso: Público (métodos limitados/leitura), Parceiro (caixas e cotas), Internal (contornos privados).

3) Contratos e esquemas

OpenAPI/AsyncAPI/Protobuf IDL é uma única fonte de verdade.
Data Contracts - Testes de compatibilidade, linteres de esquema, proibição de campos de quebra sem MAJOR.
Diretórios: ativos/redes, PSP/métodos, regiões/jurisdição, versões SDK, bandeiras de recursos.

Contrato REST mínimo (fatia OpenAPI)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

Eventos (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

4) Versionização e compatibilidade

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - Retroativo-compatível; MAJOR - versões paralelas ('/v1 ', '/v2') + adaptadores.
Deprecation policy: janela ≥ 90 dias, duas linhas de suporte, notificações automáticas contratuais.
Função Flags: ativar/desativar campos/métodos por região/parceiro.
Capability Negotion: anúncio de perfis suportados no aperto de mão.

5) Idempotidade, ordem e cursores

Idempotency-Key para comandos (create/cancel), TTL chaves ≥ 72 h.
Exactly-once semântica via outbox/inbox e consoante idumpotente.
A paginação por cursores é 'next _ cursor', resistente a inserções/remoções.
Triagens e filtros são estáveis, claramente documentados.

6) Segurança e confiança

mTLS (service↔service), pinning de sertões e rotação de chaves.
OAUTh2/OIDC (cliente credentals, JWT com TTL curto), PoP/DPoP para alinhamento ao canal.
Assinaturas Webhook (NMAS/versão da chave/hora), proteção contra repetições.
RBAC/ABAC e PoLP: escopos, org _ id/tenant _ id, limites para objeto/operação.
DLP/PII-Minimização: proibição de PII em editoras/logs, torneamento de identificadores.
Rate-limits e WAF: per org/rota/region, proteção contra abuse.

Exemplo de política de chaves (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) Quotas, QoS e backpressure

Classes QoS: P0 (pagamentos/ponte/finalização), P1 (alimentos), P2 (bulk/arquivo).
Quotas/limites: RPS, concur-requests, bytes/sec, tema/partição para eventos.
Admision controle: desviação precoce de pedidos «caros», heavy-query-guard.
Backpressure: tokens/créditos, filas com DLQ, retrai com jitter.

Política de quotas

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) Observabilidade: SLI/SLO, métricas, traçáveis

• p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Contracto Compliance% (esquemas/assinaturas).
• Webhook retry/dropped%.

SLO (referências): P0 p95 ≤ 400 ms, Availability ≥ 99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

Métricas: histogramas de latência, códigos de erro, tamanho de respostas, RPS, per-tênant.
Trailers: «trace _ id» (edge→gateway→service→DB→event/webhook).
Logi: Estruturado, sem PII, correlação por 'request _ id'.

9) Pattern lançamentos sem downthame

Blue-Green/Canary com gates SLO e outlyer-ejation.
Schema-first evolução: apenas adição de campos, adaptadores para clientes antigos.
Migração de BB zero-downtime: DDL online, conversores bidirecionais.
Controle de alterações: timelock, auditoria e registro de compatibilidade.

10) Diretórios e registros

Registro de API/versão

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

Diretório de eventos

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

Chaves/escopos

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) Testes e conformidade com os contratos

Contracto-testes: geração de clientes, validação de circuitos, negativa- _ cases.
Testes de evento replay: resistência a repetições/reordenamento.
Chaos/Lat-testes: injeções de perdas/jitter, estor lento.
Testes de segurança, assinaturas de webhooks, rotação de chaves, ataques de repetição.
Perfis de performance: spacks SLA, rotas «quentes», DA/ponte de dependência.

12) Exemplos de interface

Webhooks (assinatura e retraí)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL (leitura agregadora, somente leitura)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (fluxo de eventos)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) Processos e papéis

API Owner - contrato/versão/SLO/quotas.
Segurança - chaves/assinaturas/auditoria/DLP.
SRE/Ops - dashboards, alertas, capacity.
Parceiro Sucess - Forró, limites, fichiflags.
Compliance - jurisdição, sanções, relatórios.

14) Dashboards

Core API: latency/erro/RPS sobre rotas e dentantes.
Webhooks: delivery p95, retries, drops, assinaturas.
Events: freshness, lag, consumer health, DLQ.
Segurança: chaves de vencimento, assinaturas, pedidos negados.
Governance: versões ativas/deprekates, compatibilidade de contratos.

15) Playbook incidentes

A. Aumento p95 latência P0

1. Incluir prioridade P0 e P2-throttle; 2) Dimensionar as passarelas;

2. mudar parte das leituras para o dinheiro; 4) Análise de rotas quentes.

B. Queda delivery webhook

1. Verificar assinaturas/deslocamento horário, 2) aumentar retais/temporizações,

2. ligar batchi, 4) passar temporariamente para o pool-endpoint.

Contratos C. Drift

1. Ativar o modo «strict» (cortar mensagens incorretas),

2. notificar o produtor, 3) lançar o adaptador, 4) pós-mortem, atualizar as lentes.

D. Comprometer chave/sertão

1. Revoke/rotate, 2) remanejar webhooks, 3) auditoria, 4) notificar os parceiros.

E. Explosão de repetições/duplicação

1. Verificar Idempotency-Key/TTL, 2) reforçar o Dedup, 3) limitar a fonte «ruidosa».

16) Folha de cheque de implementação

1. Descrever contratos (OpenAPI/AsyncAPI/IDL), incluir lentes e CI.
2. Personalizar auth (OAuth2/OIDC, mTLS), assinaturas de webhooks, rotação de chaves.
3. Introduza quotas/QoS/limites, heavy-query-guard e backpressure.
4. Elevar observabilidade: SLI/SLO, pistas, dashboards, alertas.
5. Organizar lançamentos canary/blue-green, schema-first migração.
6. Iniciar diretório de versões/eventos/chaves e processos de decolagem.
7. Fazer chás/perf/testes de segurança, fazer playbooks.
8. Revalidar regularmente a minimização de dados e adequação à regulação.

17) Glossário

Contract-first - Projetando API através de contratos formais antes do código.
O Idempotency-Key é uma chave que torna a operação em segurança.
AsyncAPI - especificação de interfaces de eventos.
QoS - classe de qualidade/prioridade de serviço.
DLQ - «fila morta» para mensagens problemáticas.
Error budget burn - velocidade de «queima» do orçamento de erros em relação ao SLO.

Resultado: a API do ecossistema não é um conjunto de endpoint, mas sim um sistema gerido de contratos, segurança, quotas e observabilidade. Seguindo este quadro, o ecossistema recebe uma rápida integração, um SLO previsível e uma evolução segura sem downthame, desde o nível de rede e autenticação até os fluxos de eventos e relatórios.