Morphosis API Gateway
Propuesta de diseño; aún no está lista para producción

Comprender primero el problema y sus límites

Contexto, objetivos y límites del diseño

Explica por qué se necesita un punto de acceso unificado, qué problemas de negocio debe resolver y qué responsabilidades no corresponden a la puerta de enlace.

Explica por qué se necesita un punto de acceso unificado, qué problemas de negocio debe resolver y qué responsabilidades no corresponden a la puerta de enlace.

1. Bases y conclusiones

1.1 Material de entrada

Este diseño utiliza el resumen formal de la reunión resumen formal de la reunión como registro confirmado y la transcripción literal transcripción de la reunión como evidencia contextual. La transcripción contiene fragmentos de baja confianza, frases repetidas y errores de identificación de hablantes; no debe utilizarse por sí sola para confirmar hechos de arquitectura de alto riesgo.

  1. transcripción de la reunión
  2. resumen formal de la reunión

El repositorio actual repositorio actual no contiene código de negocio ni documentación de arquitectura existente; por tanto, las selecciones técnicas, los objetivos de rendimiento y los indicadores operativos de este documento son propuestas de diseño y no representan hechos del sistema en producción.

1.2 Decisiones de negocio confirmadas

  1. API Gateway es el punto de entrada unificado de varias plataformas de pago, no un punto de entrada exclusivo de Zero Confirmation.
  2. Las primeras plataformas incluidas son WebPay Inbox, BPS y Zero Confirmation, y será necesario integrar otras plataformas de pago en el futuro.
  3. Una API Key debe expresar las plataformas, servicios y permisos de operación a los que puede acceder.
  4. Un comerciante puede tener varias API Key y utilizar varias direcciones IP de origen.
  5. Se debe establecer una vinculación explícita entre cada API Key y cada IP de origen; toda combinación de Key e IP sin vinculación debe rechazarse.
  6. El sistema debe admitir varias regiones, varias instancias de gateway y múltiples bases de datos de backend, proporcionando redundancia y capacidad de enrutamiento.
  7. La experiencia de diseño multirregional de Zero Confirmation deberá reutilizarse en BPS en el futuro.

1.3 Conclusiones de diseño

Se recomienda una arquitectura de "plano de control global unificado y plano de datos autónomo por región":

2. Objetivos y no objetivos

2.1 Objetivos

  1. Proporcionar un punto de entrada público o de red privada unificado para todas las API de comerciantes.
  2. Gestionar permisos de múltiples plataformas, servicios y operaciones con un modelo de autorización independiente de la plataforma.
  3. Validar con precisión la combinación de API Key e IP de origen, evitando la mezcla incorrecta de varias Key y varias IP del mismo comerciante.
  4. Admitir el ciclo de vida completo de creación, rotación, revocación, vencimiento, modificación de permisos y modificación de IP de las Key.
  5. Admitir escalado horizontal regional y despliegue multirregional, con un comportamiento claro de degradación y recuperación ante el fallo de una instancia de gateway o de una región.
  6. Proporcionar observabilidad completa para auditoría de seguridad, diagnóstico de incidentes, planificación de capacidad y SLO.
  7. Permitir que futuras plataformas de pago se integren mediante configuración y un proceso de incorporación estándar, sin modificar la lógica central de autenticación.

2.2 No objetivos

  1. No implementar la lógica de negocio de WebPay Inbox, BPS o Zero Confirmation dentro del gateway.
  2. No hacer que el gateway sea responsable de la replicación de bases de datos de negocio de las plataformas, transacciones entre bases de datos ni coherencia contable.
  3. No permitir que el gateway reproduzca automáticamente y sin control una solicitud de escritura de pagos de una región en otra región.
  4. No tratar las API Key como credenciales de inicio de sesión de usuarios del portal de comerciantes; el personal administrativo debe usar un sistema de identidad independiente y autenticación fuerte.
  5. No diseñar un sistema de facturación de comerciantes en esta fase, aunque se producirán eventos de uso que puedan utilizarse para facturación.

3. Principios fundamentales

  1. Denegación predeterminada: se rechaza toda solicitud ausente, desconocida, vencida, revocada o sin autorización explícita.
  2. Vinculación explícita: los permisos y las IP se vinculan directamente a una API Key concreta y no se heredan implícitamente desde una configuración de nivel de comerciante.
  3. Separación entre plano de control y plano de datos: los cambios administrativos pueden no estar disponibles temporalmente, pero el plano de datos existente debe seguir procesando solicitudes conocidas y válidas.
  4. Autonomía regional: la ruta crítica de una solicitud solo accede a componentes de su propia región y no depende de una base de datos interregional.
  5. El backend posee la coherencia de datos: el gateway solo selecciona un backend según la política de enrutamiento publicada y no participa en escrituras dobles de negocio.
  6. Exposición mínima de secretos: el API Secret se muestra una sola vez al crearse y el servidor conserva únicamente un resumen irreversible.
  7. Auditabilidad de extremo a extremo: todos los cambios del plano de control y las decisiones de autorización del plano de datos deben ser rastreables, pero los registros no deben almacenar el Secret original, campos sensibles de pago ni cuerpos completos de solicitudes.