API del ecosistema

(Sección: Ecosistema y Red)

1) Objetivos y principios

• Integraciones rápidas y predecibles (time-to-integration ↓).
• Fiabilidad y escalabilidad (SLO, QoS, backpressure).
• Seguridad y cumplimiento de la normativa (derechos mínimos, auditoría).
• Evolución sin averías (versiones, compatibilidad, fichflags).

Principios: contract-first, minimización de datos, idempotencia, observabilidad-by-default, «dos velocidades» de lanzamientos (core vs experimental).

2) Taxonomía API

1. NAT/HTTP - operaciones de CRUD/comandos sincrónicos, idempotency-key, pagination/cursors.
2. gRPC/QUIC - baja latencia, streams, protocolos binarios.
3. Eventos (Pub/Sub) - Eventos de dominio ('deposit.', 'payout.', 'bridge.', 'risk.').
4. Webhooks - notificaciones inversas con firmas y retratos.
5. GraphQL (restringido) - lecturas agregadas sobre escaparates materializados.
6. Admin/Meta - directorios, versiones, estados, claves, cuotas.

Niveles de acceso: Public (métodos restringidos/lectura), Partner (coups y cuotas), Internal (circuitos privados).

3) Contratos y esquemas

OpenAPI/AsyncAPI/Protobuf IDL es una única fuente de verdad.
Contratos de datos: pruebas de compatibilidad, linternas de circuitos, prohibición de campos «rompedores» sin MAJOR.
Directorios: activos/redes, PSP/métodos, regiones/jurisdicciones, versiones SDK, banderas de capacidades.

Contrato APROT mínimo (fragmento 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) Versificación e interoperabilidad

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH: compatible con back-end; MAJOR - versiones paralelas ('/v1 ', '/v2') + adaptadores.
Política de depreciación: ventana ≥ 90 días, «dos líneas» de soporte, notificaciones automáticas de contratos.
Flags de características: habilitar/deshabilitar campos/métodos por región/socio.
Capability Negotiation: anuncia perfiles compatibles al apretar la mano.

5) Idempotencia, órdenes y cursores

Idempotency-Key para comandos (create/cancel), llaves TTL ≥ 72 h.
Exactly-once semántica a través de outbox/inbox y consumer idempotente.
Paginación con cursores: 'next _ cursor', resistencia a inserciones/borrados.
Ordenaciones y filtros: estables, claramente documentados.

6) Seguridad y confianza

mTLS (service↔service), pinning sert y rotación de llaves.
OAuth2/OIDC (clientes credentials, JWT con TTL breve), PoP/DPoP para enlazar al canal.
Firmas Webhook (NMAS/versión clave/tiempo), protección contra repeticiones.
RBAC/ABAC y PoLP: scoops, org_id/tenant_id, límites por objeto/operación.
DLP/PII-minimización: prohibición de PII en etiquetas/logs, tokenización de identificadores.
Rate-limits y WAF: per org/route/region, protección contra abuse.

Ejemplo de política de claves (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) Cuotas, QoS y retroceso

Clases de QoS: P0 (pagos/puente/finalización), P1 (productos), P2 (bulk/archivo).
Cuotas/límites: RPS, concur-requests, bytes/sec, tema/lote para eventos.
Control de Admision: rechazo temprano de solicitudes «caras», heavy-query-guard.
Backpressure: tokens/créditos, colas con DLQ, retiros con jitter.

Política de cuotas

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

8) Observabilidad: SLI/SLO, métricas, trazas

• p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Cumplimiento de contrato% (diagramas/firmas).
• Webhook retry/dropped%.

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

Métricas: histogramas de latencia, códigos de error, tamaño de respuesta, RPS, per-tenant.
Tracks: end-to-end 'trace _ id' (edge→gateway→service→DB→event/webhook).
Logs: estructurado, sin PII, correlación por 'request _ id'.

9) Patrones de lanzamientos sin downtime

