1. Introducción: del JSON suelto al repositorio

Descripción

Al terminar esta lección vas a poder explicar por qué exportar un workflow como archivo JSON no es lo mismo que versionarlo, vas a tener el mapa completo de los seis módulos que forman esta guía, y vas a conocer la diferencia que sostiene todo el camino: la que separa a un "constructor de workflows" de un "dueño del sistema de automatización". También vas a conocer el caso de estudio —una empresa inventada con un workflow real— que te va a acompañar en los seis módulos.

Esto importa por una razón muy concreta: el mercado lo pide por escrito. Cuando lees ofertas de trabajo serias que mencionan n8n, una parte de ellas describe el entregable con una frase que se repite casi palabra por palabra: "as version-controlled, documented JSON" —workflows entregados como JSON versionado y documentado—. No dice "que funcione". Da por hecho que funciona. Pide algo más: que esté versionado, que esté documentado, que se pueda revisar y revertir. Esa frase es la línea divisoria de esta guía, y quien no puede producir ese entregable se queda del lado de afuera de las vacantes mejor pagadas, por más workflows que haya construido.

Conexión con el módulo: esta lección es el mapa, no todavía la técnica. Aquí instalas el problema (por qué un JSON suelto no basta) y conoces la herramienta conceptual (el control de versiones) y el caso que vas a usar de aquí en adelante. Las lecciones 2 a 7 te dan el marco completo: por qué versionar te cambia el rol (lección 2), qué límites tiene exportar e importar (lección 3), qué hay dentro del archivo JSON (lección 4), qué se rompe al reimportarlo (lección 5), el modelo mental de "workflow como código" (lección 6) y la verdad sin adornos sobre qué trae n8n gratis y qué solo en los planes de pago (lección 7). La lección 8 cierra con tu primer entregable: auditas y exportas un workflow. Una nota de límite desde ya: en este módulo no vas a aprender Git. Ni un comando. Git se enseña desde cero, para alguien que nunca lo tocó, en el Módulo 2 completo.

De guardar copias a tener un repositorio

Piensa en dos cocineros que trabajan en dos restaurantes distintos. Los dos cocinan igual de bien. La diferencia está en cómo guardan sus recetas.

El primero tiene sus recetas en la cabeza y en papelitos. Cuando cambia una —le sube la sal a la salsa, le baja el tiempo de cocción— tacha el papel viejo y escribe encima, o hace un papel nuevo y tira el anterior. Si el plato de hoy sale peor que el de la semana pasada, no hay forma de volver a la versión de la semana pasada: la tachó. Si se enferma y otro cocinero tiene que cubrirlo, le deja una carpeta con papeles donde no se entiende cuál es la versión buena. Y si dos ayudantes tocan la misma receta el mismo día, el que guarda su papel último gana, y el trabajo del otro desaparece sin que nadie se entere.

El segundo restaurante tiene un recetario. Cada receta tiene un historial: se ve quién la cambió, cuándo, y qué cambió exactamente —"el 3 de marzo bajamos la sal de 8 a 6 gramos porque un cliente se quejó"—. Cualquier cocinero puede leer por qué la salsa es como es. Si la nueva versión sale peor, se vuelve a la anterior en un minuto, porque la anterior no se borró: quedó guardada. Y si dos personas quieren cambiar la misma receta, el sistema no deja que una pise a la otra en silencio; las obliga a ponerse de acuerdo.

Los dos cocineros son igual de buenos con el cuchillo. Solo uno de los dos dirige una cocina que otra persona puede operar, auditar y recuperar cuando algo sale mal.

Eso es exactamente la diferencia entre exportar un workflow a un archivo JSON y versionarlo. El archivo JSON es el papelito: una foto del workflow en un momento. Puedes tener veinte fotos en una carpeta llamada Descargas, con nombres como order-triage (3).json y order-triage-FINAL.json, y aun así no tener control de versiones. Tener copias no es tener historial. El control de versiones —el recetario— es un sistema que guarda cada cambio con su fecha, su autor y su motivo, que te deja volver a cualquier punto anterior, y que coordina a varias personas para que nadie pise el trabajo de nadie.

