Operaciones a través de la API

(Sección: Operaciones y Gestión)

1) Nombramiento y principios

La API es la «capa operativa» del ecosistema: todo lo que no se automatiza a través del contrato se transforma en trabajo manual y riesgos.

• Contrato-primero: primero la especificación (OpenAPI/JSON Schema/AsyncAPI), luego la implementación.
• Secure-by-default: escopetas mínimas, TTL cortos, mutual-TLS/firmas.
• Observable: end-to-end seguimiento y métricas SLA.
• Idempotent: la repetición es segura.
• Backwards-compatible: evolución sin cambios «rompedores».
• Auditable: hechos confirmados criptográficamente (recibos).

2) Contrato y modelos (referencia)

OpenAPI para consultas sync; AsyncAPI para eventos/webhooks.
Campos obligatorios en cada recurso: 'id', 'version', 'created _ at', 'updated _ at', 'tenant', 'region', 'trace _ id'.

el Ejemplo del fragmento del 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) Autenticación, autorización, escopetas

OAuth2/OIDC para usuarios/socios; client-credentials/JWT для S2S.
Roles Scoups/Resource: 'payments. write`, `catalog. read`, `audit. export`.
ReBAC: Acceso «por posesión» (tenant/cuenta/cuenta/cuenta-sub).
Secretos JIT: tokens de vida corta, enlace al dispositivo/subred/región.
Device posture & mTLS para operaciones críticas (pagos, claves).

4) Idempotencia y «exactamente un día»

Idempotency-Key (título) + dedoup por '(clave, cuenta, ruta)' en la ventana TTL.
Outbox/CDC para publicación de eventos - Entrega garantizada.
Exactly-once-effects: los efectos secundarios se registran a través del registro transaccional; la repetición resulta en el mismo «recibo» ('receipt _ hash').
Políticas Retry: back-off exponencial, jitter, ventanas máximas.

5) Límites, cuotas, prioridad

Rate limits: per-key/tenant/route/region; «blandos» (429) y «duros» (corte).
Cuotas/presupuestos: capas mensuales/diarias, webhooks 'QuotaCapReached'.
Uso justo: prioridad de tenantes por nivel de servicio (Oro/Plata/Bronce).
Buffers Burst: ráfagas cortas sin degradación de los vecinos.

6) Paginación, filtros, muestras

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Muestras de tiempo cortadas ('de', 'a', 'watermark') para registros/transacciones.
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency hints: 'snapshot _ at '/' as _ of' para las API de reportaje.

7) Versificación e interoperabilidad

