Desarrollo de interfaces API: conectar sistemas sin que los datos se desincronicen

Un lunes por la mañana en una empresa con tres sistemas: en el programa de pedidos figura un cliente con la nueva dirección de entrega, en la contabilidad todavía con la antigua, y en la tienda online aparece dos veces porque una vez se registró con otra dirección de correo. Nadie ha cometido un error. Cada sistema era correcto por sí mismo, y justamente ese es el problema.

En este escenario suponemos un proveedor de servicios de tamaño medio que ha ido adquiriendo software especializado a lo largo de los años. Cada programa tiene una función de exportación, algunos tienen una API, y uno solo entrega archivos CSV por correo. Entre los sistemas trabaja una persona que abre archivos, mueve columnas y copia valores. Eso funciona mientras esa persona esté y el orden de las columnas no cambie.

Por eso, quien encarga una interfaz no compra una conexión, sino un comportamiento: ¿qué ocurre si el mismo pedido llega dos veces, si el sistema de destino no responde en ese momento o si alguien cambia el nombre de un campo? Las respuestas a estas preguntas determinan si la integración se sostiene. Que dos programas puedan intercambiar datos es la mitad fácil de la tarea.

A ello se suma que el intercambio manual oculta conocimiento. La persona que está entre los sistemas sabe que ciertos clientes nunca deben crearse automáticamente, que una columna a veces contiene comentarios en lugar de cifras y que la exportación tarda más a fin de mes. Este conocimiento de la experiencia no figura en ninguna documentación. Quien no lo pregunta al automatizar construye una interfaz que trata mal justo esos casos especiales.

La mayoría de los problemas de interfaz parecen al principio fruto del azar. Falta un pedido en el sistema de destino, otro está duplicado, un acceso falla el lunes y el martes no. Detrás de estos síntomas hay unas pocas causas recurrentes, y pueden nombrarse antes de escribir la primera línea de código.

La primera es el tiempo. Las credenciales caducan, los tokens se renuevan, los certificados pierden su validez. La segunda es el volumen: los sistemas de terceros limitan las consultas por minuto y, al superarse el límite, suelen responder con el código de estado 429. La tercera es el significado: el campo “estado” se llama igual en ambos sistemas, pero admite valores distintos. La cuarta es el cambio, pues el proveedor de la API de terceros actualiza su software sin conocer su plan de mantenimiento.

Además, las redes no son fiables. Una llamada puede llegar al destinatario, procesarse, y la confirmación perderse por el camino. El remitente ve un tiempo de espera agotado y lo repite. Sin precauciones, esto produce justo el pedido duplicado que nadie sabe explicar. Este patrón no es una excepción, sino un caso normal en los sistemas distribuidos.

Una quinta causa se subestima a menudo: la transferencia parcial silenciosa. Una conciliación procesa 400 de 500 registros, se interrumpe ante una entrada defectuosa y no notifica nada, porque el proceso terminó formalmente. Al día siguiente faltan 100 registros y nadie sabe cuáles. Que una integración aísle los errores individuales o interrumpa toda la ejecución es, por tanto, una decisión de diseño deliberada.

Antes de hablar de REST o de webhooks, hay una cuestión de responsabilidad: ¿qué sistema es la fuente principal de cada dato? Si las direcciones de clientes pueden editarse tanto en el programa de pedidos como en la contabilidad, cada sincronización es una disputa que un algoritmo no puede resolver. Con una titularidad clara de los datos, una conciliación bidireccional suele convertirse en un flujo unidireccional con excepciones definidas.

El segundo análisis se refiere al desencadenante. ¿Debe el sistema de destino saber de inmediato lo que ha ocurrido, o basta una conciliación cada pocas horas? De inmediato significa webhooks o eventos. Periódicamente significa consulta por fecha de modificación. Ambas cosas tienen costes. Los webhooks entregan rápido, pero a veces no llegan, llegan dos veces o en orden equivocado. Las consultas son lentas, pero más fáciles de reparar, porque en cualquier momento se puede preguntar qué ha cambiado desde ayer.

