Contratos y comunicación entre sistemas
¿Cómo pueden colaborar la pantalla de una aplicación y el servidor —o tu sistema y el de un banco— sin que uno tenga que leer ni conocer el código interno del otro? Lo logran mediante un contrato de comunicación. Cuando dos piezas de software fallan al integrarse, casi siempre se debe a que su contrato era ambiguo o incompleto.
Objetivos y conocimientos previos
Partiendo de Fronteras de confianza, aprenderás qué es un contrato lógico (interfaz o API), qué elementos debe especificar para no dejar casos en el aire, y cuándo conviene comunicarse de forma sincrónica (esperando respuesta inmediata) frente a asincrónica (mediante colas o eventos).
Qué es un contrato lógico (Interfaz o API)
En ingeniería de sistemas, una interfaz o API (Application Programming Interface) no es más que un acuerdo formal en la frontera entre dos componentes:
- El consumidor (cliente) se compromete a enviar una solicitud que cumpla ciertas condiciones y formato.
- El proveedor (servidor o módulo) se compromete a realizar una operación definida y devolver un resultado estructurado predecible, sin que el consumidor necesite saber cómo está programado por dentro.
Este acuerdo permite que ambos lados evolucionen por separado: mientras el proveedor respete el contrato prometido, puede mejorar su base de datos o cambiar de lenguaje sin romper a quienes se comunican con él.
Los cinco elementos de un contrato completo
Un error muy común al pedirle a un agente que conecte dos partes de un proyecto es definir el contrato solo para el «camino feliz» (happy path: cuando todo sale bien). Un contrato lógico riguroso debe especificar cinco puntos:
| Elemento del contrato | Qué define | Ejemplo en «Crear Reserva» |
|---|---|---|
| 1. Propósito y operación | Qué intención de negocio ejecuta y si consulta estado o lo modifica. | Solicitar el alta de una reserva activa para una actividad. |
| 2. Entrada requerida | Qué datos deben enviarse, con sus tipos y formatos exactos. | id_actividad (identificador válido) más la credencial de la persona autenticada. |
| 3. Precondiciones | Qué debe ser cierto para que la operación pueda aceptarse. | Persona autenticada y autorizada, actividad existente, plazas activas menores que la capacidad, sin reserva activa previa de esa persona. |
| 4. Salida de éxito (Postcondición) | Qué garantiza el proveedor que ocurrió y qué datos devuelve cuando todo se cumple. | Garantiza que la reserva quedó persistida en estado ACTIVA y devuelve { id_reserva, estado: "ACTIVA", fecha_creacion }. |
| 5. Salidas de rechazo o fallo | Qué devuelve de forma diferenciada cuando no se cumple una precondición o hay un error técnico. | Códigos distintos para: NO_AUTORIZADO, ACTIVIDAD_INEXISTente, AFORO_COMPLETO, RESERVA_DUPLICADA o ERROR_INTERNO. |
Observa la importancia del quinto punto: si ante cualquier problema el servidor responde simplemente "Error", la interfaz no sabrá si debe decirle al usuario «Ya tenías una reserva en esta actividad», «No quedan plazas» o «Hubo un fallo técnico temporal, inténtalo más tarde».
Comunicación sincrónica frente a asincrónica
Cuando el Componente A necesita que el Componente B haga algo, existen dos modos fundamentales de coordinar el tiempo:
- Componente Emisor envía solicitudModo Sincrónico
- El emisor espera bloqueado hasta que el receptor termina todo el proceso
- Recibe resultado final inmediato
Modo Asincrónico- Se registra la tarea en una cola/evento y se responde «Recibido» al instante
- El trabajo pesado se procesa en segundo plano y se notifica o consulta después
| Criterio | Comunicación Sincrónica | Comunicación Asincrónica |
|---|---|---|
| Cómo funciona | Quien llama espera en línea hasta recibir la respuesta definitiva. | Quien llama entrega el encargo (en un buzón o cola de eventos) y continúa; el receptor lo procesa a su ritmo. |
| Cuándo usarla | Cuando el usuario necesita saber el veredicto inmediato para continuar (ej. comprobar si hay plaza y confirmar la reserva). | Cuando la tarea es lenta, pesada o depende de terceros lentos (ej. generar un informe anual de mil facturas, enviar cien correos o analizar un documento largo con IA). |
| Riesgo si se elige mal | Si haces sincrónica una tarea que tarda 40 segundos, la pantalla se congela y la conexión se corta antes de terminar. | Si haces asincrónica una operación sin avisar en la interfaz que está «en proceso», el usuario creerá que ya terminó o que no hizo nada y volverá a pulsar el botón. |
Amortiguadores (Buffers y Colas)
En la comunicación asincrónica, ¿qué pasa si en un minuto llegan 500 solicitudes de generación de facturas en PDF, pero el procesador solo puede generar 10 por minuto?
Para no perder solicitudes ni tumbar el sistema, se coloca en medio una cola o buffer: una estructura persistente donde las tareas esperan en orden hasta ser procesadas. A cambio, el contrato del sistema debe incluir un estado explícito para esa tarea (EN_COLA, PROCESANDO, COMPLETADO, FALLIDO) para que el usuario o el sistema puedan consultar cómo terminó.
Practica
Diseñas un módulo donde un cliente sube las fotos de 20 recibos de gastos del mes para que un modelo de IA extraiga los datos y prepare un borrador de informe contable. El proceso completo de lectura y análisis de las 20 imágenes tarda unos 45 segundos.
- Explica qué ocurrirá en la experiencia del usuario y en la conexión si diseñas este contrato como una única llamada sincrónica que no responde nada hasta terminar las 20 imágenes.
- Diseña una alternativa asincrónica: ¿qué debe devolver el servidor en el primer segundo tras recibir las imágenes y qué estados debe tener el lote de recibos mientras se procesa?
- Define el contrato de salida para cuando una de las 20 imágenes esté borrosa y no pueda leerse: ¿debe fallar todo el lote de 20 recibos o debe el contrato permitir informar qué recibos se procesaron con éxito y cuál requiere revisión humana?
Criterio de comprensión: debes proponer una recepción inmediata con identificador de lote/tarea y estados de progreso, y especificar un contrato de resultado capaz de distinguir éxitos parciales y elementos que requieren intervención humana sin descartar los 19 recibos válidos.
Profundiza con IA
Este es mi diseño de contrato para el procesamiento de lotes de recibos: [tu respuesta]. Actúa como el desarrollador encargado de construir la pantalla del usuario que consume mi contrato. Hazme tres preguntas sobre casos que no haya dejado claros en el contrato (por ejemplo, límites de tamaño, cómo saber cuándo terminó o qué pasa si la misma imagen se sube dos veces) para ayudarme a cerrarlo.
Siguiente lectura
Incluso con el mejor contrato del mundo, la red que conecta dos sistemas puede cortarse justo cuando la respuesta venía de vuelta. ¿Cómo evitamos que la incertidumbre duplique operaciones críticas? Cerramos el curso con Fallos en red, incertidumbre e idempotencia.