Esta guía es sobre construir ese recetario para tus workflows. El Módulo 2 te enseña la herramienta que lo hace —se llama Git— desde cero. Pero antes de aprender la herramienta, este módulo te da la razón. Porque una técnica que aprendes sin entender qué problema resuelve se te olvida a la semana.

Ejemplo trabajado: la carpeta de descargas contra el repositorio

Vamos a ver la diferencia sin entrar todavía en ninguna herramienta. Imagina el mismo cambio hecho de las dos formas.

Un workflow de Cumbre —ya te presento la empresa en un momento— clasifica pedidos. Alguien decide que los pedidos de más de 5000 pesos vayan a revisión manual en vez de aprobarse solos. Hace el cambio en el editor de n8n y lo guarda.

Forma 1: la carpeta de descargas. Abre el menú del workflow, elige Download, y n8n le baja un archivo order-triage.json a su computadora. Ya tiene la nueva versión guardada. Pero fíjate en lo que no tiene:

• No sabe en qué se diferencia este archivo del que bajó el mes pasado. Los dos son bloques de texto de cientos de líneas; encontrar el cambio a ojo es imposible.
• Si el cambio resulta un error —empiezan a llegar quejas de que todo va a revisión manual—, tiene que acordarse de cuál de los archivos de su carpeta era el bueno. Y si el bueno ya lo sobrescribió, no hay bueno.
• Si un compañero también tocó order-triage esa semana, ahora hay dos archivos order-triage.json en dos computadoras distintas, cada uno con la mitad de la verdad, y nadie sabe cómo juntarlos.

Forma 2: el repositorio. Hace el mismo cambio en el editor, exporta el mismo archivo, pero lo guarda en un repositorio con una nota corta: "send orders over 5000 to manual review". Ahora:

• El sistema le muestra exactamente qué cambió respecto de la versión anterior: dos o tres líneas resaltadas, no cientos. Puede leer el cambio en diez segundos.
• Si el cambio fue un error, vuelve a la versión anterior con un comando. La anterior sigue ahí, intacta, con su fecha.
• Si un compañero tocó el mismo workflow, el sistema lo detecta y los obliga a reconciliar los dos cambios antes de que uno borre al otro.

Qué esperar. El cambio en el editor es idéntico en las dos formas: mismo workflow, mismo comportamiento nuevo. Lo que cambia no es lo que hace el workflow hoy; es todo lo que puedes hacer con él mañana. La Forma 1 te deja un archivo. La Forma 2 te deja un archivo más su historia, su explicación y una red de seguridad. Esa diferencia es invisible el día que todo funciona, y es la diferencia entre una tarde tranquila y una noche en vela el día que algo se rompe.

No necesitas entender todavía qué es un "repositorio" ni qué comando revierte un cambio. Eso es el Módulo 2. Lo único que quiero que te lleves es que tener el archivo no es lo mismo que tener el control.

Qué es, exactamente, un workflow versionado

Definamos bien los términos, porque el resto de la guía se apoya en ellos.

Un workflow es lo que ya sabes construir: el lienzo de n8n con sus nodos conectados —un disparador, unos nodos de integración, unos filtros, quizás un nodo AI Agent—. Cuando lo construyes, vive dentro de tu instancia de n8n, guardado en su base de datos. Ahí lo editas, lo ejecutas y lo ves correr.

El JSON del workflow es ese mismo workflow escrito como texto. JSON —JavaScript Object Notation— es un formato para representar datos estructurados con llaves, corchetes y pares de "nombre: valor". Cuando exportas un workflow, n8n toma todo lo que hay en el lienzo —qué nodos hay, cómo están conectados, cómo está configurado cada uno— y lo escribe en un archivo de texto con ese formato. Ese archivo es la lección 4 completa; por ahora quédate con la idea de que el JSON es el workflow en forma de texto, y que como es texto, se puede guardar, comparar y versionar igual que cualquier documento.

