n8n

n8n es un motor de automatización que corres tú mismo. De un lado está AppBO, al que se llega por su API REST y sus webhooks. Del otro está lo que viva en tu entorno: una base de datos interna, una carpeta compartida, una aplicación de negocio en una red privada, un almacén de datos para reportes, además del mismo catálogo de SaaS públicos al que llega cualquier plataforma de automatización. La diferencia que lo define es dónde corre el motor: en tu infraestructura, dentro del perímetro de tu red, con las credenciales guardadas en tu instancia y no en la de un proveedor.

Esa es la razón para elegirlo. Si tu restricción es regulatoria, contractual o simplemente una revisión de seguridad que no va a aprobar que los datos de clientes pasen por un proveedor de automatización externo, un motor autoalojado elimina la pregunta por completo. Los datos de AppBO llegan a un host que controlas, se transforman en ese host y se escriben en un destino que controlas. También es la respuesta correcta cuando la integración necesita llegar a algo que no tiene un endpoint público (un sistema de gestión de la clínica en una subred privada, una base de datos detrás de un firewall), porque el motor ya está adentro con él.

El costo es que la plataforma es tuya. La disponibilidad, las actualizaciones, los certificados TLS, los respaldos, los workers de la cola, el almacenamiento de secretos y la capacidad ahora son tu responsabilidad, y un motor que se cae a las dos de la mañana no le avisa a ningún proveedor. n8n también te da un nodo Code, que es a la vez su mejor función y el lugar donde se acumula la lógica de negocio sin documentar. Trata una instancia de n8n en producción como un servicio que operas, con el monitoreo y el control de cambios que eso implica.

1. Monta la instancia bien antes de construir nada: una base de datos persistente en lugar del almacenamiento en archivo por defecto, un volumen duradero, TLS en un hostname al que tu equipo pueda llegar y autenticación en la interfaz del editor. Un editor de n8n expuesto sin autenticación es un almacén de credenciales abierto a internet.
2. Decide cómo va a recibir webhooks la instancia. Configura la URL pública de webhooks para que las URL de webhook generadas sean las que se pueden alcanzar desde afuera, y abre solo esa ruta en tu ingress. Si esto sale mal, obtienes URL de webhook que se ven bien y a las que no se puede llegar.
3. Configura el modo de cola con workers separados si esperas cualquier volumen real. El modo por defecto de un solo proceso va a poner tus ejecuciones en fila una tras otra y se va a convertir en el cuello de botella.
4. Crea la credencial de AppBO en n8n. Usa una credencial de app OAuth donde el nodo lo permita; si no, configura una credencial de autenticación por encabezado con el bearer token, junto con el encabezado de versión de la API que indica la referencia. Guárdala como credencial de n8n, nunca escrita directamente en un nodo.
5. Confirma que la credencial funciona corriendo un solo nodo de lectura (traer un contacto o listar los calendarios) y revisando que el identificador de cuenta que regresa sea el de la cuenta que querías.
6. Elige cómo arranca el flujo de trabajo. Para flujos que inicia la plataforma, agrega un nodo Webhook y registra su URL como webhook saliente o como paso de webhook en un flujo de AppBO. Para trabajo programado, usa un disparador Schedule y lee desde la API.
7. Asegura el nodo Webhook. Agrégale autenticación por encabezado y haz que AppBO envíe el encabezado con el secreto correspondiente. Un webhook de n8n sin autenticación es un endpoint público que va a ejecutar tu flujo de trabajo para cualquiera que lo encuentre.
8. Captura datos reales: activa el flujo de trabajo, envía un evento real y fija (pin) los datos resultantes en el nodo Webhook para que puedas seguir construyendo sin volver a enviar eventos.
9. Arma la transformación con nodos Set e IF antes que con un nodo Code. Reserva el nodo Code para lógica de verdad, y coméntalo, porque va a durar más que quien lo escribió.
10. Agrega un nodo de búsqueda antes de cualquier nodo de creación, con una clave basada en un identificador estable, y separa los casos de encontrado y no encontrado con un nodo IF.
11. Configura el manejo de errores de forma explícita: activa el reintento en caso de falla con un intervalo razonable en los nodos que llaman a servicios inestables, decide nodo por nodo si se continúa cuando hay una falla y configura un flujo de error en los ajustes del flujo de trabajo para que las fallas se reporten y no solo queden en el registro.
12. Devuelve la respuesta correcta desde el nodo Webhook y devuélvela rápido. Usa la opción de responder de inmediato y haz el trabajo después de responder, para que la plataforma no se quede esperando a que termine todo tu flujo.
13. Verifica la conexión de principio a fin: dispara un evento real en AppBO, mira cómo aparece la ejecución en n8n, confirma la rama que tomó y confirma que el registro de destino es correcto.
14. Prueba los modos de falla con los que de verdad te vas a topar: detén el sistema de destino y confirma que el reintento y el flujo de error se comportan bien; reinicia n8n a mitad de una ejecución y confirma que sabes qué pasa con el trabajo en curso.
15. Pon la instancia bajo monitoreo: que el proceso esté vivo, la profundidad de la cola, la tasa de ejecuciones fallidas y el uso de disco del historial de ejecuciones, y define una política de retención de datos de ejecución antes de que se llene la base de datos.