SemVer: `v1`, `v1. 1 '(extensiones),' v2 '- sólo por nuevos caminos/neymspaces.
Reglas de evolución: sólo agregando campos/valores, «deprecate → remove» a través de la ventana.
Pruebas de compatibilidad: «contratos como pruebas» (consumer-driven).

8) Eventos, webhooks y recibos

AsyncAPI describe temas/payload/firmas.
Firma: HMAC/EdDSA, encabezados 'X-Signature', 'X-Nonce', 'X-Timestamp' (ventana estrecha).
Recibos (receipts): 'receipt _ hash' y firma DSSE en eventos críticos (pagos, cambios de RTP/límites, listas de precios).
Retrai y dedoup: idempotencia por 'idempotency _ key '/' event _ id'.
DLQ/cuarentena: mensajes no válidos/repetidos con causas.

9) Observabilidad y calidad

Traces: obligatorios 'trace _ id/span _ id' a través de gateway/business events/webhooks.
Metrics: disponibilidad, p50/p95/p99, error-rate, retry-rate, costo por 1k.
Logs: estructurado, sin secretos/PII; etiquetas 'tenant/region/version'.
SLO/alertas: condiciones orientadas a SLO y runas automáticas (pause/re-route/rollback).

10) Errores y semántica de los estados

2xx es un éxito (202 para operaciones asíncronas).
4xx es culpa del cliente (422 son validación, 409 son conflicto/idempotencia, 429 son límites).
5xx - problemas temporales.
Cuerpo de error: 'code', 'message', 'trace _ id', 'hint', 'retry _ after?'.
UX para socios: tabla de «qué hacer» por cada error.

11) Políticas de código común (OPA/ABAC)

Autorización centralizada: «quién/qué/dónde/cuándo/por qué».
Políticas en Git, código de rugido, pruebas de CI (pre-vuelo: "¿permitirá la política? »).
Cheque SoD: «crear pago» ≠ «aprobar».

12) Seguridad, privacidad, cumplimiento

PII-minimización: tokenización/máscaras, acceso a la primaria sólo a través de jobs aprobados.
Secretos: Vault/KMS, TTL corto, rotaciones; prohibición de los secretos compartidos.
Cifrado: mTLS/TLS 1. 3, AES-GCM at-nat, HSTS/PKP cuando corresponda.
Jurisdiction-aware: localización de datos/claves por región.
Registros de auditoría: WORM, cortes de Merkle, firmas DSSE.

13) Operación: SLI/SLO y dashboards

• Disponibilidad per-route/region.
• Latencia p95 (lectura/escritura).
• Éxito de webhooks (recibos), Maga de envío.
• Error-rate/Retry-rate.
• Costo por 1k consultas y egresos.

SLO (ejemplo): 99. 95% de disponibilidad; p95 ≤ 120/250 ms; webhooks ≥ 99. 5 %/5-minas; P1 MTTR ≤ 60 minutos.

14) Gestión de cambios (lanzamientos/revisiones)

Blue-Green/Canary para pasarelas y rutas críticas.
Fichflags para un comportamiento sin liberación.
Expand→Migrate→Contract para circuitos y payload.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefactos: imágenes/manifiestos firmados, registro de versiones.

15) SDK, clientes, «sandbox»

SDK oficial (TS/Java/Python/Go) con la misma semántica de errores y retrocesos.
Sándbox con claves de prueba/certificados y simuladores de proveedores de contenido PSP/KYC.
Las pruebas de contrato se incluyen en SDK CI, compatibilidad nightly.

16) Modelo de datos (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 calidad

Contract Drift: 0 cambios «rompedores» sin deprechate.
Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, lag p95 ≤ 60 s.
Auto Fail vs Abuse: proporción de bloques maliciosos, ruido ≤ nivel objetivo.
Cost/1k: Control de rutas y regiones (presupuestos/cap-alertas).
SDK Adoption: una fracción del tráfico a través de los SDK oficiales.

19) Playbucks de incidentes

Spike 429/límites: elevar la tapa para Gold, trotar llaves «ruidosas», conectarse con un socio.
WebhookLag: aumentar los workers/batches, priorizar las colas, desactivar temporalmente los webhooks opcionales.
PriceMismatch (catalog/FX/Tax): conciliación de versiones, memoria caché con discapacidad de fuerza, retroceso del artefacto, compensación.
PSP Outage: cambio de ruta, cuarentena de transacciones «grises», réplicas.
Compromise API-key: revocación inmediata, rotación, auditoría de los últimos 30 días.

20) Especificidad de iGaming/fintech

API de RTP/Limits: sólo agregados y versiones de perfiles; cambios - con recibos.
Pagos/pagos: 202 + webhooks con firmas; idempotencia en la llave de la orden.
Afiliados: dedoop de conversiones, recrow de disputas, informes firmados.
Juego responsable: exhibe «guardrails API» para los límites y eventos RG.

21) Lista de verificación de implementación

• Contrato descrito (OpenAPI/AsyncAPI), validación CI y pruebas de consumo.
• Configurados OAuth2/OIDC, escopetas, secretos JIT y mTLS para rutas críticas.
• Se han introducido idempotencia, retraídas, DLQ y cuarentena.
• Límites/cuotas/prioridades y alertas por caps.
• Paginación con cursores, muestras consistentes de 'as _ of'.
• Versioning y Política de depreciación.
• Webhooks con firmas/recibos, réplicas y dedoop.
• Rastreo/métricas/registros, SLO y runas.
• Registros WORM, firmas DSSE, cortes de Merkle.
• SDK, sandbox, simuladores, ejemplos de código y «how-to».

22) FAQ

¿Por qué 202 para operaciones largas?
Para no mantener la conexión y proporcionar un retray/recibo confiable a través de webhook.

¿Necesitan ambos: OpenAPI y AsyncAPI?
Sí: sync para comandos/consultas, async para eventos/negociación de estados.

¿Cómo evitar los cambios rompedores?
Regla «sólo adiciones», deprecate → observe → remove, pruebas de contrato de clientes.

¿Dónde guardar los recibos?
En una zona WORM con firmas; 'receipt _ hash' se devuelve al cliente y se comprueba a petición.

Resumen: Las operaciones a través de API son la disciplina de contrato y operación: modelo estricto de acceso e idempotencia, límites y versiones, observabilidad y SLO, firmas y recibos. Agregue cajas de arena y SDK, y los socios se integrarán de manera rápida, segura y predecible, y el negocio se escalará sin pérdida de calidad y cumplimiento.