Un pedido entra bien, el ERP lo acepta, la tienda lo confirma y el almacén lo ve. Todo parece funcionar. Hasta que un día una actualización de catálogo cambia un campo, un pedido queda bloqueado y nadie sabe si la orden está realmente pendiente, cancelada o duplicada.
Integrar sistemas no es hacerlos hablar; es definir quién decide cuando no están de acuerdo.
Ese es el punto que muchas empresas descubren tarde. La integración API suele venderse como un proyecto técnico, pero en realidad es una decisión operativa: qué sistema es fuente de verdad, qué errores se toleran, qué se reintenta automáticamente y qué se escala a una persona.
El fallo típico: integrar sin contrato operativo
El error más común es pensar en endpoints, no en reglas. Se diseña el flujo de datos, pero no se responde a preguntas básicas:
- ¿Qué sistema manda sobre stock, precios, pedidos y clientes?
- ¿Qué ocurre si el ERP responde tarde o devuelve un error parcial?
- ¿Qué validaciones se hacen antes de crear un registro?
- ¿Cómo se detectan duplicados, diferencias de formato o campos vacíos?
- ¿Quién recibe la alerta y en qué plazo debe actuar?
Cuando estas respuestas no existen, la integración acaba convirtiéndose en una cadena de parches. El equipo comercial ve un estado, operaciones ve otro y soporte termina haciendo reconciliaciones manuales.
La tesis es simple: una integración útil no es la que mueve más eventos por minuto, sino la que reduce excepciones operativas y hace visible el fallo antes de que el cliente lo sufra.
Qué debe decidirse antes de programar
Hay tres decisiones que conviene cerrar antes de escribir una sola línea:
- Fuente de verdad por objeto: no basta con decir “el ERP manda”. Hay que especificar si manda para stock, tarifas, direcciones, impuestos, disponibilidad o estado del pedido.
- Política de errores: un error de validación no se reintenta igual que un timeout. Algunos fallos requieren cola; otros, rechazo inmediato; otros, revisión humana.
- Observabilidad mínima: cada integración necesita trazabilidad por ID de pedido o transacción, estado del mensaje, timestamp, causa del error y responsable de resolución.
Si esto no está documentado, el proyecto depende demasiado del desarrollador que lo construyó. Y eso es frágil.
Un criterio útil: si la empresa no puede explicar qué pasa con un pedido fallido sin abrir el código, todavía no tiene una integración madura.
Mini caso: cuando “funcionaba” pero no era operable
Una empresa mediana de distribución vendía por ecommerce y gestionaba pedidos en ERP. La integración funcionaba en el sentido estricto: los pedidos llegaban. Pero cuando había un fallo en la dirección de envío, el sistema no distinguía entre un error recuperable y uno definitivo.
Resultado: algunos pedidos quedaban en un estado ambiguo durante horas. El equipo de operaciones revisaba manualmente decenas de casos al día. El equipo comercial prometía plazos que el almacén no podía cumplir. Y cada caída pequeña generaba una cadena de correos.
La solución no fue “hacer una integración más robusta” en abstracto. Fue introducir reglas concretas:
- rechazo automático de direcciones incompletas,
- cola para incidencias temporales del ERP,
- alertas solo para errores sin reintento,
- panel de estados por tipo de fallo,
- y un responsable operativo para cada excepción.
El volumen no cambió mucho. La diferencia fue que las excepciones dejaron de ser misterio.
La decisión incómoda: a veces hay que aceptar menos automatización
Aquí está la parte menos popular: no todo debe automatizarse al 100 %.
En integraciones críticas, automatizar el 95 % y dejar el 5 % más delicado con revisión humana puede ser mejor que forzar una automatización total. Esto aplica especialmente a:
- pedidos de alto valor,
- cambios de dirección después del pago,
- clientes con condiciones comerciales especiales,
- inventario con alto riesgo de rotura de stock,
- y sincronizaciones que afectan a fiscalidad o facturación.
La decisión incómoda es admitir que la eficiencia aparente puede esconder riesgo operativo. La pregunta no es “¿podemos automatizarlo?”, sino “¿qué coste tiene equivocarse aquí?”.
Señales de que la integración ya está madura
No hace falta una suite enorme para saber si una integración está bien planteada. Estas señales ayudan:
- los errores tienen categoría y dueño,
- los reintentos están limitados y son trazables,
- los datos críticos tienen validación antes de entrar al ERP,
- las incidencias se resuelven con un SLA interno,
- y operaciones puede ver el estado sin depender del equipo técnico.
También hay una señal negativa muy clara: si cada incidencia termina en “reinicia el conector” o “vuelve a lanzar el proceso”, el sistema no está diseñado para operar, solo para sobrevivir.
La mejor integración API no se mide por su elegancia técnica, sino por cuánto reduce el trabajo invisible de reconciliación, seguimiento y corrección manual.
En proyectos así, en Codefuente solemos empezar por el contrato operativo antes que por la implementación, porque ahí se decide si una integración ayuda de verdad o solo añade otra capa de complejidad.