En tercer lugar se examina la forma de interfaz del sistema de terceros. Una API REST bien documentada con sandbox es la situación cómoda. Más a menudo hay una API a medio terminar que no refleja todos los campos, o solo una importación de archivos CSV o XML. Entonces la interfaz de archivos no es una solución de emergencia, sino un formato que puede hacerse robusto con sumas de verificación, nombres de archivo fijos y archivos de acuse de recibo.

Por último, la cuestión del daño pertenece al análisis: ¿qué cuesta que una transferencia falle una hora, un día o una semana? Un contacto de boletín que llega tarde es asumible; la falta de una autorización para una entrega, no. De la respuesta se deduce cuánto esfuerzo en supervisión y reinicio está justificado.

El camino tentador es la conexión punto a punto: el sistema A llama directamente al sistema B. Con dos sistemas es defendible. Con cinco sistemas surgen hasta diez conexiones, cada una con sus propios formatos, su propio tratamiento de errores y sus propias credenciales. Cada cambio en un sistema afecta a varios puntos. Por eso propondríamos una capa central de integración a partir del tercer sistema conectado.

Esta capa es discreta: un pequeño servicio que recibe datos, los traduce a un modelo interno, los deposita en una cola y los distribuye a los sistemas de destino. Reúne en un solo lugar las credenciales, los registros y la lógica de reintentos. El precio es un componente adicional que alguien tiene que mantener en funcionamiento. Con dos sistemas y interfaces estables sería excesivo, y lo diríamos.

Una alternativa son las plataformas de integración ya hechas y las herramientas sin código. Se configuran rápido y cubren bien los casos estándar, como “nueva consulta en el formulario, nueva entrada en el CRM”. Su límite está donde los datos deben convertirse, conciliarse o reintentarse de forma selectiva ante errores, y en la dependencia del proveedor. Para flujos sencillos es una opción honesta; para procesos de los que dependen la facturación o la entrega, lo sopesamos con más cuidado.

Hay una idea decisiva: la integración forma parte del software, no va al margen. Tiene versiones, pruebas, supervisión y un responsable. Quien la trata como un subproducto acaba con un script que algún día un empleado ya no se atreve a modificar.

El paso central del diseño es el modelo de datos entre los sistemas. Para cada entidad, como cliente, pedido o artículo, establecemos qué campos existen, cuáles son obligatorios, qué valores se admiten y qué sistema es el responsable. A ello pertenece una tabla de correspondencias: ¿cómo se convierte el valor “abierto” de un sistema en el valor “en curso” del otro? Estas tablas parecen banales, pero aclaran las cuestiones que después cuestan semanas.

Un identificador estable es especialmente importante. Cuando dos sistemas se refieren al mismo cliente, necesitan una clave conocida por ambos. Los nombres y las direcciones de correo no sirven bien, porque cambian. Lo habitual es que la integración almacene el identificador del sistema de terceros junto al propio. Sin una clave así, solo queda una conciliación difusa por similitud, que genera asignaciones erróneas que se notan al emitir la factura.

Otros detalles son discretos y traicioneros: zonas horarias y marcas de tiempo, separadores decimales, redondeo de importes, juegos de caracteres para las diéresis y tildes, valores vacíos frente a campos no enviados. Un campo que no se transfiere puede significar “sin cambios” o “borrado”. Esta distinción debe definirse expresamente; de lo contrario, una actualización sobrescribe registros completos con huecos.

El modelo se describe como un esquema, por ejemplo con JSON Schema, y cada mensaje entrante se valida frente a él. Los mensajes no válidos no acaban silenciosamente en el destino, sino en una lista que una persona puede ver. Así, una cuestión de calidad de datos se convierte en un proceso visible.

Empecemos por el acceso. Las API de terceros suelen exigir una clave de API u OAuth 2.0 con tokens de acceso de corta duración y un token de renovación. Las claves nunca van en el código fuente, sino en un almacén protegido del servidor, y solo reciben los permisos que la integración necesita. Cuando un token caduca, el servicio debe renovarlo por sí mismo y registrar el evento. Un aviso en el calendario para la caducidad de un certificado no es ningún lujo.

