Laravel y Sage. ¿Pero qué Sage?

Una reunión inicial en la que alguien dice "usamos Sage" ha dicho más o menos lo mismo que "usamos una base de datos". Acota el fabricante y nada más. Los productos que comparten el nombre se construyeron en décadas distintas por empresas distintas, varias de ellas adquiridas, y en el punto en que su aplicación Laravel tiene que hablar con uno de ellos, no tienen casi nada en común.

Esto no es una queja sobre Sage. Es una familia de productos muy amplia que atiende desde un autónomo hasta un fabricante con plantas en cuatro países, y ninguna interfaz única serviría a los dos. Pero significa que la primera hora del proyecto es una pregunta y no un esquema.

La pregunta que lo decide todo

Sage Accounting, el producto para pequeñas empresas, es un servicio alojado con una interfaz REST y OAuth 2. Si eso es lo que usa el cliente, la integración se parece a cualquier otra integración SaaS moderna y el trabajo son las reglas de negocio.

Sage 50 es una aplicación de escritorio con un fichero de datos. Según la edición y la época, la entrada es un controlador o un servicio local que se ejecuta en la máquina que guarda ese fichero. La palabra importante de esa frase es local: aquello que llamaría no está en internet y nunca se pensó para estarlo.

Sage 200 se bifurca. Una edición la aloja Sage y tiene una interfaz publicada. La otra se instala en los servidores del propio cliente, y su interfaz se ejecuta allí, detrás de lo que haga la red del cliente. Esas dos no son la misma integración ni la misma estimación.

Sage Intacct y Sage X3 son productos distintos otra vez, dirigidos a departamentos financieros más grandes, con sus propias interfaces, su propia autenticación y su propio vocabulario para los mismos conceptos contables.

Así que las preguntas que hay que responder antes de comprometer una fecha:

• Qué producto, y qué edición de ese producto.
• Dónde se ejecuta físicamente, y quién administra esa máquina.
• Qué versión, porque a lo largo de las versiones se han añadido y retirado interfaces.
• Quién en el cliente puede conceder el acceso, y cuánto tarda su aprobación.

Esa última no es una pregunta técnica y con frecuencia es la línea más larga del plan.

Cuando no hay nada en internet a lo que llamar

Pongamos Sage 50 en un servidor de la oficina del cliente, o Sage 200 en su propia infraestructura. Su aplicación Laravel está en un alojamiento con dirección pública. No hay ruta entre las dos, y ninguna librería lo arregla.

Hay tres formas honestas de resolverlo, y son decisiones sobre la infraestructura del cliente tanto como sobre su código.

Un conector que instala el cliente. Un proceso pequeño dentro de su red, junto a los datos de Sage, que habla hacia fuera con su aplicación por HTTPS. Como es él quien abre la conexión, no hace falta ninguna regla de entrada en el cortafuegos, y eso es lo que lo hace aceptable para la mayoría de departamentos de sistemas. También se convierte en software que usted tiene que versionar, vigilar y mantener en una máquina a la que no puede conectarse.

Una ruta de red privada. Una VPN o un túnel dedicado entre su red y su alojamiento. Más limpio de razonar una vez existe, y existe cuando el equipo de sistemas del cliente tiene tiempo, que es el riesgo. Merece la pena insistir cuando el cliente ya tiene ese acuerdo con otro proveedor.

Intercambio de ficheros. Exportar desde su lado de forma programada, dejarlo donde el producto importa, o leer la exportación que genera. Lo descartan demasiado rápido quienes prefieren las APIs. Es observable, una ejecución fallida deja el fichero ahí, y una persona puede abrirlo y ver qué estaba mal.

Sea cual sea, la consecuencia de diseño es la misma y hay que decírsela al cliente en la primera semana: los datos de su aplicación son una copia con retraso, el retraso depende de que una máquina en su edificio esté encendida, y la interfaz tiene que decirlo en lugar de presentar una cifra vieja como actual.

Todo a la cola, y en serio

Contra Sage Accounting esto es un consejo corriente. Contra una instalación local es la diferencia entre un sistema que funciona y otro que se cae todos los jueves por la tarde, cuando allí corren los informes semanales y el servidor está ocupado.

Una llamada síncrona hacia un sistema así acabará tardando noventa segundos, y si está dentro de una petición web tiene un tiempo agotado, un usuario que ha visto un error y ninguna forma fiable de saber si la escritura llegó. Ponga cada interacción en una cola, déle un tiempo generoso, y haga segura la reintentada: aquí rige la misma realidad de entrega al menos una vez, con el peligro añadido de que el otro lado quizá no pueda decirle si su primer intento funcionó.

Guarde de cada intento la petición, la respuesta y la marca de tiempo, y consérvelo más tiempo del que cree necesitar. Cuando en marzo el equipo financiero pregunte por qué falta una factura de febrero, esa tabla es lo único que responde.

El IVA, y cómo mantenerse al margen

Con clientes británicos esto sale de inmediato, porque Making Tax Digital convirtió la presentación del IVA en algo que se envía desde el software en lugar de teclearse en una web.

El instinto es construir el envío. Normalmente el movimiento correcto es el contrario. Si el negocio lleva su registro de IVA en un producto de Sage compatible, ese producto presenta, y el trabajo de su integración es asegurar que las cifras que le llegan son correctas y llegan antes del plazo. Añadir una segunda vía de presentación crea un problema de conciliación con una administración tributaria al final.

Donde sí pasa a ser su problema es en la forma de los datos que entrega. Devengo frente a fecha de factura, el tratamiento de un abono emitido en un periodo posterior, redondeo por línea frente a redondeo por factura, e inversión del sujeto pasivo en operaciones transfronterizas. Si eso sale mal, el envío es software correcto produciendo una declaración incorrecta.

Qué hacer antes de escribir código

Pida una copia de los datos, o acceso de lectura a una empresa de pruebas. No una especificación ni una captura: los registros reales, con los campos que el personal del cliente ha renombrado y las cuentas de cliente que se crearon en 2011 y nadie ordenó nunca. Todas las estimaciones que salen muy mal se hicieron a partir de una descripción de los datos en lugar de los datos.

Después escriba de qué lado está la verdad para cada entidad, en un documento que firme el equipo financiero y no en uno que solo lean los desarrolladores. Es una página de prosa. También es el único artefacto del proyecto que seguirá importando dentro de dos años, porque el código se reescribe y esa página es contra lo que se comprueba la reescritura.

Si el libro mayor está en Xero y no en Sage, la cuestión del acceso desaparece y otra ocupa su lugar - el ciclo de vida de los tokens, que tiene un fallo capaz de desconectar clientes en silencio. Nuestra página de ingeniería de integraciones explica cómo se acotan los dos tipos de proyecto.