De la plataforma a n8n

• Los datos (payload) de los webhooks salientes de AppBO o de los pasos de webhook de los flujos de trabajo, que llegan a un nodo Webhook en tu host.
• Registros que se leen por la API: contactos y campos personalizados, oportunidades, conversaciones, citas, envíos de formularios, usuarios.
• Conjuntos de resultados paginados, que n8n puede recorrer de forma nativa elemento por elemento.

De n8n a la plataforma

• Creación y actualización de contactos, incluidos los valores de campos personalizados.
• Creación de oportunidades y cambios de etapa.
• Notas, tareas y citas.
• Entrada de un contacto a un flujo de trabajo.
• Cualquier otra operación de la API mediante el nodo HTTP Request con la credencial guardada, que es como llegas a los endpoints que ningún nodo dedicado cubre.

Dentro de tu entorno

• Lecturas y escrituras contra bases de datos internas, carpetas compartidas y aplicaciones en redes privadas. Los datos se quedan de tu lado del perímetro todo el tiempo.
• Las credenciales de todo lo anterior, guardadas en el almacén cifrado de credenciales de tu instancia.

Lo que no se mueve

• Nada va a un proveedor de automatización externo. No hay un registro de ejecuciones externo que guarde tus datos.
• Los elementos de los editores de la plataforma: funnels, sitios y el diseño de las plantillas de email.
• El historial de ejecuciones fuera de tu instancia; si lo necesitas en otro lado, envíalo a propósito.
• Las garantías transaccionales entre nodos. Una falla en el nodo nueve no deshace el nodo cuatro.

Escenario: un operador de servicios de salud no puede enviar datos de pacientes a un proveedor de automatización alojado, y tiene que escribir cada cita de AppBO en una base de datos de gestión de la clínica que corre en sus propias instalaciones.

1. n8n corre en una máquina virtual dentro de la red del operador, detrás de su balanceador de carga, con TLS en un hostname interno y la interfaz del editor restringida a la red corporativa. Solo la ruta de webhooks está expuesta hacia afuera.
2. Un flujo de trabajo empieza con un nodo Webhook en una ruta larga y aleatoria, con autenticación por encabezado que exige un secreto que generó el operador.
3. En AppBO, un flujo que se dispara cuando se agenda una cita termina en un paso de webhook que apunta a esa URL, envía el encabezado con el secreto y un cuerpo JSON plano: identificador del evento, identificador del contacto, nombre, campo personalizado de fecha de nacimiento, inicio de la cita, nombre del calendario y profesional asignado.
4. Se hace una reserva real. El nodo Webhook recibe la solicitud, valida el encabezado y responde de inmediato con un estado de éxito para que la plataforma no se quede esperando.
5. Un nodo IF compara el identificador del evento con una tabla de deduplicación en la base de datos local. No se había visto antes, así que la ejecución sigue por la rama verdadera.
6. Un nodo Set normaliza los datos: la fecha de nacimiento se cambia al formato que espera la base de datos, el nombre del profesional se relaciona con el identificador interno del personal y el inicio de la cita se convierte a la zona horaria de la base de datos.
7. Un nodo Postgres busca al paciente por el número de expediente médico propio del operador, que AppBO guarda en un campo personalizado. El paciente existe.
8. Un segundo nodo Postgres inserta la fila de la cita y escribe el identificador del evento en la tabla de deduplicación en el mismo lote de instrucciones, para que una repetición no pueda agendar dos veces.
9. Un nodo HTTP Request llama de vuelta a AppBO con la credencial guardada y escribe una nota en el contacto que registra que la cita se sincronizó, lo que le da a la recepción una confirmación visible.
10. La base de datos deja de estar disponible por un rato durante una ventana de mantenimiento. Los reintentos del nodo Postgres fallan, se dispara el flujo de error y el equipo de operaciones recibe una alerta con el nombre de la ejecución fallida.
11. Cuando termina la ventana, el equipo reintenta la ejecución fallida desde la lista de ejecuciones de n8n. La revisión de deduplicación sigue pasando porque no se escribió nada, la cita se inserta sin problemas y ningún dato de pacientes salió nunca de la red.

