Hoja de cálculo de integración de API

0) Revisión rápida (quién hace qué)

• El propietario de la integración está asignado
• Contacto on-call (24 × 7/esclavo. relojes) recetados
• SLO/SLA convenidos y ventana de soporte de lanzamiento
• Status page y canal de incidentes (email/Slack/Webhook)

1) Accesos, entornos, versiones

• Acceso a sandbox/staging/production obtenido
• Versión de la API confirmada: '/v1 '/título 'X-API-Version'
• Allowlist IP y reglas de red están configuradas
• Relojes y TZ: todo el tiempo en UTC, NTP sincronización
• Se verificó la compatibilidad de SDK/clientes con SemVer y la matriz de versiones

2) Autenticación y tokens

• Mecanismo negociado: OAuth2 Credentials/Auth Code + PKCE/API Clave/mTLS
• La vida útil de Access Token y la rotación de Refresh Token están personalizadas
• Para API Key: el secreto se muestra una vez, se guarda en el gestor de secretos
• JWKS/JTI/' kid 'son verificados, clock skew activado ± 5 min
• 'Authorization' los titulares no son lógicos (revisión)

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3) Seguridad y privacidad

• TLS 1. 2 +/HSTS, opcional mTLS
• Minimización PII: sólo enviamos las máscaras deseadas en los logs
• Política de retención y eliminación (GDPR/DSAR) documentada
• Rotación secreta: clave activa/siguiente, plan de rollover
• Anti-Abuse: capcha/velocidad de creación de claves/restricciones de registro

4) Límites, cuotas y backoff

• Anunciados 'X-RateLimit- '/' X-Quota-' titulares
• El cliente respeta el 429 y el 'Retry-After'
• Retrés sólo para 5xx/408/429, retroceso exponencial + jitter
• Se establece un límite de tiempo/intento (por ejemplo, ≤ 5 intentos ≤ 60s en total)

5) Idempotencia y conflictos

• Todas las operaciones de escritura se envían con 'Idempotency-Key' (TTL ≥ 24-72 h)
• Conflicto de duplicados → 409 IDEMP_REPLAY se procesa
• ETag/' If-Match 'para actualizaciones competitivas habilitadas (si está disponible)

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6) Paginación y deltas incrementales

• Se utiliza la paginación cursor/keyset ('next _ cursor', 'has _ more')
• Ordenación estable '(updated_at, id)' está documentada
• Descargas incrementales: watermark o change token
• Ventanas superpuestas (overlap 1-2 min) y dedoop por '(id, version/seq)'

7) Formato de error y diagnóstico

• Formato único 'application/problem + json' (RFC 7807)
• Soporte de campo: 'error _ code', 'trace _ id', 'retriable', 'detail'
• Mapa de errores y acciones del cliente descritas (runbook)

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8) Webhooks: recibo y repeticiones

• Confirmación de éxito - cualquier 2xx; ACK rápido después de enqueue
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Política de retiro: backoff + jitter, hasta 24-72 horas
• DLQ + Replay: disponible y validado
• Almacenamiento de dedoop en el receptor, TTL ≥ ventanas retraídas

9) Observabilidad y rastreo

• Se incluye OpenTelemetry Hooks en el cliente/SDK
• Correlación 'trace _ id '/' X-Request-ID' en toda la cadena
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms: ráfaga de 5xx/429, aumento de p95, caída de la tasa de éxito, lag webhooks

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10) Productividad y sostenibilidad

• Grupos de conexiones, keep-alive, HTTP/2/3 donde sea posible
• El paralelismo es limitado (backpressure), la cola del cliente no se «inflará»
• Las políticas de circuit-breaker/timeout/fallback están configuradas
• Pruebas de carga: burst 10 ×, conexiones largas, inicio en frío

11) Datos, monedas, tiempo

• Formatos: ISO-8601 UTC, dinero - líneas decimales/unidades menores, locales no dependen del entorno
• Las codificaciones/lenguajes son consistentes (por ejemplo, 'Accept-Language' para mensajes, pero 'error _ code' es automática)
• Política de redondeo/comisiones documentada

12) Conciliación y presentación de informes (reconciliation)

• Conciliaciones diarias/horarias con cantidades de control
• API/descargas para conversiones probadas (CSV/JSON, manifiestos/hashes)
• Discrepancias - en tickets con referencias a 'trace _ id'

13) Cumplimiento y aspectos jurídicos

• Se aceptan las condiciones de uso de la API (fair use/nat control)
• PII/Titulares de datos - Funciones y zonas de almacenamiento definidas
• Legal Hold/Auditoría-registro de acciones habilitadas en incidentes

14) Documentación y portal de desarrolladores

• OpenAPI/AsyncAPI son relevantes, hay ejemplos de «copiar-pegar»
• SDK (TS/Py/Java/Go/.NET) - versiones acordadas, Cookbook disponible
• Try-it playground funciona, las claves de arena están activas
• Changelog/deprecation/roadmap son visibles en el portal

15) Pruebas: funcional, negativo, caos

Funcional

• CRUD/scripts clave completados (happy path)
• Paginación/cursor/delta incremental

Negativos

• 401/403/404/409/422/429/5xx y tratamiento 'Retry-After'
• Firma web incorrecta, tokens caducados, cuerpos grandes

Caos

• Drop 10-30% eventos, reordenar, retrasos de 1-10 minutos
• Desactivar dependencias (PSP/KYC) → errores/fallback correctos

16) Aceptación y lanzamiento (go-live)

• Se ha completado la revisión final de PRR (Producción Readiness Review)
• Inclusión canaria: 10% → 25% → 50% → 100%
• Retroceso automático por señales SLO (errores/latencia/429)
• Se publica la matriz de contacto de incidentes y la ruta de escalamiento
• Backlog CAPA después del piloto formado por

17) Operación y apoyo

• Runbook/playbooks: «5xx spike», «429 storm», «webhook backlog», «timeout»
• Informes periódicos sobre SLO/Error Budget
• Rotación de secretos y claves según lo programado
• Plan de deprecación/migración de versiones acordado (fecha sunset)

18) Patrones de artefactos

Plantilla de configuración env

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

Política de retiro (pseudo)

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19) Lista de comprobación final «a la firma»

• Los entornos/versiones/claves/allowlist están listos
• Auth/JWT/keys/mTLS configurados y probados
• Límites/cuotas/retraídas/idempotencias implementadas
• La paginación/cursor/delta funciona con datos
• Webhooks: firmas, repeticiones, DLQ/Replay verificados
• Los errores 'problem + json', 'trace _ id' se adhieren a todos los registros
• Dashboards/alertas recogidas, OTel incluido
• Pruebas de carga/negativas/caos superadas
• Las conciliaciones y los informes convergen, runbooks formalizados
• PRR/canario/rollback-plan listo, contactos on-call especificado

Resultado

Este cheque cierra los aspectos técnicos, operativos y de cumplimiento de la integración de API. Pase los puntos de arriba hacia abajo, automatice la verificación de límites, idempotencia y webhooks, active la observación y el plan de retroceso, y su lanzamiento se llevará a cabo previsiblemente, sin «sorpresas» en la producción.