Versionar un workflow es guardar ese JSON dentro de un sistema de control de versiones, de modo que cada cambio quede registrado con su fecha, su autor y una nota que explica el motivo. Un sistema de control de versiones es un programa cuyo único trabajo es recordar la historia de unos archivos: cada estado por el que pasaron, quién los llevó ahí y por qué. El más usado del mundo se llama Git, y es el que enseña esta guía. Pero Git es la herramienta; versionar es la idea.

Y el repositorio —lo vas a leer mil veces de aquí en adelante— es el lugar donde vive esa historia. Piénsalo como la carpeta del proyecto, pero una carpeta con memoria: no solo guarda los archivos como están ahora, guarda todas las versiones por las que pasaron. Un repositorio puede vivir en tu computadora y también tener una copia en un servicio como GitHub, para respaldo y para trabajar en equipo. El nombre del repositorio de nuestro caso de estudio va a ser cumbre-automations.

Tres consecuencias de esto que conviene tener claras desde ya:

El repositorio, no la instancia de n8n, es la fuente de verdad. Esto suena raro al principio y es el corazón del Módulo 6. La instancia de n8n donde corre el workflow es como un músico tocando: es donde pasa la música. El repositorio es la partitura: es donde está escrito qué debe pasar. Si el músico se equivoca, vuelves a la partitura. Si pierdes al músico, contratas otro y le das la partitura. Lo que no puedes perder es la partitura.

Versionar no cambia lo que hace el workflow. Un workflow versionado y uno sin versionar corren exactamente igual y producen el mismo resultado. Versionar no es una mejora de rendimiento ni una feature nueva para tus usuarios. Es una mejora en tu capacidad de operar, entender y recuperar el sistema. El beneficio lo cobras tú y tu equipo, no el pedido que se procesa hoy.

Versionar es la base de todo lo demás. No es un tema aislado. Es el cimiento sobre el que se construyen los entornos (Módulo 4), la prueba en sandbox (Módulo 5) y la promoción y el rollback (Módulo 6). Si el JSON no está versionado, no hay forma limpia de decir "esta versión probada es la que va a producción". Por eso este es el módulo 1: sin él, los demás no se sostienen.

La evidencia: qué pide realmente el mercado

Vale la pena mirar de frente el dato que justifica esta guía, con sus límites.

Cuando se revisan ofertas de trabajo que mencionan n8n y se lee la sección de requisitos completa —no el título—, aparece un patrón que a primera vista sorprende. Sobre un conjunto de unas 38 ofertas serias analizadas a mediados de 2026, la proporción aproximada es esta:

Lo que pide la oferta	Proporción aproximada	Qué implica en la práctica
Prueba en sandbox o entornos separados (staging/prod)	~12 de 38	Tienes que poder probar un cambio sin tocar producción
Control de versiones con Git	~6 de 38	Tienes que entregar los workflows como JSON versionado
Solo construcción de workflows	El resto	El piso, no el techo: es lo que se asume, no lo que diferencia

Tres advertencias honestas sobre estos números, porque enseñar un dato sin sus límites es enseñar mal.

Primera: no son un censo, son una muestra. Treinta y ocho ofertas no son el mercado entero; son una foto de un momento y de unas cuantas bolsas de trabajo. El número exacto va a cambiar según dónde y cuándo mires. Tómalos como una banda, no como un punto.

Segunda: la proporción parece baja, y ese es el punto. Solo 6 de 38 piden Git explícitamente. Podrías concluir que no vale la pena. Sería un error, por la tercera advertencia.

Tercera, y es la que importa: las ofertas que piden esto no son una muestra aleatoria. Son sistemáticamente las mejor pagadas y las que dan más autonomía. La vacante que pide "workflows as version-controlled, documented JSON" y "experience with staging and production environments" no está buscando a alguien que arme flujos; está buscando a alguien que posea un sistema. El vocabulario lo delata: "automation system owner" en vez de "workflow builder". Son roles distintos, con sueldos distintos, y el filtro entre uno y otro es justo lo que enseña esta guía.

