Ingeniería de integraciones Laravel

Muy pocas aplicaciones están solas. Hay un sistema contable que es dueño de los números de factura, un proveedor de pagos que decide cuándo el dinero es real, un almacén con opiniones sobre el stock, y cada vez más una administración tributaria que exige documentos en forma estructurada.

La integración es donde vive la ingeniería genuinamente difícil de una aplicación de negocio, y casi siempre se subestima, porque el código es directo y todo lo que lo rodea no.

Qué conectamos

Contabilidad y ERP. SAP, Logo, Netsuite, Xero, Sage y lo que una empresa lleve ejecutando desde antes de que llegara nadie de los que trabajan allí hoy. El problema recurrente no es el protocolo: es que los dos sistemas creen ser dueños del mismo registro, y nadie ha decidido cuál gana.

Proveedores de pago. Tarjetas, métodos locales, mandatos de domiciliación, repartos de marketplace. Cada uno tiene su propio modelo de qué es un pago, y las diferencias llegan a la tabla de pedidos en lugar de quedarse en el cliente de la API - Stripe es el ejemplo trabajado, y el resto difiere en los detalles y no en la forma.

Plataformas de facturación electrónica. Cada vez más obligatorias y cada vez más distintas por país: ZATCA, XRechnung, Peppol, y el proveedor acreditado que se sitúa en medio. Una factura pasa a ser un documento asíncrono con una máquina de estados detrás.

Bancos y archivos. Importación de extractos, ficheros de pago, conciliación. Los formatos son viejos, están mal documentados y no perdonan, y el trabajo es de emparejamiento más que de análisis sintáctico.

Todo lo demás. Transportistas, SMS, proveedores de identidad, CRMs, registros públicos.

Las partes que deciden si funciona

Una frontera que es suya. Su aplicación habla con su interfaz; una implementación habla con la API de ellos. Cuesta casi nada construirlo y es lo que convierte cambiar de proveedor en una semana en lugar de un trimestre, lo cual importa más de lo que parece, porque a los proveedores los compran, deprecan versiones y cambian precios.

Idempotencia, porque todo llega dos veces. Los webhooks se reenvían. Los reintentos se disparan tras una petición que en realidad tuvo éxito. Un tiempo de espera agotado no le dice nada sobre si el otro lado procesó algo. Cada escritura que cruza la frontera necesita una clave que haga del segundo intento una operación sin efecto, y esa clave pertenece al esquema y no a las intenciones de un desarrollador.

Una decisión sobre el fallo, por integración. Cuando el sistema de ellos está caído: ¿falla la acción del usuario, se encola, o sigue degradada? Cobrar una tarjeta no es enviar un correo de marketing, y tratarlos igual es la forma de que una caída de un proveedor se convierta en una caída suya.

Límites de petición respetados a propósito. Espera creciente, una cola que reparte el trabajo, y un techo que usted fija en lugar de descubrir. Que le limiten por enviar un año de recuperación de datos en cuatro minutos es un incidente autoinfligido.

Un registro de lo intercambiado. Cada petición y cada respuesta, guardadas el tiempo suficiente para zanjar una discusión. Cuando la otra parte dice que nunca lo recibió, esta es la diferencia entre una respuesta de cinco minutos y una quincena.

La conciliación es el trabajo de verdad

Dos sistemas que guardan los mismos hechos acabarán discrepando. No puede ser: lo harán, porque se pierden mensajes, se introducen correcciones en un lado, y en algún momento alguien edita un registro a mano.

Una integración que supone acuerdo descubre la desviación cuando se queja un cliente. Una integración bien construida comprueba: una tarea programada que compara ambos lados, un informe de diferencias, y una resolución definida para cada tipo. No tiene ningún glamur y es la diferencia entre una conexión en la que confía y otra que tendrá que revisar por muestreo para siempre.

Cómo transcurre un encargo

Mándenos la documentación de la API con la que hay que hablar y, si existe, credenciales de un sandbox. La mayor parte del dimensionado sale de leer lo que la otra parte garantiza de verdad, no lo que dice su página de marketing.

El alcance que vuelve lista cada integración, sus modos de fallo, y qué tendrá que hacer la conciliación al respecto. Lleva un precio y es a lo que apunta el contrato. Si una de las integraciones resulta ser un proyecto de investigación y no un desarrollo, eso figura como línea aparte en el alcance en vez de como sorpresa en el segundo mes.

Después el trabajo, en su repositorio, con la conciliación construida a la vez que el camino feliz.

Qué recibe

La integración como pull requests revisables, la interfaz que aísla al proveedor, el comportamiento de cola y reintentos con sus decisiones de fallo escritas, la tarea de conciliación y su informe, y un documento que describe qué se intercambia y qué pasa cuando no.

Cuando el trabajo toca facturación o declaración fiscal en un país concreto, las restricciones de ese mercado forman parte del alcance en lugar de ser un descubrimiento. Lo que cambia en cada uno está descrito en detalle en las páginas de mercado, en inglés.