Introducción

Antes de conectar tu primer workflow real en n8n, necesitas entender una cosa que confunde a casi todos los principiantes: n8n no pasa archivos sin procesar ni streams entre nodos. Pasa items. Todo — un payload de webhook, una fila de base de datos, una respuesta de API — se envuelve en un item estructurado antes de pasar al siguiente nodo. Si adoptas este modelo mental desde el principio, depurar se vuelve mucho más fácil.

¿Qué es un item?

Un item es la unidad fundamental de datos en n8n. Cada nodo recibe un array de items y devuelve un array de items. Cada item es un objeto de JavaScript con una clave obligatoria llamada json, que contiene tus datos de payload reales como un objeto JSON. Opcionalmente, un item también puede llevar datos binarios (para archivos, imágenes, etc.), pero eso se trata por separado.

Un único item se ve así en su forma esencial:

{
  "json": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

Cuando un nodo como HTTP Request obtiene una lista de usuarios desde una API, n8n no entrega al siguiente nodo un gran array. Lo divide y entrega al siguiente nodo un item por cada usuario. Esto significa que si tu API devuelve 10 usuarios, el nodo siguiente se ejecuta 10 veces — una vez por cada item. Ese comportamiento es fundamental en la forma en que piensa n8n.

Cómo fluye el JSON entre nodos

Cuando haces referencia a datos de un nodo anterior, siempre estás accediendo a la clave json de un item. En las expresiones, n8n usa la sintaxis que se muestra a continuación para acceder al resultado del nodo anterior:

{{ $json.fieldName }}

Si quieres obtener datos de un nodo específico con nombre, en lugar del inmediatamente anterior, usas:

{{ $node["NodeName"].json.fieldName }}

En la práctica, si tienes un nodo Set que produce un item con la estructura mostrada anteriormente, el siguiente nodo puede hacer referencia al correo del usuario así:

{{ $json.email }}

Lo clave que debes interiorizar: nunca trabajas con el cuerpo de respuesta HTTP en crudo como una cadena. Cuando los datos llegan a tu expresión, n8n ya lo ha parseado en el objeto json. No necesitas llamar a JSON.parse() tú mismo.

El modelo de ejecución

n8n procesa los items de uno en uno a través de cada nodo, en secuencia. Cuando un nodo recibe varios items, itera sobre ellos automáticamente — no escribes un bucle. Esto se llama el modelo de ejecución basado en items.

Piensa en un workflow que lee 50 filas de una base de datos, transforma cada fila y envía un correo por fila. No escribes "por cada fila, enviar correo". Solo conectas los nodos. n8n se encarga de la iteración.

Esto tiene implicaciones importantes:

Primero, cada nodo de la cadena se ejecuta una vez por item de forma predeterminada. Un nodo que añade un campo de timestamp se ejecutará 50 veces para 50 items, produciendo 50 items de salida.

Segundo, algunos nodos fusionan o dividen deliberadamente el número de items. El nodo Merge puede combinar flujos. El nodo SplitInBatches puede agrupar items. El nodo Code puede remodelar todo el array si es necesario. Ser consciente de cómo cambia el conteo de items a lo largo del workflow es clave para evitar comportamientos inesperados.

Tercero, si algún nodo falla en un item, por defecto toda la ejecución se detiene. Puedes configurar el manejo de errores por nodo para cambiar esto, pero el comportamiento predeterminado es fail-fast.

Ejemplo práctico

Así se ve realmente un array de items cuando entra en un nodo Code. Puedes inspeccionarlo tú mismo usando el depurador integrado haciendo clic en el panel de salida de cualquier nodo.

[
  {
    "json": {
      "orderId": "ORD-001",
      "amount": 120.5,
      "status": "pending"
    }
  },
  {
    "json": {
      "orderId": "ORD-002",
      "amount": 89.0,
      "status": "shipped"
    }
  }
]

Si colocas un nodo Code después de esto y quieres añadir un flag de procesado a cada item, escribes:

for (const item of items) {
  item.json.processed = true;
}
return items;

Observa que tú iteras sobre los items dentro del nodo Code — esa es la única excepción a la regla de "n8n itera por ti". El nodo Code te entrega el array completo y espera el array completo de vuelta.

Resumen

Cada pieza de datos en n8n se envuelve en un item con una clave json. Los nodos reciben y emiten arrays de items, y por defecto cada nodo se ejecuta una vez por item — no gestionas bucles fuera del nodo Code. Expresiones como $json.fieldName son la forma de acceder a los datos de un item. Entender este modelo de ejecución es la base de todo lo demás: las transformaciones, las ramificaciones, las fusiones y el manejo de errores se construyen directamente sobre él.