Revisado el 30 de septiembre de 2026. Guion de evaluación para responsables de integraciones.
¿Por qué aparecen pedidos duplicados en una integración?
Un sistema puede reenviar una operación porque no recibió respuesta, aunque el destino ya la hubiera guardado. También puede entregar el mismo evento varias veces. La integración debe reconocer una operación repetida y tratarla sin crear otro pedido. A esto se le llama idempotencia y hay que diseñarlo y probarlo.
Tener una API disponible no resuelve por sí solo los reintentos. Frappe genera una API REST para sus DocTypes, pero el contrato entre sistemas debe definir qué representa una operación, cómo se identifica y cómo se comprueba el resultado si se pierde la respuesta.
Para endpoints, autenticación y ejemplos básicos, consulta la guía de API REST y webhooks de ERPNext. Aquí nos centramos en comprobar la fiabilidad del intercambio.
Elegir una identidad que no cambie al reintentar
Define una identidad estable antes de enviar el primer mensaje. Para crear un pedido, puede combinar sistema de origen, empresa o cuenta y número de pedido externo. Esa identidad debe seguir siendo la misma al repetir la creación. Si llega una modificación posterior, hay que distinguirla de un reintento de la operación anterior.
Ejemplo didáctico: tienda A envía el pedido 4821, ERPNext lo guarda y la conexión se corta antes de responder. La tienda lo reenvía. El resultado correcto es localizar el pedido ya creado y devolver su referencia, no crear uno nuevo. Este escenario permite evaluar el conector; no describe un caso de cliente.
Pide que el implementador explique dónde se conserva la relación entre identificador externo y documento ERPNext. Pregunta también qué ocurre si dos mensajes idénticos llegan al mismo tiempo. Consultar primero y crear después puede duplicar datos si ambos procesos consultan antes de que alguno guarde.
Guion de pruebas antes de conectar producción
Una prueba útil fuerza fallos, además de comprobar un envío correcto. Debe dejar evidencia del mensaje recibido, la operación realizada y el documento resultante. El responsable del negocio debe poder conciliar pedidos y estados sin necesitar interpretar todos los registros técnicos ni contar mensajes como si fueran ventas.
| Escenario | Qué provocar | Resultado que debes exigir |
|---|---|---|
| Envío correcto | Un pedido válido | Un documento y referencia trazable |
| Mensaje repetido | Reenviar la misma creación | El mismo documento, sin duplicado |
| Respuesta perdida | Cortar la respuesta después de guardar | Recuperación del resultado existente |
| Llegada simultánea | Dos creaciones con igual identidad | Una única creación o conflicto controlado |
| Error de datos | Artículo inexistente o dato inválido | Error visible, sin documento incompleto |
| Cambio posterior | Modificar un pedido ya recibido | Regla de actualización documentada |
| Servicio indisponible | Interrumpir el destino temporalmente | Reintentos limitados y cola observable |
| Evento desordenado | Entregar una cancelación antes de crear | Tratamiento explícito y conciliable |
La comprobación de identidad y la creación deben coordinarse de forma que la concurrencia no abra una segunda creación. La solución concreta depende del conector y su almacenamiento: pide evidencia de esa garantía, no solo una captura de dos envíos manuales separados.
Reintentar sin ocultar los errores
Distingue un fallo temporal de un dato que necesita corregirse. Una caída de red puede justificar un reintento; un artículo inexistente no se arregla repitiendo el mensaje indefinidamente. Define límites, avisos y responsables para los mensajes pendientes. Cuando el resultado sea incierto, compruébalo antes de crear otra vez.
El registro de integración debería permitir seguir la identidad externa, destino, estado, número de intentos y último error. Evita guardar secretos y datos personales innecesarios en los registros. Para soporte, suele ser más útil una referencia trazable que copiar íntegramente cada pedido en múltiples archivos.
La documentación de Frappe explica que las llamadas con token se asocian al usuario y sus roles. Usa una cuenta dedicada con los permisos necesarios, revisa el acceso al entregar el conector y acuerda cómo rotar credenciales sin interrumpir la operación.
Conciliar: comprobar lo que realmente llegó
Compara operaciones de origen y destino en un periodo y revisa las pendientes y excepciones. No uses el número de intentos como número de pedidos: una operación puede generar varios mensajes. Incluye importes, moneda y estado cuando sean relevantes para el proceso; contar documentos iguales no basta para validar una sincronización.
Acuerda quién revisa esa conciliación, con qué frecuencia y cómo corrige diferencias. La entrega debe incluir una prueba con mensajes repetidos y una incidencia recuperada. Si cambia la versión o el comportamiento de una app, repite las pruebas afectadas: consulta la guía de personalizaciones y actualizaciones.
Preguntas frecuentes
¿Un webhook garantiza que ERPNext recibirá el evento una sola vez?
No conviene asumirlo. El contrato del emisor y del receptor debe contemplar entregas repetidas y respuestas perdidas. La integración tiene que reconocer qué operación ya procesó y comprobar el resultado antes de repetir una creación.
¿Basta con buscar el pedido antes de crearlo?
No siempre. Dos procesos simultáneos pueden buscar a la vez y no encontrarlo todavía. Hay que coordinar la comprobación y la creación con una garantía de unicidad o un mecanismo equivalente, y probar el comportamiento bajo concurrencia.
¿Hay que reintentar todos los errores de la API?
No. Distingue problemas temporales, datos inválidos y resultados inciertos. Define reintentos limitados y una cola de excepciones con un responsable; repetir indefinidamente puede ocultar un problema o producir efectos duplicados.
Sobre el autor
Lleva desde 2014 implantando ERPNext y desarrollando sobre Frappe Framework, que es lo único a lo que se dedica CodigoNext: ni una línea de negocio con otro ERP. Ha construido el módulo VeriFactu de la casa y trabaja el día a día de pymes españolas y de proyectos en Latinoamérica. Escribe aquí lo que se encuentra en los proyectos, incluido lo que no funciona y lo que no compensa. Conoce al equipo.
CodigoNext trabaja exclusivamente con ERPNext y Frappe desde 2014. Para España y Latinoamérica, diseñamos integraciones y desarrollo con alcance y pruebas acordadas. Si cambias de mantenedor, incluye estas comprobaciones en el traspaso de proveedor.