Y hay una señal más, del otro lado del mostrador. En el foro oficial de n8n, entre las razones que la gente da para abandonar la herramienta y migrar a otra, aparece una frase que se repite: "poor version control" —control de versiones pobre—. No es que n8n no pueda versionarse; es que mucha gente nunca aprendió a hacerlo y terminó culpando a la herramienta. Esta guía es, en parte, la respuesta a esa queja: sí se puede, y a costo cero.

Esa es la razón real de esta guía. No el porcentaje: la clase de rol para el que te habilita, y el problema concreto que te enseña a no sufrir.

Constructor de workflows contra dueño del sistema

Esta distinción es el hilo que atraviesa los seis módulos, así que vale la pena nombrarla bien desde el principio.

Un constructor de workflows sabe hacer que las cosas funcionen. Le das un requerimiento —"cuando entre un pedido, clasifícalo y mándalo al CRM"— y lo arma en el lienzo, lo prueba a mano, ve que funciona, y lo activa. Es una habilidad real y valiosa. Es el piso del oficio.

Un dueño del sistema de automatización sabe todo eso y además responde otras preguntas, que son las que se hacen en una entrevista técnica y las que aparecen a las tres de la mañana cuando algo falla:

• ¿Cómo llevas un cambio a producción sin arriesgar lo que ya funciona?
• Si el cambio de ayer rompió algo, ¿cómo vuelves a la versión de anteayer, y en cuánto tiempo?
• ¿Cómo pruebas un workflow que le escribe al CRM real, sin escribirle al CRM real?
• Si tu compañero y tú tocan el mismo workflow, ¿cómo evitan pisarse?
• Cuando entregues este sistema y te vayas, ¿cómo hace la siguiente persona para entender por qué está armado así?

Fíjate en que ninguna de esas preguntas es sobre construir. Todas son sobre operar, versionar, probar y entregar. El constructor arma la máquina; el dueño garantiza que la máquina se pueda reparar, mejorar y traspasar sin drama. El mercado paga mucho más por el segundo, porque el segundo es quien le quita el miedo a la empresa de depender de una automatización.

Esta guía te lleva del primero al segundo. No te enseña a construir mejores workflows —eso lo dan las guías de fundamentos y de patrones de diseño—. Te enseña a envolver los workflows que ya sabes construir en la disciplina que los vuelve un sistema entregable. Al terminar, vas a producir exactamente el artefacto que el mercado pide por escrito, y vas a poder defenderlo en una entrevista.

El caso de estudio de esta guía: Cumbre y su workflow order-triage

Toda la guía trabaja sobre la misma empresa y el mismo workflow. La razón es pedagógica: si cada lección estrena un ejemplo, gastas la mitad de tu energía entendiendo el contexto en vez del concepto. Con un solo caso, para el Módulo 4 ya conoces el terreno de memoria.

Cumbre es una distribuidora mayorista latinoamericana. Le vende café, té e insumos de despensa a unas 400 cafeterías y tiendas pequeñas repartidas en varias ciudades. Es la misma empresa de la guía de JavaScript en el nodo Code, y la usamos otra vez a propósito, para darte continuidad: si vienes de esa guía, ya la conoces. No es una empresa grande —tiene doce personas— y por eso automatiza: no le alcanza el equipo para procesar los pedidos a mano.

El equipo de automatización de Cumbre mantiene un workflow que es el protagonista de esta guía. Se llama order-triage, y hace tres cosas:

1. Recibe pedidos que entran por distintos canales.
2. Los clasifica con un nodo AI Agent —decide si un pedido se aprueba solo, si va a revisión manual, o si le falta información—.
3. Consulta el CRM con un nodo HTTP Request, para enriquecer el pedido con datos del cliente y registrar el resultado.

Notarás que el workflow tiene justo las dos piezas que hacen que versionarlo sea interesante y que reimportarlo sea peligroso: un nodo AI Agent, que necesita credenciales de un proveedor de modelos, y una llamada HTTP al CRM, que necesita credenciales del CRM. Esas credenciales son el centro del problema de portabilidad que vas a estudiar en las lecciones 4 y 5. No es casualidad que el caso las tenga: son exactamente el tipo de cosa que se rompe cuando mueves un workflow de una instancia a otra.

