El Problema de las Integraciones Externas en el Mundo Real
Cuando diseñamos sistemas empresariales en Bolivia y Latinoamérica —particularmente aquellos que integran cobros interbancarios por QR y emisión de Facturación Electrónica en Línea (como el sistema SIAT del Servicio de Impuestos Nacionales)— debemos partir de una premisa innegociable: los servicios externos fallarán en el momento menos oportuno.
Las redes sufren microcortes, los certificados TLS de terceros expiran, los servidores gubernamentales entran en ventanas de mantenimiento o responden con errores 502 Bad Gateway tras quince segundos de espera. Si la arquitectura de nuestro sistema asume que una llamada HTTP externa dentro de una transacción de negocio siempre tendrá éxito inmediato, tarde o temprano sufriremos las dos peores pesadillas de un sistema comercial: cobrarle al cliente sin emitir ni registrar su pedido, o emitir facturas duplicadas ante el reintento del usuario.
En este artículo detallo la arquitectura basada en Máquinas de Estado Inmutables, Claves de Idempotencia y el patrón Transactional Outbox que implementamos en FORBUS S.R.L. para lograr tolerancia a fallos de grado bancario.
1. Anatomía de una Falla de Escritura Dual (Dual-Write Problem)
Analicemos el antipatrón más frecuente en aplicaciones web tradicionales:
- El controlador recibe la petición de venta, abre una transacción en la base de datos, descuenta el stock y guarda el registro de la venta.
- Antes o inmediatamente después de hacer
COMMIT, el servicio realiza una petición HTTP hacia la pasarela de facturación electrónica o coloca un mensaje en Redis/RabbitMQ.
¿Qué ocurre si la llamada HTTP dentro de la transacción tarda 25 segundos en responder? La fila del producto en la base de datos permanece bloqueada durante esos 25 segundos, congelando a todos los demás compradores que intentan adquirir el mismo artículo y agotando el pool de conexiones. Peor aún: si la base de datos confirma la venta (COMMIT) y un milisegundo después el proceso de Node.js se reinicia antes de encolar el trabajo en Redis, la venta queda registrada pero la factura electrónica jamás se emite.
Renderizando Diagrama de Arquitectura...
2. Implementación del Patrón Transactional Outbox en PostgreSQL
El patrón Transactional Outbox elimina por completo la escritura dual. En lugar de comunicarnos con la red externa o con un broker de mensajería durante la transacción del usuario, insertamos la intención de envío como un registro más dentro de una tabla outbox_events en la misma transacción de PostgreSQL. Dado que tanto la tabla de ventas como la tabla outbox_events residen en el mismo motor relacional, la atomicidad ACID garantiza al 100% que ambos registros existen juntos o ninguno existe.
sqlCREATE TABLE integraciones.outbox_events ( id_evento UUID PRIMARY KEY, agregado_tipo VARCHAR(60) NOT NULL, agregado_id UUID NOT NULL, tipo_evento VARCHAR(80) NOT NULL, payload JSONB NOT NULL, estado VARCHAR(20) NOT NULL DEFAULT 'PENDIENTE', intentos INT NOT NULL DEFAULT 0, max_intentos INT NOT NULL DEFAULT 10, proximo_intento_en TIMESTAMPTZ NOT NULL DEFAULT now(), ultimo_error TEXT, creado_en TIMESTAMPTZ NOT NULL DEFAULT now(), procesado_en TIMESTAMPTZ ); -- Índice parcial: solo indexa los eventos que aún requieren trabajo, -- manteniendo el índice diminuto en memoria aunque la tabla tenga millones de históricos. CREATE INDEX idx_outbox_pendientes_ejecucion ON integraciones.outbox_events (proximo_intento_en ASC) WHERE estado IN ('PENDIENTE', 'REINTENTANDO');
El uso de un índice parcial (WHERE estado IN ...) es una decisión crítica de rendimiento. A medida que el sistema procesa millones de facturas y su estado pasa a COMPLETADO, esas filas salen automáticamente del índice B-Tree. De este modo, el recolector asíncrono consulta siempre un índice de pocos kilobytes en menos de un milisegundo.
Extracción Concurrente sin Colisiones mediante SKIP LOCKED
Para que múltiples instancias de nuestros workers en NestJS procesen la cola simultáneamente sin enviar dos veces la misma factura, utilizamos FOR UPDATE SKIP LOCKED:
sqlWITH lote_reclamado AS ( SELECT id_evento FROM integraciones.outbox_events WHERE estado IN ('PENDIENTE', 'REINTENTANDO') AND proximo_intento_en <= clock_timestamp() ORDER BY proximo_intento_en ASC LIMIT 20 FOR UPDATE SKIP LOCKED ) UPDATE integraciones.outbox_events o SET estado = 'PROCESANDO', intentos = o.intentos + 1 FROM lote_reclamado l WHERE o.id_evento = l.id_evento RETURNING o.id_evento, o.agregado_id, o.tipo_evento, o.payload, o.intentos;
Si el Worker 1 toma las primeras veinte filas, el Worker 2 que ejecuta la misma consulta un milisegundo después no se queda esperando en cola: salta inmediatamente las filas bloqueadas (SKIP LOCKED) y toma las siguientes veinte disponibles.
3. Idempotencia Determinista y Máquinas de Estado Finitas
En entornos móviles con conectividad inestable, es habitual que el teléfono del cliente envíe la solicitud de pago o pedido, el servidor la procese correctamente, pero la respuesta se pierda en la red celular antes de llegar a la pantalla del usuario. Cuando el usuario vuelve a presionar el botón "Confirmar", debemos garantizar que la operación sea idempotente.
En lugar de confiar en validaciones temporales frágiles (como bloquear peticiones similares durante cinco segundos), implementamos una tabla de control de idempotencia vinculada a una clave determinista generada por el cliente o derivada criptográficamente del contexto de la orden:
typescript// Ejemplo de transición de estado estricta en la capa de dominio (TypeScript / NestJS) export type EstadoDocumentoFiscal = | 'BORRADOR' | 'PENDIENTE_ENVIO' | 'EMITIDA_EN_LINEA' | 'EMITIDA_CONTINGENCIA' | 'OBSERVADA_RECHAZADA' | 'ANULADA'; const TRANSICIONES_PERMITIDAS: Record<EstadoDocumentoFiscal, readonly EstadoDocumentoFiscal[]> = { BORRADOR: ['PENDIENTE_ENVIO'], PENDIENTE_ENVIO: ['EMITIDA_EN_LINEA', 'EMITIDA_CONTINGENCIA', 'OBSERVADA_RECHAZADA'], EMITIDA_CONTINGENCIA: ['EMITIDA_EN_LINEA', 'OBSERVADA_RECHAZADA'], EMITIDA_EN_LINEA: ['ANULADA'], OBSERVADA_RECHAZADA: ['PENDIENTE_ENVIO', 'ANULADA'], ANULADA: [], }; export function validarTransicionFiscal( estadoActual: EstadoDocumentoFiscal, nuevoEstado: EstadoDocumentoFiscal, ): void { const permitidos = TRANSICIONES_PERMITIDAS[estadoActual] ?? []; if (!permitidos.includes(nuevoEstado)) { throw new Error( `Transición de estado fiscal inválida: no es posible pasar de [${estadoActual}] a [${nuevoEstado}].`, ); } }
Cuando el servicio de impuestos reporta indisponibilidad prolongada o el tiempo de respuesta supera el umbral operativo definido, la máquina de estados conmuta limpiamente de PENDIENTE_ENVIO a EMITIDA_CONTINGENCIA, firmando y entregando el comprobante al comprador al instante y programando el evento de regularización de paquete para cuando el servicio externo se restablezca.
Conclusión
La resiliencia en ingeniería de software no consiste en esperar que la red nunca falle, sino en diseñar sistemas donde las fallas externas sean eventos ordinarios previstos en la máquina de estados. Combinar el patrón Transactional Outbox, índices parciales en PostgreSQL e idempotencia estricta permite que las empresas operen de forma continua las veinticuatro horas, independientemente de la estabilidad de los servicios de terceros.