Límites de uso

Tu motor no tiene una cuota de tareas impuesta por un proveedor, lo que elimina un límite y deja expuesto otro: ahora es facilísimo saturar la API de AppBO. Un ciclo sobre diez mil contactos sin control de ritmo va a recibir respuestas 429 muy rápido. Agrega lotes a propósito y una espera entre lotes, respeta los encabezados de límite de uso y recuerda que tus propios sistemas internos también tienen límites de capacidad. La capacidad del lado de n8n es la que hayas aprovisionado; en el modo de un solo proceso, las ejecuciones simultáneas hacen fila una detrás de otra.

Reintentos e idempotencia

El reintento en caso de falla de n8n es por nodo y vuelve a ejecutar solo ese nodo, lo cual es útil, pero significa que un nodo de creación que se agotó por tiempo después de funcionar va a crear un segundo registro en el reintento. Mantén una tabla de deduplicación o una clave de upsert, y haz que el nodo que escribe sea idempotente en lugar de confiar en que el reintento es seguro. Sé realista con los reinicios del proceso: las ejecuciones en curso cuando el proceso se cae pueden no reanudarse, así que para todo lo que no se puede perder, deja que el reintento de webhooks de la plataforma sea tu red de seguridad y responde solo cuando ya hayas puesto el trabajo en una cola duradera.

Trampas al mapear campos

n8n pasa los datos como elementos (items), y un nodo que espera un elemento pero recibe veinte se va a ejecutar veinte veces. Es una sorpresa frecuente después de un nodo que devuelve una lista. Las expresiones dan un resultado vacío sin avisar cuando una ruta no existe, así que un campo renombrado más arriba produce valores vacíos en lugar de un error. Fija datos de muestra mientras construyes, y después acuérdate de quitarlos antes de activar; un flujo de trabajo que queda corriendo con datos fijados parece funcionar y no procesa nada real.

Creación de duplicados

Aquí se suman dos fuentes de duplicados: la entrega de webhooks de la plataforma, que es al menos una vez, y tus propios reintentos. Revisa un identificador de evento al principio del flujo de trabajo y guárdalo como parte de la misma escritura que crea el registro.

Pruebas contra producción

Corre instancias separadas, o como mínimo flujos de trabajo separados con credenciales separadas, para pruebas y producción, y nunca apuntes un flujo de prueba a una cuenta de AppBO en producción. La propia distinción de n8n entre una URL de prueba y una URL de webhook de producción confunde a mucha gente: un flujo que funciona mientras el editor está abierto pero no hace nada cuando lo cierras casi siempre es una URL de prueba registrada donde debía ir la de producción.

Vencimiento de la autorización e higiene operativa

Las credenciales OAuth vencen y necesitan renovarse; n8n se encarga de eso con las credenciales que administra, pero un token que pegaste en una credencial de autenticación por encabezado simplemente va a dejar de funcionar un día sin ningún aviso. Ponle un recordatorio de vencimiento a cualquier credencial estática. Más allá de la autorización, las fallas operativas son tuyas: un certificado TLS vencido, un disco lleno por un historial de ejecuciones que nunca se depuró, una actualización que cambia el comportamiento de los nodos y un almacén de credenciales cuya llave de cifrado nunca se respaldó.

Lo que se rompe con más frecuencia

• La URL pública de webhooks configurada no coincide con la realidad, así que no se puede llegar a las URL generadas.
• URL de webhook de prueba que se quedan en la configuración de producción.
• Datos fijados que se quedan en un nodo y ocultan que no está pasando nada real.
• El historial de ejecuciones llena la base de datos y degrada la instancia.
• Una interfaz del editor o un nodo Webhook sin autenticación expuestos a internet.
• Lógica de negocio enterrada en un nodo Code sin comentarios que ya nadie en el equipo entiende.
• Actualizaciones aplicadas sin leer las notas de la versión, que cambian el comportamiento de los nodos por debajo de flujos que funcionaban.