A lo largo de la guía, order-triage es el workflow que vas a versionar (Módulos 2 y 3), probar en sandbox (Módulo 5) y promover por entornos (Módulos 4 y 6). Esos entornos van a llamarse, en inglés como manda la convención, dev, staging y prod:

Entorno	Para qué sirve	Con qué datos y credenciales trabaja
dev	Construir y probar cambios sin miedo	Datos sintéticos, credenciales de prueba
staging	Ensayar el cambio en condiciones parecidas a producción	Datos parecidos a los reales, credenciales de prueba
prod	Correr de verdad, con los pedidos reales de Cumbre	Datos y credenciales reales

Y el repositorio donde vive el historial versionado de order-triage —y del resto de las automatizaciones de Cumbre— se va a llamar cumbre-automations.

Guarda estos nombres, porque los vas a ver en las seis módulos: el workflow order-triage, los entornos dev/staging/prod, el repositorio cumbre-automations. Están todos en inglés, y es deliberado: es la convención de todo el ecosistema tech. El código, los nombres de archivo, de rama, de entorno y de repositorio van en inglés, aunque la prosa que lees vaya en español. Es la mezcla que vas a encontrar en cualquier empresa de la región.

Una última nota sobre Cumbre: es una empresa inventada. Los números —400 clientes, doce personas, el umbral de 5000 pesos para revisión manual— son hipótesis razonables para practicar, no datos de mercado. Si mañana trabajas en una distribuidora real, los umbrales van a ser otros; lo que se transfiere es la forma de pensar el problema.

Los prerrequisitos y el camino por defecto

Antes de seguir, conviene ser claro sobre qué necesitas y qué no.

Lo que sí necesitas: haber construido workflows reales en n8n. Esta guía no te enseña a armar un flujo, un disparador ni un nodo AI Agent; da por hecho que ya lo sabes hacer, porque su trabajo es versionar y entregar lo que ya sabes construir. Si nunca armaste un workflow completo, el lugar para empezar es la guía de fundamentos o el bootcamp gratuito de n8n, y después vuelves aquí.

Lo que también vas a usar: una terminal básica —correr comandos, editar archivos— y Docker instalado en tu máquina, porque a partir del Módulo 4 vamos a levantar entornos locales con Docker Compose. No te preocupes si no dominas ninguna de las dos: se explican en su momento, paso a paso, con la señal exacta de qué vas a ver en pantalla.

Lo que NO necesitas: saber Git. Es el punto más importante de esta sección. Git se enseña desde cero en el Módulo 2, para alguien que jamás lo tocó. Si ya lo conoces, vas a avanzar rápido; si no, no es un problema, es el plan. Tampoco necesitas saber administrar servidores: aquí Docker Compose solo levanta entornos en tu propia computadora, no despliega nada en internet.

El camino por defecto de toda la guía es self-hosted Community a costo cero. Esto merece una frase clara porque hay mucha confusión al respecto. n8n tiene una edición gratuita y de código abierto —Community— que puedes instalar en tu máquina, y con ella se hace todo lo que enseña esta guía: versionar con Git, entornos separados, prueba en sandbox, promoción y rollback. Cero pesos. Hay features que solo existen en los planes de pago —el control de versiones con Git integrado en la interfaz, por ejemplo—, y cuando aparezcan te las voy a declarar con honestidad, explicando qué hacen y cuándo vale la pena pagarlas. Pero el camino principal no cuesta nada, y la lección 7 le dedica toda su atención a esta frontera.

Qué vas a poder hacer al terminar el módulo

Este módulo tiene una capacidad de salida acotada, y es a propósito. Al final de la lección 8 vas a poder:

• Explicar por qué exportar e importar JSON no es versionar, con argumentos concretos, no con eslóganes.
• Leer la estructura del JSON de un workflow y nombrar sus partes principales: nodos, conexiones, configuración, identificadores, referencias a credenciales.
• Identificar qué campos se rompen cuando reimportas un workflow ingenuamente en otra instancia: IDs de credencial, IDs de nodo, webhooks, variables embebidas.
• Producir tu primer entregable de la guía: un workflow exportado más una nota de riesgos de portabilidad.