Blue-Green/Canary con SLO-gates y outlier-ejection.
Evolución de Schema-first: sólo la adición de campos, adaptadores para clientes antiguos.
Migración BD Zero-downtime: DDL en línea, convertidores bidireccionales.
Control de cambios: timelock, auditoría y registro de compatibilidad.

10) Catálogos y registros

Registro de API/versiones

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

Directorio de eventos

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

Llaves/Scoops

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

11) Pruebas y cumplimiento de contratos

Contract-tests: generación de clientes, validación de circuitos, negative-_cases.
Pruebas de respuesta de eventos: resistencia a la repetición/reordenación.
Chaos/Lat-tests: inyecciones de pérdida/jitter, slot lento.
Pruebas de seguridad: firmas de webhooks, rotación de claves, ataques de repetición.
Performance-perfiles: spikes SLA, rutas «calientes», DA/puente de la dependencia.

12) Ejemplos de interfaces

Webhooks (firma y retrabajo)

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 (lectura agregada, sólo lectura)

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

gRPC (flujo de eventos)

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

13) Procesos y roles

API Owner - contrato/versión/SLO/cuotas.
Seguridad: claves/firmas/auditoría/DLP.
SRE/Ops - dashboards, alertas, capacity.
Partner Success - onboarding, límites, fichflags.
Compliance - jurisdicciones, sanciones, informes.

14) Dashboards

Core API: latency/error/RPS a través de rutas y tentantes.
Webhooks: delivery p95, retries, drops, firmas.
Events: freshness, lag, consumer health, DLQ.
Seguridad: claves de caducidad, firmas, solicitudes denegadas.
Governance: versiones/deprechates activos, compatibilidad de contratos.

15) Incidentes de Playbook

A. Crecimiento de la latencia P95 P0

1. Habilitar la prioridad P0 y P2-throttle; 2) escalar las puertas de enlace;

2. Cambiar parte de las lecturas a caché; 4) análisis de rutas «calientes».

B. Caída de delivery webhook

1. Compruebe el cambio de firma/hora, 2) aumente el retroceso/temporización,

2. activar batchy, 4) cambiar temporalmente a pull endpoint.

C. Contratos de drift

1. Incluir «modo strict» (cortar mensajes incorrectos),

2. notificar al productor, 3) lanzar el adaptador, 4) post-mortem, actualizar los linters.

D. Compromiso de clave/sert

1. Revoke/rotate, 2) reescribir webhooks, 3) auditoría, 4) notificar a los socios.

E. Explosión de repeticiones/tomas

1. Comprobar Idempotency-Key/TTL, 2) reforzar el dedoup, 3) limitar la fuente «ruidosa».

16) Lista de verificación de implementación

1. Describir los contratos (OpenAPI/AsyncAPI/IDL), incluir los linters y CI.
2. Configurar auth (OAuth2/OIDC, mTLS), firmas de webhooks, rotación de claves.
3. Introduzca cuotas/QoS/límites, heavy-query-guard y backpressure.
4. Elevar la observación: SLI/SLO, pistas, dashboards, alertas.
5. Organizar lanzamientos: canary/blue-green, schema-first migración.
6. Ejecute el directorio de versiones/eventos/claves y los procesos de deprechates.
7. Realizar cheos/perf/pruebas de seguridad, hacer playbooks.
8. Revisar periódicamente la minimización de los datos y el cumplimiento de la normativa.

17) Glosario

Contract-first - Diseño de API a través de contratos formales antes del código.
Idempotency-Key es la clave que hace que la repetición de la operación sea segura.
AsyncAPI - Especificación de interfaces de eventos.
QoS - clase de calidad/prioridad de servicio.
DLQ es una «cola muerta» para mensajes problemáticos.
Error budget burn - tasa de «quema» del presupuesto de errores con respecto a SLO.

En pocas palabras: la API del ecosistema no es un conjunto de endpoints, sino un sistema gestionado de contratos, seguridad, cuotas y observabilidad. Siguiendo este marco, el ecosistema obtiene integraciones rápidas, SLO predecibles y una evolución segura sin downtime, desde el nivel de red y la autenticación hasta los flujos de eventos y los informes.