En los webhooks rige esta regla: confirmar rápido, procesar después. El receptor comprueba la firma del mensaje, lo coloca en la cola y responde de inmediato con éxito. El procesamiento propiamente dicho se ejecuta por separado. Así, un sistema de destino lento no bloquea al emisor, y un mensaje no se pierde solo porque el procesamiento fallara. Como los emisores repiten sus mensajes si hay un fallo, el receptor debe tolerar duplicados.

Aquí entra en juego la idempotencia. Una operación es idempotente si ejecutarla varias veces da el mismo resultado que ejecutarla una sola vez. En la práctica, el emisor genera un identificador único para cada transferencia y el receptor recuerda cuáles ha procesado ya. Si el mismo identificador llega de nuevo, se confirma, pero no se vuelve a ejecutar. Algunas API ofrecen para ello una clave de idempotencia en la cabecera de la petición; donde no existe, la comprobación se construye uno mismo.

Ante los errores, la integración distingue dos clases. Los errores transitorios, como tiempos de espera agotados, errores del servidor y el código de estado 429, se reintentan, con intervalos crecientes y algo de aleatoriedad para que muchos reintentos no lleguen a la vez. Los errores permanentes, como datos no válidos o falta de autorización, no se reintentan, sino que se aparcan y se notifican. Quien repite todo a ciegas sobrecarga el sistema ajeno y oculta la causa real.

Por último llega el acuse: solo cuando el sistema de destino confirma el éxito y devuelve un identificador propio se considera completada la transferencia. Ese identificador se guarda y vincula de forma permanente ambos registros.

En los proyectos de integración, los casos especiales son la norma. El primero es el procesamiento de recuperación: tras una caída de un día, deben transferirse los datos pendientes, y la API de terceros permite solo un número limitado de consultas por minuto. Aquí ayuda un limitador de tasa en el propio servicio, que reparte las llamadas de manera uniforme, evalúa las cabeceras de respuesta de la API y respeta el tiempo de espera indicado ante un 429. Una recuperación no debe desplazar el funcionamiento normal.

El segundo caso especial es el orden. Los webhooks pueden llegar desordenados: el cambio «pedido cancelado» llega antes que «pedido creado». El servicio debe o bien reconocer el orden mediante un contador de versión o una marca de tiempo y descartar los mensajes más antiguos, o bien consultar directamente al emisor el estado actual al recibir el mensaje. Lo segundo es más robusto, pero más costoso en número de llamadas.

En tercer lugar, el control de versiones de la API de terceros. Los proveedores serios mantienen versiones y anuncian el fin de las antiguas. Por eso la integración fija expresamente la versión utilizada en lugar de fiarse de una versión por defecto, y lee los avisos de obsolescencia en las cabeceras de respuesta y en los comunicados de cambios. También es importante la tolerancia al leer: campos nuevos y desconocidos en una respuesta no deben provocar un fallo. En cambio, si faltan campos obligatorios, la integración debe fallar de forma ruidosa en lugar de escribir en silencio datos erróneos.

En cuarto lugar, la conexión de sistemas heredados que no tienen ni API ni webhooks. Un sistema de laboratorio o un ERP antiguo quizá entrega cada noche un archivo en un directorio. Esto también se puede resolver bien: los archivos solo se procesan cuando existe una marca de finalización, cada línea recibe un identificador y un archivo de acuse devuelve lo que se aceptó. Estas conexiones no deben considerarse de segunda categoría, sino una interfaz lenta pero fácilmente verificable.

El beneficio de una integración se nota allí donde hasta ahora las personas hacían de puente de datos. Menos copiar a mano significa menos errores de tecleo, transmisión más rápida y tiempo liberado. En este estudio no damos cifras, porque dependen de su situación de partida: ¿cuántos registros circulan al día, con qué frecuencia surgen errores, cuánto tarda la corrección? Estas magnitudes deben medirse antes del proyecto; de lo contrario, después faltará la comparación.

