Integrar la API de un ERP en producción es una de las operaciones de mayor riesgo de cualquier proyecto IT: una mala integración bloquea facturación, duplica asientos contables o detiene la operación completa. Esta guía describe el patrón seguro que aplicamos en Uniamos para integrar SAP, Odoo, NetSuite, Aspel, Contpaq y Dynamics sin interrupciones — usable también si lo haces tú mismo.
Respuesta corta: nunca conectes un sistema externo directo a la API del ERP. Construye una capa middleware idempotente entre los dos, despliega en modo solo-lectura primero (5-7 días), luego habilita escritura solo en entidades de baja criticidad, después haz despliegue por etapas (10% → 50% → 100%) y monitorea 24/7 con plan de rollback probado.
1. Por qué fracasan las integraciones de ERP
De las integraciones de ERP que vemos fallar en empresas mexicanas y españolas, casi todas cometen al menos uno de estos cinco errores que la guía evita:
- Conexión directa sin middleware. El sistema externo (web, ecommerce, CRM) llama directo a la API del ERP. Cualquier cambio en el ERP rompe la integración. No hay capa de protección.
- No implementar idempotencia. Si la red falla y el sistema reintenta, se crea el pedido dos veces. En 6 meses tienes facturación duplicada.
- Habilitar escritura desde el día 1. Sin un periodo de solo-lectura previo no detectas errores de mapeo antes de que se conviertan en problema fiscal.
- Ignorar rate limits del ERP. Casi todos los ERPs tienen límites de llamadas/segundo. Si los superas, el ERP empieza a tirar errores 429 y bloquea operaciones reales del equipo.
- No tener plan de rollback. Cuando algo va mal, el equipo IT entra en modo pánico porque no sabe cómo desactivar la integración rápido.
2. Arquitectura mínima recomendada
La arquitectura que aplicamos en Uniamos tiene tres capas:
2.1 Capa de sistema externo
El sistema que necesita los datos del ERP: web, ecommerce, chatbot, CRM, app móvil. Nunca toca la API del ERP directamente.
2.2 Capa middleware (la clave)
Una capa intermedia desplegada en infra propia o en la nube (AWS, GCP, Azure, Vercel Functions, Cloudflare Workers) que:
- Expone una API estable al sistema externo (no la del ERP directamente).
- Traduce entre el esquema externo y el esquema del ERP.
- Implementa idempotencia con un idempotency-key por operación.
- Aplica rate limiting hacia el ERP para no superar sus límites.
- Reintenta con backoff exponencial cuando hay errores transitorios.
- Loguea cada operación con metadata para auditoría posterior.
- Cachea lecturas costosas con invalidación inteligente.
2.3 Capa ERP
El ERP en sí. Idealmente con un usuario API dedicado (no el de un humano), permisos limitados al alcance necesario, y monitoreo de uso desde el lado del ERP.
3. Proceso de despliegue paso a paso
Auditoría inicial (semana 1)
Revisar versión del ERP, tipo de API disponible (REST, SOAP, RFC, OData), permisos del usuario API, límites de rate y zonas de datos sensibles (facturación, cuentas bancarias, RH). Documentar todo antes de tocar nada.
Diseño del middleware (semana 2)
Definir endpoints estables del middleware, esquema de idempotencia, política de reintentos (típicamente 3 intentos con backoff 1s/4s/16s), formato de logs (structured logging tipo JSON), y métricas a exponer (latencia, errores por endpoint, contador de operaciones).
Desarrollo y testing (semanas 2-4)
Construir el middleware, escribir tests unitarios y de integración (mockear el ERP para tests automatizados), preparar un entorno sandbox del ERP si está disponible. No tocar producción todavía.
Modo solo-lectura en producción (semana 5)
Habilitar el middleware leyendo del ERP en producción pero SIN escribir. El sistema externo puede consultar productos, clientes, pedidos, pero no crear nada. Validar 5-7 días que los datos se reflejan correctamente.
Escritura en entidades de baja criticidad (semana 6)
Activar escritura solo en entidades que si fallan no rompen el negocio: catálogo de productos, contactos, leads. Aún no facturas ni asientos contables.
Despliegue por etapas (semanas 7-8)
Una vez validado, activar escritura en entidades críticas (facturas, CFDI, asientos) en etapas: primero 10% del tráfico, monitorear 48h, luego 50%, monitorear 48h, finalmente 100%. Si algo falla en una etapa, rollback inmediato.
Monitoreo continuo
Alertas en Slack o email para: errores 5xx del ERP, latencia >1s, discrepancias entre datos del sistema externo y el ERP, rate limit alcanzado, autenticación fallida. Revisión diaria los primeros 30 días, luego semanal.
¿Necesitas integrar un ERP en producción sin riesgo?
Lo hacemos en Uniamos para empresas en México, LATAM y España. Diagnóstico gratuito.
4. Comparativa de los ERPs más usados
| ERP | Tipo API | Dificultad | Tiempo típico integración |
|---|---|---|---|
| Odoo | REST + XML-RPC + JSON-RPC | Baja | 3-5 semanas |
| NetSuite | SuiteTalk REST + SuiteScript | Media | 5-7 semanas |
| Microsoft Dynamics 365 | OData + REST | Media | 4-6 semanas |
| SAP Business One | Service Layer (OData) | Media-Alta | 6-8 semanas |
| SAP S/4HANA | OData + RFC | Alta | 8-12 semanas |
| Aspel SAE | API REST limitada + DB | Media | 5-7 semanas |
| Contpaq i | SDK + DB | Media-Alta | 6-8 semanas |
| Holded | REST clean | Baja | 3-5 semanas |
5. Patrón de idempotencia (lo más importante)
Si solo te llevas una cosa de esta guía, que sea esta: nunca hagas una llamada de escritura al ERP sin un idempotency-key. El patrón es simple:
- El sistema externo genera un UUID único para cada operación de escritura (ej:
create_order_550e8400-e29b-41d4-a716-446655440000). - El middleware guarda en su base de datos:
{idempotency_key, status, result_from_erp}. - Antes de llamar al ERP, el middleware busca si la key ya existe. Si existe y tiene resultado, devuelve ese resultado sin volver a llamar al ERP.
- Si no existe, llama al ERP, guarda el resultado y lo devuelve.
- Si la llamada al ERP falla con timeout, el middleware no sabe si la operación se ejecutó o no. La próxima vez que reciba la misma idempotency-key, hará una consulta al ERP para verificar antes de reintentar.
Sin esto, una pérdida de red durante una operación de "crear factura" puede generar dos facturas duplicadas — y en México, con CFDI 4.0 timbrado, eso es un problema fiscal serio.
6. Errores específicos del contexto mexicano
Si tu ERP opera en México, además hay dos consideraciones críticas:
6.1 CFDI 4.0 y timbrado con el PAC
Si la integración crea facturas, hay que coordinar con el PAC (FactureHoy, Factura.com, Solución Factible, FacturaXpress, FormasDigitales) para que cada factura se timbre con los datos correctos: RFC, uso de CFDI, método de pago, régimen fiscal. Una factura mal timbrada es una factura que el cliente rechaza y un problema con el SAT.
6.2 Complementos de pago
Cuando se cobra una factura previamente emitida en parcialidades, hay que emitir un CFDI de Pago adicional. La integración debe disparar esto automáticamente cuando detecte el pago en la pasarela. Es donde la mayoría de integraciones fallan silenciosamente y a final de año hay decenas de pagos sin complemento que el SAT puede objetar.
Preguntas frecuentes
¿Cómo integro la API de un ERP sin parar mi operación?
Middleware idempotente entre ERP y sistema externo, despliegue por etapas (10% → 50% → 100%), modo solo-lectura inicial 5-7 días antes de escritura, plan de rollback probado, monitoreo 24/7. Nunca conexión directa.
¿Qué ERPs tienen API más fácil?
Odoo, NetSuite, Microsoft Dynamics 365 y Holded son los más amigables. SAP B1 y S/4HANA son más complejos pero potentes. Aspel y Contpaq requieren conectores específicos.
¿Cuáles son los errores más frecuentes?
Conexión directa sin middleware, falta de idempotencia, escritura desde el día 1, ignorar rate limits del ERP, no tener plan de rollback, no monitorear discrepancias.
¿Cuánto tarda integrar una API de ERP?
4-8 semanas para integración estándar. Auditoría 1 sem, middleware 2-3 sem, validación solo-lectura 1 sem, despliegue por etapas 1-2 sem. Casos complejos multi-país: 12-16 semanas.
¿Cuánto cuesta integrar un ERP?
Simple desde 50.000 MXN (~2.800 USD). Mediana 100.000-250.000 MXN (~5.500-14.000 USD). Compleja con CFDI 4.0 250.000+ MXN. Más mantenimiento mensual del middleware.
Integración de ERP llave en mano
Diagnóstico gratuito de 30 minutos. Te decimos el plazo, costo y arquitectura exacta para tu caso.
Sobre Uniamos. Implementamos integraciones de ERP, CRM y APIs en empresas en México, LATAM y España. Más sobre nuestro servicio de integraciones y APIs o vuelve al blog.