Conectar FileMaker con el ERP: el webhook de SAGE, paso a paso

El dato ya existe. El problema es que está en el sitio equivocado, y alguien lo teclea otra vez.

Es una escena muy habitual en pymes: un sistema de gestión a medida, en FileMaker en nuestro caso, donde ocurre el negocio día a día (pedidos, presupuestos, proyectos), y un ERP contable, SAGE en este proyecto, donde tiene que acabar esa información para la facturación y la contabilidad. Entre los dos, una persona copiando datos de un sistema a otro.

Ese doble tecleo no solo cuesta tiempo. Genera una diferencia silenciosa entre lo que dice el sistema de gestión y lo que dice la contabilidad, y esa diferencia siempre aparece en el peor momento: al cierre de mes, en una auditoría, o cuando un cliente reclama una factura que no cuadra.

Estamos resolviendo esto conectando ambos sistemas con un webhook. La primera fase ya está en marcha, y lo que nos ha costado más trabajo no ha sido la parte técnica de FileMaker ni de SAGE: han sido tres decisiones de arquitectura que hay que tomar antes de escribir una sola línea.

El recorrido, paso a paso

Antes de las decisiones, conviene ver el camino completo de una factura, tal como lo tenemos montado:

1. FileMaker envía la factura a SAGE. Cuando la factura está lista en el sistema de gestión, un script la manda al ERP junto con los datos del cliente que SAGE necesita. Cada envío lleva un identificador propio del albarán, que es la pieza que luego permite reconocer la respuesta.
2. SAGE la registra y asigna lo definitivo. El número de factura, la serie, el ejercicio y la fecha oficiales los pone el ERP, que es quien manda en la contabilidad.
3. SAGE avisa de vuelta con un webhook. La respuesta llega a nuestro servidor de FileMaker a través de la capa que publica los webhooks, y dispara un script de entrada.
4. FileMaker reconoce la factura y la completa. El script busca la factura por ese identificador de albarán y le escribe el número, la serie, el ejercicio y la fecha definitivos, y el estado de Verifactu cuando ya está disponible.

Dos detalles de diseño de ese último paso nos han ahorrado más de un disgusto. El primero: el script solo exige el identificador; todo lo demás lo aplica si viene y no falla si no viene, porque no todas las respuestas traen todos los datos a la vez. El segundo: guarda siempre el mensaje tal cual llegó, en crudo, junto a la factura. Cuando algo no cuadra, lo primero es poder ver exactamente qué nos dijo el otro sistema.

Quién manda cuando el mismo dato vive en dos sitios

Si un mismo dato (un cliente, una línea de pedido, un importe) se puede modificar tanto en el sistema de gestión como en el ERP, tarde o temprano vas a tener una versión distinta en cada sitio. La pregunta no es técnica, es de negocio: ¿cuál de los dos sistemas es la fuente de verdad para ese dato?

En nuestro planteamiento, FileMaker es donde ocurre el negocio y donde se genera el dato por primera vez, así que es FileMaker quien manda: el webhook empuja información hacia SAGE, no al revés. Esa decisión hay que tomarla explícitamente y para cada tipo de dato, no dar por hecho que “ya se sabrá”. Si se deja sin decidir, la integración termina teniendo un comportamiento distinto según quién la usó primero, que es la peor forma de tener una regla de negocio: la que nadie escribió.

Por qué elegimos webhook y no una sincronización periódica

Antes de decidirnos por un webhook, la alternativa obvia era una sincronización por lotes: cada cierto tiempo, un proceso que revisa qué ha cambiado en FileMaker y lo envía a SAGE. Es más sencilla de construir, pero tiene un coste que en este proyecto no era aceptable: el retraso. Con una sincronización periódica, la contabilidad siempre va por detrás de la operación real, y ese desfase es exactamente el tipo de diferencia silenciosa que queríamos eliminar.

Un webhook, en cambio, envía el dato en el momento en que ocurre el hecho que lo genera: se cierra un pedido en FileMaker, y ese mismo evento dispara el envío hacia SAGE. La contabilidad deja de ir por detrás del negocio. La contrapartida es que hay que asumir, desde el diseño, que la comunicación entre los dos sistemas puede fallar en cualquier momento, y ahí es donde entran las tres decisiones que de verdad han llevado el trabajo de esta primera fase.

Qué pasa cuando el webhook falla

Un webhook que se pierde sin que nadie se entere es peor que no tener integración en absoluto, porque genera una confianza falsa: el equipo cree que el dato ya está en SAGE, y no lo está. La sensación de “esto ya se sincroniza solo” es cómoda hasta que deja de ser verdad y nadie se da cuenta a tiempo.

Por eso, antes de dar por buena una integración, la pregunta que nos hacemos no es “¿funciona el día bueno?”, sino “¿qué vemos el día que falla?”. Necesitamos saber que un envío no ha llegado, no descubrirlo semanas después al cuadrar cifras. Esa parte, la de detectar el fallo, es tan importante como la del envío en sí.

Qué pasa si el mismo mensaje llega dos veces

Reintentar un envío que ha fallado es normal, y en cualquier integración por red va a pasar tarde o temprano: una conexión que se corta a mitad, un tiempo de espera agotado, un reintento automático. Lo que no puede pasar es que ese reintento duplique un asiento contable en SAGE.

Eso significa que la integración tiene que poder recibir el mismo mensaje dos veces sin que el resultado cambie: si SAGE ya tiene registrado ese pedido, recibirlo otra vez no debe generar una segunda entrada. Es una propiedad que hay que diseñar desde el principio en cómo se identifica cada envío, no algo que se pueda añadir por encima una vez que el sistema ya está en marcha y ya ha duplicado algo una vez.

Por qué esto es una decisión de arquitectura, no un detalle técnico

Es tentador tratar estos tres puntos (quién manda, qué pasa si falla, qué pasa si se duplica) como detalles de implementación que se resuelven sobre la marcha, ya con el código delante. En nuestra experiencia es al revés: si no se deciden antes, el comportamiento de la integración lo acaba definiendo el orden en que se escribieron las líneas de código, no una decisión consciente de negocio. Y eso es exactamente lo que se quiere evitar cuando el objetivo es que la contabilidad y la operación digan siempre lo mismo.

Por eso la primera fase de este proyecto ha dedicado más tiempo a conversaciones sobre estos tres puntos que a la propia integración técnica entre FileMaker y SAGE. Una vez que las reglas están claras, la parte de código es la parte fácil.

Lo que nos llevamos de esto

Integrar dos sistemas es fácil el día bueno: mandas el dato, llega, se registra. El trabajo de verdad está en los días malos: en decidir quién manda, en saber cuándo algo no ha llegado y en que un reintento no se convierta en un duplicado. Esas tres decisiones, tomadas antes de escribir código, son las que hacen que una integración se pueda dejar funcionando sin mirarla todos los días.

Si te enfrentas a una integración parecida entre tu sistema de gestión y tu ERP, puedes ver cómo encajamos este tipo de proyectos en aplicaciones a medida con FileMaker o en cómo trabajamos.