Lo que no vas a poder hacer todavía, y está bien: versionar de verdad con Git. Este módulo te da el porqué y el mapa del problema; el Módulo 2 te da el cómo. Si al terminar sientes que entiendes perfectamente qué se rompe y por qué necesitas control de versiones, pero todavía no sabrías crear un repositorio, ese es exactamente el resultado esperado.

El mapa de este módulo

Lección	Qué resuelve
2	El reparto del mercado: por qué "funciona en mi editor" no es un entregable, y qué artefacto te hace pasar el filtro de una entrevista
3	Cómo se exporta hoy un workflow y por qué copiar y pegar JSON no es historial, ni revisión, ni rollback, ni colaboración
4	Qué hay dentro del archivo JSON: nodos, conexiones, configuración, IDs, credenciales; qué campos son estables y cuáles volátiles
5	Qué se rompe al reimportar en otra instancia y por qué "lo exporté y lo importé" falla en silencio
6	El modelo mental de "workflow como código": el repositorio como fuente de verdad y el ciclo editar → exportar → commit → revisar → promover
7	Qué trae Community gratis y qué solo los planes de pago, con el criterio para decidir cuándo vale pagar
8	Proyecto: audita y exporta un workflow, y escribe su nota de riesgos de portabilidad

Fíjate en el orden, porque no es arbitrario. Primero el para quién y para qué (lección 2): el rol que persigues. Después el problema en detalle: cómo se exporta hoy y por qué no basta (3), qué hay dentro del archivo (4) y qué se rompe al moverlo (5). Recién entonces la solución conceptual: el modelo de "workflow como código" (6). Y antes de cerrar, la verdad económica: qué es gratis y qué se paga (7). El proyecto (8) junta todo en un entregable.

Lo que esta guía deliberadamente no cubre

Vale la pena decirlo temprano para que sepas dónde buscar lo que no está aquí.

No es una guía para construir workflows. No vas a aprender nodos, disparadores ni lógica de flujo. Eso son las guías de fundamentos y de patrones de diseño. Aquí versionamos y entregamos lo que ya sabes construir.

No es una guía de agentes de IA. El workflow order-triage tiene un nodo AI Agent, pero solo lo versionamos, promovemos y probamos. Diseñar el agente, sus herramientas y sus bucles es tema de la guía de chatbots y agentes.

No es una guía de operación en producción. Monitoreo, alertas, manejo de errores, reintentos y control de costos en vivo son de la guía de mantenimiento en producción. Aquí el motor de depuración se usa como herramienta de prueba, no de diagnóstico de incidentes.

No es una guía de infraestructura de servidores. Desplegar en un VPS, reverse proxy, endurecer Linux, escalar con workers: todo eso es la guía de producción. Aquí Docker Compose solo levanta entornos locales aislados en tu máquina.

Errores comunes

Creer que "tengo el archivo JSON" es lo mismo que "tengo control de versiones" (conceptual). Qué pasa: alguien exporta sus workflows regularmente, los guarda en una carpeta o en Google Drive, y cree que ya está versionando. Un día necesita volver a la versión de hace tres semanas y descubre que solo tiene la de hoy, o que tiene diez archivos con nombres confusos y no sabe cuál era el bueno. Por qué pasa: la palabra "versión" se usa flojamente; tener varias copias parece versionar. Cómo detectarlo: pregúntate si puedes responder, para tu workflow más importante, "¿qué cambió entre la versión de hace un mes y la de hoy, y quién lo cambió?". Si no puedes, no estás versionando, estás acumulando archivos. Cómo corregirlo: es justo lo que enseña esta guía. El control de versiones no es tener copias; es tener un sistema que registra cada cambio con su fecha, su autor y su motivo, y que te deja volver a cualquier punto. Los archivos sueltos no hacen nada de eso.

