Microservicios e Integración ERP para Empresa Constructora
Construcción · API e Integración de Sistemas — Una arquitectura de microservicios que entregó cinco dominios de integración independientemente desplegables para una empresa constructora — diseñada para integrarse con su entorno productivo activo sin interrumpir ni un día de operaciones.
Una empresa constructora consolidada con un departamento interno de tecnología contactó a J14 Design con un mandato específico y bien delimitado: no necesitaban un equipo externo que reconstruyera sus sistemas. Tenían ingenieros internos capaces de mantener y desarrollar su plataforma central. Lo que necesitaban era un partner especializado para diseñar y entregar la capa de microservicios responsable de integrar sus sistemas existentes con un conjunto de plataformas externas — sin interrumpir el trabajo de desarrollo en curso, sin crear dependencias arquitectónicas que el equipo interno no pudiera mantener, y sin introducir decisiones técnicas que generaran restricciones a largo plazo. Este fue un engagement de partnership técnico, no una toma total del proyecto.
El Desafío
Complejidad de integración sobre un entorno productivo activo. La plataforma central de la empresa estaba en uso activo — gestionando cronogramas de proyectos, adquisiciones, coordinación de subcontratistas, reportes de campo y flujos de documentos en obras activas. Cualquier trabajo de integración debía ocurrir sin comprometer la estabilidad de esos sistemas en funcionamiento.
- Conectividad con ERP — los datos operativos y de campo generados fuera del ERP debían fluir hacia él de forma confiable, con lógica de transformación que respetara el modelo de datos del ERP sin requerir modificaciones a la plataforma central.
- Plataforma de gestión de subcontratistas — conectar con los procesos internos de asignación de proyectos y aprobación para onboarding, seguimiento de cumplimiento, verificación de seguros y flujos de pago.
- Sincronización con sistema contable — datos financieros incluyendo órdenes de compra, asignaciones de costo por obra, aprobaciones de facturas y estado de pagos, sincronizados bidireccionalmente con lógica de resolución de conflictos y trazabilidad.
- Gestión de documentos y firma electrónica — contratos, órdenes de cambio y documentos de cumplimiento enviados a un servicio cloud con callbacks de estado actualizando el sistema interno.
- Agregación de datos de campo — datos capturados por supervisores en dispositivos móviles debían llegar al backend en formato estructurado y validado, con lógica para manejar conectividad intermitente desde obras remotas.
La Arquitectura
J14 Design entregó una arquitectura de microservicios orientada a dominios en la que cada preocupación de integración fue aislada en su propia unidad de servicio independientemente desplegable. En lugar de construir una capa de middleware monolítica que se convertiría en una dependencia compartida, cada servicio tenía su propia configuración, lógica de reintento, manejo de errores y contrato de interfaz. Responsabilidad única: cada microservicio era dueño de exactamente un dominio de integración. Diseño API-first por contrato: antes de escribir código de implementación, se produjeron documentos de especificación OpenAPI definiendo cada endpoint, payload, respuesta de error y evento webhook. Operaciones idempotentes: todas las operaciones de sincronización fueron diseñadas para ser re-ejecutables de forma segura. Comunicación orientada a eventos: servicios se comunicaban a través de una cola de eventos. Patrón Circuit Breaker: cada integración de salida implementó lógica de circuit breaker para prevenir fallas en cascada.
Servicios Entregados
1. Servicio de Integración ERP
Consumía eventos de la plataforma interna y los transformaba al formato esperado por el ERP mediante un motor de mapeo de campos configurable.
- Pushes en tiempo real activados por webhooks
- Sincronización batch programada para conjuntos de datos de alto volumen
- Endpoint de reporte de reconciliación para verificar estado de sincronización e identificar discrepancias
2. Bridge de Plataforma de Subcontratistas
Conectó el flujo de asignación interno con la plataforma externa de gestión de subcontratistas.
- Verificación automática de estado de cumplimiento al momento de la asignación
- Verificación de validez de seguros y completitud de onboarding
- Eventos de activación de pago reenviados a la plataforma externa al aprobar internamente
3. Servicio de Sincronización Contable
Gestionó el flujo bidireccional de datos financieros entre la plataforma interna y el sistema contable.
- Capa de staging que retenía registros pendientes de validación antes de commitear
- Trazabilidad completa de cada evento de sincronización y decisión de resolución de conflictos
- Log de auditoría accesible para ambos equipos
4. Servicio de Flujo Documental
Manejó el ciclo de vida completo de documentos que requerían firma electrónica o archivado.
- Push de documentos al proveedor cloud al momento de generación
- Lógica de secuencia de firma simple y multi-parte
- Callbacks entrantes de webhook para actualizar estado y activar notificaciones downstream
5. Servicio de Agregación de Datos de Campo
Actuó como gateway de entrada para datos capturados en campo por dispositivos móviles.
- Validación de payload, aplicación de esquemas y deduplicación
- Manejo de entrega fuera de orden usando numeración de secuencia y reconciliación de timestamps
- Aplicación correcta de registros después de brechas de conectividad sin sobrescribir datos más recientes
Decisiones Técnicas Clave
- Límites de servicio orientados al dominio: Cada límite de servicio fue definido por el dominio de negocio que servía, no por el método técnico de integración. Esto significó que el servicio de subcontratistas contenía toda la lógica relacionada con flujos de subcontratistas, independientemente de si esa lógica involucraba una llamada API, una lectura de base de datos o un webhook.
- Gestión centralizada de secretos y configuración: Todas las credenciales de terceros, claves API y valores de configuración específicos del entorno se gestionaron a través de la infraestructura de gestión de secretos existente de la empresa. Los servicios de J14 Design consumían configuración únicamente a través de variables de entorno — nunca mediante valores hardcodeados o credenciales en el repositorio.
- Observabilidad completa desde el primer día: Cada servicio expuso un endpoint /health, un endpoint /metrics en formato Prometheus y salida de log estructurado con nomenclatura de campos consistente. Se configuraron reglas de alertas de línea base para umbrales de tasa de error, degradación de tiempo de respuesta y lag de sincronización antes del handoff.
Tecnologías Utilizadas
- Node.js
- Docker
- OpenAPI / Swagger
- REST APIs
- Webhooks
- Arquitectura de cola de eventos
- Circuit Breaker Pattern
- Operaciones idempotentes
- Métricas Prometheus
- Logs JSON estructurados
- Conector ERP
- Integración API de firma electrónica
- PostgreSQL
- Gestión de configuración por variables de entorno
Resultados e Impacto
- Cinco dominios de integración entregados como microservicios independientemente desplegables y completamente documentados — dentro del alcance, en plazo y sin interrupciones al entorno productivo activo.
- Onboarding del equipo interno completado en menos de 3 días gracias a especificaciones OpenAPI, configuraciones Docker, runbooks de despliegue y documentación arquitectónica completa.
- Cero incidentes en producción durante los períodos de operación paralela previos a cada cutover. Cada discrepancia de datos fue resuelta antes del cutover, no después.
- Fallas de integración reducidas a casi cero — los patrones de circuit breaker y el diseño de operaciones idempotentes eliminaron la clase de fallas de sincronización intermitentes que previamente requerían intervención manual.
- El equipo interno extendió dos de los cinco servicios en el primer trimestre post-handoff sin requerir intervención de J14 Design — el resultado esperado desde el diseño.
Más Casos de Éxito
- Plataforma POS y CRM para Retail Multitienda: 98.7% de Precisión — Plataforma POS y CRM cloud-native construida para una empresa retail multitienda en el sur de la Florida — reemplazando infraestructura fragmentada y semi-offline con un sistema operativo unificado.
- App Móvil Offline-First para Operaciones en Campo (iOS y Android) — Una app nativa iOS y Android junto a una plataforma web en tiempo real — reemplazando formularios en papel, hojas de cálculo y comunicación fragmentada para una empresa de servicios en campo en 2 países de América Latina.