El éxito se puede medir con pocos indicadores: proporción de mensajes transferidos con éxito, número y antigüedad de los casos aparcados, tiempo desde el evento hasta la llegada al sistema de destino, diferencias de conciliación en una muestra periódica y horas de retrabajo al mes. Un panel con estos valores impresiona menos que un diagrama de arquitectura, pero resulta más útil en la operación.

Igual de importante es el límite de la promesa. Una integración solo puede ser tan fiable como el más débil de los sistemas conectados. Si la API de terceros se cae durante un día, no lo compensará, pero recuperará los datos en cuanto el sistema vuelva. Tampoco desaparecen los defectos de calidad de los datos de origen. Una interfaz hace visibles los errores y transmite rápido los datos malos si no se corrigen en el origen.

Lo realista es, por tanto, aspirar a que las transferencias sean trazables, a que los errores se notifiquen en lugar de tragarse y a que una caída no provoque pérdida de datos. Es menos que «funciona siempre», pero bastante más de lo que ofrecen muchos scripts crecidos sin control.

Se prueba primero contra la sandbox del proveedor externo, si existe. Permite provocar casos de error sin riesgo: datos no válidos, tokens caducados, límites alcanzados. Donde no hay sandbox, ayuda una réplica propia de la API de terceros como servicio de pruebas sencillo que devuelve respuestas grabadas. No sustituye a la prueba real, pero permite verificar de forma automatizada la lógica de reintentos y la idempotencia. Los datos de producción no pertenecen a las pruebas.

La observabilidad en la operación es tan importante como el código. Cada transferencia recibe un identificador de correlación que aparece en todas las entradas del registro, de modo que se puede seguir el recorrido de un registro. Las alarmas deben avisar de pocos estados, pero significativos: las credenciales caducarán pronto, la cola crece, hay casos aparcados más tiempo del establecido. Una alarma que salta a diario sin consecuencias acaba ignorándose.

La documentación debe estar escrita de modo que una persona sin conocimientos previos pueda operar la integración. Incluye los flujos de datos, el modelo de asignación, el procedimiento en caso de caída, la gestión de las credenciales, el punto de contacto en el proveedor externo y una lista de particularidades conocidas. Estas últimas suelen ser la parte más valiosa, porque recogen lo que no figura en ninguna parte de la documentación oficial.

El mantenimiento no es un apéndice, sino parte del contrato con uno mismo. Las API de terceros cambian, los certificados caducan, las bibliotecas se quedan obsoletas. Un ritmo fijo de actualización de dependencias y una revisión de los comunicados de cambios de los proveedores externos cuestan poco comparados con una reparación de urgencia a fin de mes. Quien encarga solo el desarrollo y deja sin aclarar la operación acabará teniendo el script que nadie se atreve a tocar.

Quien encarga el desarrollo de una interfaz de API no debería preguntar si los datos llegan, sino qué ocurre cuando no llegan. Esta perspectiva separa las integraciones fiables de los scripts que funcionan en el caso normal. Las credenciales, los límites, los reintentos, el control de versiones y la documentación no son servicios adicionales, sino el núcleo del trabajo.

Un siguiente paso razonable es pequeño. Anote, para dos de sus sistemas, cuál manda en clientes, pedidos y artículos, y dónde hoy las personas llevan datos de uno a otro. Solo esta lista suele mostrar qué conexión genera más retrabajo y cuál compensa conectar primero. A menudo no es la más grande, sino la que más errores comete.

Con gusto analizamos juntos su panorama de sistemas y le decimos con claridad dónde tiene sentido un desarrollo propio y dónde basta una herramienta ya hecha. Para el primer flujo indicamos un marco después de haber visto las interfaces externas, no antes. Los compromisos sin esa revisión serían meras conjeturas.

También planificamos con usted el momento del cambio. Un funcionamiento en paralelo, en el que la transferencia antigua y la nueva corren a la vez durante unas semanas y se concilian con regularidad, cuesta algo de esfuerzo, pero genera confianza. Solo cuando las diferencias están explicadas se apaga el puente manual, y la persona que lo ha sostenido hasta ahora sigue implicada como conocedora de los casos especiales.