Saltarse esta guía porque "mis workflows ya funcionan" (conceptual). Qué pasa: alguien construye workflows sólidos, los tiene corriendo en producción, y concluye que versionar es burocracia para empresas grandes. Funciona, hasta el día en que un cambio rompe algo y no hay cómo volver atrás, o hasta la entrevista donde le preguntan cómo maneja los despliegues y no tiene respuesta. Por qué pasa: el costo de no versionar es invisible mientras nada falla, y el beneficio se cobra en el futuro. Cómo detectarlo: si tu plan de recuperación ante un cambio malo es "espero acordarme de qué toqué", ya tienes el problema. Cómo corregirlo: entiende que versionar no es para cuando el sistema es grande, es para cuando el sistema importa. Un solo workflow que le escribe al CRM real de la empresa ya justifica poder revertirlo en un minuto.

Pensar que versionar es una habilidad de programadores y no de automatizadores (conceptual). Qué pasa: alguien asocia Git y repositorios con "eso es cosa de desarrolladores de software" y decide que no es parte de su rol. Por qué pasa: durante años el control de versiones vivió solo en el mundo del código, y el marketing del no-code vendió justo lo contrario —"no necesitas nada de eso"—. Cómo detectarlo: si crees que tu trabajo termina cuando el workflow funciona en tu editor, tienes esta creencia. Cómo corregirlo: mira las ofertas de trabajo. Las que pagan mejor piden explícitamente "version-controlled JSON". Versionar dejó de ser opcional para el automatizador profesional el día que el mercado empezó a pedirlo por escrito. No es cosa de programadores; es la parte del oficio que separa a quien arma flujos de quien es dueño de un sistema.

Ejercicios

Ejercicio 1 — Lee el mercado con tus propios ojos. Busca cinco ofertas de trabajo reales que mencionen n8n (en LinkedIn, en bolsas de trabajo remotas o en canales de la comunidad). Para cada una, lee la sección de requisitos completa y anota si aparece alguna de estas señales: "version control" o "Git", "staging"/"production"/"environments", "CI/CD", "documented", o "JSON". Cuenta en cuántas de las cinco aparece al menos una.

Ver solución

No hay una respuesta única, y ese es el punto: el dato tiene que ser tuyo. Lo que la mayoría encuentra es un patrón: las ofertas junior o de agencias pequeñas rara vez mencionan estas palabras; las ofertas remotas en dólares, o las de empresas con un equipo técnico, las mencionan mucho más, a veces en la primera línea de requisitos.

Si de tus cinco ofertas ninguna pide nada de esto, tienes dos hipótesis igual de válidas: o tomaste una muestra de vacantes muy junior, o el mercado de tu región va con retraso respecto del promedio remoto. Amplía a diez antes de concluir.

Por qué funciona: la evidencia que cité —unas 6 de 38 pidiendo Git, unas 12 de 38 pidiendo entornos— es un promedio ajeno. Este ejercicio lo convierte en un dato propio, que es el único que va a cambiar lo que haces esta semana. Y te entrena a leer los requisitos completos, no el título, que es donde vive la información que separa a un rol de otro.

Ejercicio 2 — Traduce tu situación actual. Piensa en el workflow más importante que hayas construido (o, si no tienes uno, en order-triage de Cumbre). Responde por escrito, en una frase cada una: (a) Si tuvieras que volver a la versión de hace un mes, ¿podrías? (b) Si un compañero editara el mismo workflow hoy, ¿cómo se enterarían de que los dos lo tocaron? (c) Si te fueras de la empresa mañana, ¿cómo entendería la siguiente persona por qué está armado así?

Ver solución

La respuesta honesta de la mayoría, antes de esta guía, es alguna variante de "no podría", "no nos enteraríamos" y "no lo entendería". Y está bien: ese es exactamente el estado de partida que esta guía resuelve.

(a) Volver a una versión anterior requiere haber guardado esa versión de forma recuperable. Un archivo en una carpeta quizás sirve, si te acuerdas de cuál era y no lo sobrescribiste. Un repositorio lo garantiza. (b) Enterarse de un cambio simultáneo requiere un sistema que detecte conflictos; dos archivos en dos computadoras no lo hacen. (c) Que otra persona entienda el "porqué" requiere documentación y un historial de decisiones; el workflow por sí solo muestra el "qué", no el "porqué".

