Integrar pedidos con un ERP: revisión manual, envíos idempotentes y log de sincronización
EN BREVE: El error más común al integrar un ERP es tratar “el ERP aceptó el pedido” como “el pedido se completó”. Muchos ERP siguen revisando los pedidos a mano y contabilizan el movimiento de stock después, y la plataforma solo puede esperar. Damos a cada envío una clave de negocio estable para poder reintentarlo sin riesgo, obtenemos el estado consultando en lugar de fiarnos de una sola respuesta, escribimos cada acción de sincronización en un log y ejecutamos una conciliación diaria para encontrar documentos que ya no coinciden en ambos lados.
1.0 Primero, dibujar el flujo de negocio
Antes de escribir código de integración, siéntese con el implantador del ERP y con el responsable de negocio y anote cada paso desde el pedido hasta la factura. Indique en qué lado ocurre cada paso y si es automático o manual. Una cadena típica: alta de cliente, envío del pedido, revisión en el ERP, contabilización del movimiento de stock, envío con número de seguimiento, confirmación del cobro y descarga de la factura.
Marcar los pasos manuales es clave. Un pedido que la plataforma muestra como “en proceso” puede estar en la cola de tareas de alguien dentro del ERP, y ningún reintento lo moverá. La interfaz y las alertas deben distinguir “estamos esperando al ERP” de “el envío falló”; si no, operaciones llevará ambos tipos de problema a los desarrolladores.
2.0 Envíos que se puedan reintentar sin riesgo
El caso difícil son los timeouts: la petición puede haber llegado o no. Si el ERP crea un segundo documento al reintentar, hay un pedido duplicado.
- Cada documento lleva una clave de negocio estable, normalmente el número de pedido de la plataforma, y el ERP deduplica con ella. Si el ERP no puede deduplicar, se consulta si el documento ya existe antes de enviarlo.
- Los datos maestros de los que se depende van primero: un cliente nuevo se da de alta antes que su pedido. Si una dependencia no está lista, el documento espera en una cola local en lugar de forzarse.
- Que los códigos no coincidan es lo normal, no la excepción. Acuerde por escrito qué se envía cuando un producto o cliente aún no existe en el ERP y qué lado completa el hueco.
- Los errores del ERP suelen esconderse dentro de una respuesta HTTP 200. Un único cliente reconoce esa semántica de error para que cada punto de llamada no la interprete a su manera.
3.0 El estado se obtiene consultando
La respuesta a un envío solo indica que el ERP recibió el documento. Los estados posteriores llegan mediante una consulta programada:
| Punto de diseño | Nuestra elección |
|---|---|
| Recorrido | Paginación por conjunto de claves sobre la clave primaria, no OFFSET; estable al crecer el volumen y sin saltarse filas entre páginas |
| Orden | Un cursor que avanza en bucle y retoma donde se detuvo la última ejecución, para no reintentar siempre el mismo lote de fallos |
| Espera creciente | Los documentos que fallan una y otra vez se consultan con menos frecuencia, hasta un tope; superado el tope pasan a una persona |
| Concurrencia | Un documento solo lo procesa un trabajador a la vez, garantizado con un bloqueo de fila o una concesión temporal |
4.0 El log de sincronización es donde empieza el diagnóstico
Cada llamada escribe una fila: número de documento, acción, resumen de la petición, código de resultado, mensaje del ERP, duración y número de intento. Contraseñas, tokens y datos personales completos quedan fuera.
Con esa tabla, “¿por qué no se ha enviado este pedido?” empieza con una consulta y no rebuscando en los logs de la aplicación o pidiendo capturas al equipo del ERP. También mantenemos un manual de diagnóstico: cada problema nuevo resuelto queda con su síntoma, causa raíz, solución y las consultas de diagnóstico, con la entrada más reciente arriba. Los problemas de integración con ERP suelen volver con otra forma, y ese manual acaba siendo más útil que cualquier panel.
5.0 Conciliación
Aunque cada paso sea correcto, los dos lados se van separando: alguien edita o cancela un pedido directamente en el ERP, o el resultado de una consulta nunca se guardó. Una conciliación diaria compara estados, importes y facturas y pone las diferencias en una lista para una persona. Nunca “corrige” ninguno de los dos lados automáticamente; su resultado es una lista de trabajo.
6.0 Desarrollo y pruebas
- El adaptador del ERP es una interfaz con una implementación simulada para el trabajo local y la CI, de modo que todo el ciclo de vida del pedido, facturación incluida, funciona sin conexión.
- Los entornos de prueba del ERP suelen diferir de producción o directamente no existen. Durante las pruebas de integración, guarde anonimizadas las peticiones y respuestas reales de cada endpoint y úselas como casos de regresión.
- Concilie con más frecuencia las primeras semanas tras la puesta en producción para sacar a la luz casos que el entorno de pruebas nunca mostró.
Si va a conectar un sistema de pedidos a un ERP, o una integración existente se rompe a menudo, consulte Web, nube y gestión de dispositivos o hable de un proyecto con nosotros.
Referencias
- Stripe, peticiones idempotentes: https://docs.stripe.com/api/idempotent_requests
- Use The Index, Luke, paginación por conjunto de claves: https://use-the-index-luke.com/no-offset
Preguntas frecuentes
El ERP solo expone vistas de base de datos, no una API. ¿Podemos integrarlo?
Las vistas de solo lectura sirven para traer productos y existencias. Escribir documentos directamente en la base de datos del ERP es arriesgado: se salta las validaciones del propio ERP y deja poco claro quién es responsable cuando algo falla. Las escrituras deben pasar por la API o la función de importación del ERP, y el límite de lectura y escritura hay que acordarlo antes con el implantador del ERP.
¿Con qué frecuencia conviene sincronizar las existencias?
Depende de lo que cueste vender sin stock y de la carga que aguante el ERP. Volver a comprobar las existencias en tiempo real al confirmar el pedido suele ser más fiable que subir mucho la frecuencia de la sincronización programada, y castiga menos al ERP.
La revisión en el ERP es lenta y los clientes ven siempre 'en proceso'. ¿Qué hacemos?
Muestre con honestidad dónde espera el pedido, por ejemplo 'pendiente de revisión en el ERP', junto con el plazo acordado con el negocio. La plataforma no puede hacer la revisión por el equipo del ERP, pero sí hacer visible la espera y avisar automáticamente al responsable cuando se supera el plazo.
Si cambiamos de ERP más adelante, ¿hay que reescribir la plataforma?
Si el código de integración está en un único adaptador, cambiar de ERP consiste sobre todo en reescribir ese adaptador, rehacer las correspondencias de códigos y probar de extremo a extremo. Si el código de negocio llama a la API del ERP por todas partes, el cambio es mucho mayor; por eso construimos la capa de adaptación desde el principio.