Escribimos
Integrar dos sistemas que no se conocen
Una integración se juega en los acuerdos, no en el código: quién manda sobre cada dato y qué se hace cuando el otro lado no contesta.
Los tres acuerdos que van antes del código
Integrar dos sistemas es acordar por escrito qué datos viajan, quién manda sobre cada uno y qué ocurre cuando el otro lado no contesta. Escribir el código que hace la llamada es la parte pequeña, y casi nunca es la que se rompe seis meses después.
El contrato. Qué campos se mandan, con qué nombre y qué tipo, qué se devuelve cuando sale bien y qué se devuelve cuando sale mal. Eso es lo que define una API. Da igual si el otro lado la publica documentada o si es un sistema interno antiguo al que hay que preguntarle probando: el contrato existe siempre. La diferencia es si está escrito o si vive en la cabeza de alguien.
Quién es dueño del dato. Por cada cosa que viaja hay que decidir cuál de los dos sistemas la escribe y cuál solo la lee. Un cliente puede cambiar su correo en dos sitios; si los dos lo escriben, tarde o temprano habrá dos correos distintos y ninguna regla para elegir. Lo decidimos por campo y no por entidad: el precio lo manda el catálogo y el estado del pedido lo manda el sistema de cobro. Va escrito en una tabla que el cliente puede leer.
Qué pasa cuando uno cae o cambia. El otro sistema se caerá alguna vez, y puede cambiar un campo sin avisarte. La pregunta que hay que responder antes de empezar es qué debe ver el usuario mientras tanto, y si la operación puede esperar o tiene que rechazarse en ese momento.
Lo que se rompe siempre
| Qué se rompe | Cómo se manifiesta | Qué hay que decidir antes |
|---|---|---|
| Reintentos | Falla la red a mitad, el sistema lo vuelve a intentar y la operación se ejecuta dos veces | Cada operación lleva una clave propia y el receptor la ignora si ya la vio |
| Duplicados | El mismo cliente entra dos veces con el correo escrito distinto | Qué campo identifica de verdad a una entidad, y qué se hace cuando no coincide |
| Fechas | Una publicación programada sale con horas de diferencia | En qué zona horaria se guarda, y quién convierte: el que manda o el que recibe |
| Límites de peticiones | Funciona en pruebas con diez registros y se corta con dos mil | Cuántas llamadas por minuto admite el otro lado y qué se hace al llegar al tope |
| Credenciales | Deja de funcionar sin aviso y nadie sabe por qué | Dónde se guardan, cuándo caducan y quién recibe el aviso antes de que caduquen |
Los reintentos merecen un párrafo aparte porque están detrás de buena parte de lo que luego se llama «datos corruptos». Un sistema que reintenta se comporta bien. El problema aparece cuando el receptor no sabe distinguir el segundo intento del primero, y cobra dos veces, o crea dos pedidos. La solución cuesta poco al principio y cuesta un proyecto si hay que meterla cuando ya hay duplicados en producción.
Con los webhooks pasa lo mismo y peor, porque ahí no controlas tú cuándo llega el mensaje. Pueden llegar desordenados, repetidos o con retraso, cuando el pedido ya se dio por perdido. Un receptor que no guarda qué eventos ha procesado acaba duplicando trabajo o perdiéndolo.
Los nombres de los campos son parte de la integración
Quien configura una integración no lee tu documentación interna. Lee los nombres de los campos, el orden en que aparecen y el mensaje que sale cuando algo no se puede hacer. Si esos tres se deciden al final, acabas enseñando los nombres internos del otro sistema y el error literal que devolvió su servidor.
Los estados intermedios son el otro sitio donde se nota. Una integración que responde al momento y otra que tarda son el mismo código y dos productos distintos: en la segunda hay que decidir si el usuario espera, si se va y recibe un aviso, o si el trabajo queda en una cola visible.
Zernio: la integración vive en el flujo del cliente
Zernio es una plataforma desde la que las marcas programan lo que publican en redes. Sus clientes ya automatizaban buena parte de su trabajo con flujos de n8n, y el último paso, programar la publicación, seguían haciéndolo a mano en otra herramienta.
Construimos el nodo de n8n con el que un cliente de Zernio crea y programa publicaciones desde su propio flujo, con sus credenciales. Está publicado en el catálogo público de n8n y el código es abierto, con lo que cualquiera puede comprobar que existe sin pedirnos permiso.
La decisión del encargo fue que la integración viviera donde ya trabaja el cliente, en lugar de pedirle que entrara en la herramienta de Zernio. Y que las credenciales sean del cliente y no pasen por nosotros, que es lo razonable cuando la integración la instala un tercero en su propia máquina.
Por dónde empezar si tienes una integración pendiente
Antes de pedir presupuesto, escribe dos cosas en un folio. La lista de datos que van a viajar y quién manda sobre cada uno. Y qué tiene que ver el usuario cuando el otro sistema no responde. Con esas dos respuestas, la conversación con cualquier proveedor pasa a ser sobre qué hace el sistema en el peor día.
Si no están claras y el sistema ya está en producción con clientes dentro, ese es el trabajo del diagnóstico.
Ver también
¿Te está pasando en tu propio sistema?
El diagnóstico le pone número y orden sobre tu propio código.