Por qué funciona: las tres preguntas son, respectivamente, rollback (Módulo 2 y 6), colaboración (Módulo 2) y documentación/handoff (Módulo 3). Si al leerlas sentiste incomodidad, esa incomodidad es el mapa de lo que vas a resolver. Guarda tus respuestas: al terminar la guía, vuelve a leerlas y fíjate cuántas cambiaron.

Ejercicio 3 — Reconstruye el mapa. Sin volver a mirar la tabla de la sección "El mapa de este módulo", escribe de memoria qué resuelve cada una de las siete lecciones que siguen (2 a 8), en una frase cada una. Después compara y marca las que se te escaparon.

Ver solución

(2) El reparto del mercado: constructor contra dueño del sistema, y qué artefacto te hace pasar el filtro. (3) Cómo se exporta hoy y por qué copiar y pegar JSON no es versionar. (4) Qué hay dentro del archivo JSON de un workflow y qué campos son estables o volátiles. (5) Qué se rompe al reimportar en otra instancia y por qué falla en silencio. (6) El modelo mental de "workflow como código": el repo como fuente de verdad y el ciclo de trabajo. (7) Qué es gratis en Community y qué se paga, con el criterio de decisión. (8) El proyecto: auditar y exportar un workflow con su nota de riesgos.

Por qué funciona: si pudiste reconstruir al menos cinco de las siete, ya tienes internalizada la progresión del módulo, que va del rol (¿para qué?) al problema (¿por qué el JSON suelto no basta?) a la solución conceptual (¿qué modelo lo resuelve?) a la economía (¿qué cuesta?). Las que más se escapan suelen ser la 4 y la 5, que son las más técnicas y todavía no las viste.

Resumen y siguiente paso

En esta lección viste que tener el archivo JSON de un workflow no es lo mismo que tener control sobre él: el archivo es una foto, y el control de versiones es el recetario con historia, autor y motivo de cada cambio, más la capacidad de volver atrás y de coordinar a varias personas. Viste la imagen de los dos cocineros —los dos buenos, solo uno capaz de dirigir una cocina operable— y el mismo cambio hecho con la carpeta de descargas contra el repositorio. Entendiste que el mercado pide por escrito workflows "as version-controlled, documented JSON", y que ese entregable es la línea que separa al constructor de workflows del dueño del sistema de automatización. Conociste a Cumbre y a su workflow order-triage —con su nodo AI Agent y su llamada HTTP al CRM—, los entornos dev/staging/prod y el repositorio cumbre-automations, que te acompañan las seis módulos. Y recibiste el mapa del módulo, los prerrequisitos y el camino por defecto: self-hosted Community a costo cero.

Antes de avanzar a la lección 2 deberías poder: explicar en una frase por qué tener copias no es versionar; nombrar las tres cosas que hace order-triage y las dos piezas que lo hacen interesante para versionar (el nodo AI Agent y la llamada al CRM); y decir de memoria qué distingue a un constructor de un dueño del sistema.

Lo que sigue es afilar esa distinción hasta que sea operativa. La lección 2 entra de lleno en el reparto del mercado: por qué "funciona en mi editor" no es un entregable que alguien pueda pagar, qué preguntas te hace un entrevistador para saber de qué lado de la línea estás, y qué artefacto concreto —el mismo que vas a producir en esta guía— te hace pasar ese filtro.

Recursos

• Export and import workflows — n8n Docs — la página oficial que describe cómo exportar (Download) e importar un workflow desde el editor; la vas a usar de referencia en las lecciones 3 y 8.
• Source control and environments — n8n Docs — la sección oficial sobre control de versiones y entornos; útil para ver desde ya qué es lo que solo traen los planes de pago, tema de la lección 7.
• Git and n8n — n8n Docs — cómo n8n integra Git en su interfaz (una feature de pago); la contrastamos con el camino gratuito de esta guía.
• Understand workflows — n8n Docs — los componentes de un workflow (nodos, conexiones), base de la anatomía del JSON que estudias en la lección 4.
• Release notes 2.x — n8n Docs — el historial de la versión 2 de n8n; útil para confirmar qué versión usas frente a lo que dice esta guía.