Módulo 3: Loops e Iteraciones

Mini-Proyecto: Procesar 1000 Items con Rate Limit

Siguiente →

Descripción de la cápsula

Cierre del módulo. Vas a construir un workflow real que procesa 1000 items llamando una API con rate limit, integrando todos los patrones del módulo: SplitInBatches, Wait, retry de fallos, Aggregate al final, y reporting completo.

El caso: enriquecer 1000 leads con datos adicionales desde una API (Clearbit-style, mock o real). Esta es una tarea común en automatización de marketing/sales y demuestra dominio de los patterns de loops en producción.

Lo que vas a aprender

Al terminar este mini-proyecto serás capaz de:

  • ✅ Integrar SplitInBatches + Wait + retry + Aggregate
  • ✅ Procesar volumen realista (1000 items) sin saturar APIs
  • ✅ Manejar errores durante el loop sin perder progreso
  • ✅ Reportar resultados comprehensivos al final
  • ✅ Sentir confianza para procesar listas grandes en producción

El escenario

Lo que tienes

Un Google Sheet con 1000 leads (columns: name, email, company). Quieres:

  1. Para cada lead, llamar una API de enrichment (simulada o real)
  2. La API devuelve datos extra (industry, company_size, linkedin_url, funding)
  3. Combinar lead + datos enrichment
  4. Guardar el resultado en otro Sheet leads_enriched
  5. Al final, mandar reporte a Slack con stats

Restricciones

  • API rate limit: 10 requests/segundo (600/min)
  • Tu plan de n8n: suficiente para 1000+ ejecuciones internas
  • Algunos leads van a fallar (datos incompletos, API timeout) — esperado ~5%

Output esperado

  • Sheet leads_enriched con 950-1000 filas (los que se enriquecieron OK)
  • Sheet leads_failed con 50 filas (los que fallaron, con razón)
  • Slack: "Procesados 1000 leads. 952 enriquecidos. 48 fallaron. Tiempo: 2.5 min."

Paso 1: Preparar los datos

1.1. Crear el Sheet de input

Sheet leads_to_enrich. Si no tienes 1000 leads reales, genera con datos fake:

  • Usa Mockaroo o similar
  • 1000 filas con columns: name, email, company

1.2. Crear Sheets para output

  • leads_enriched: columns name, email, company, industry, company_size, linkedin_url, funding, enriched_at
  • leads_failed: columns name, email, company, failure_reason, attempted_at

1.3. API de enrichment

Para este proyecto puedes:

  • Opción A (más realista): usar Clearbit free tier, Hunter.io, o similar
  • Opción B (gratis): mock con JSONPlaceholder o Beeceptor — recibe email, responde con datos fake

Para la lección, asumimos mock que responde:

{
  "email": "input email",
  "industry": "Software",
  "company_size": "50-200",
  "linkedin_url": "https://linkedin.com/...",
  "funding": "Series A"
}

O error 404 si email es inválido / no encuentra.

Paso 2: Construir el workflow

2.1. Workflow nuevo

Nombre: [PROY-G2M03] Enriquecer 1000 leads

2.2. Trigger

Manual Trigger (para development). En producción podrías usar Schedule diario.

2.3. Leer el Sheet

Google Sheets node:

  • Operation: Get Rows
  • Document: leads_to_enrich
  • Filter: ninguno (todos)

Output: 1000 items.

2.4. SplitInBatches

[SplitInBatches]
  - Batch Size: 10

10 items por batch → 100 batches. Con rate limit 10/seg, batch 10 + Wait 1s = exactamente al ritmo.

2.5. Dentro del loop: HTTP Request a la API

[HTTP Request]
  - URL: https://your-api/enrich
  - Method: POST
  - Body: { "email": "{{ $json.email }}" }
  - Continue On Fail: ON  ← importante (cápsula 6 de G1)
  - Retry On Fail: ON, max 2, wait 5000ms  ← para errores transitorios

2.6. Separar éxitos y fallos

Después del HTTP, IF para clasificar:

[IF: $json.error existe o status code >= 400]
├─ TRUE → branch fallidos
└─ FALSE → branch exitosos

Branch exitosos:

  • Set node: combinar datos lead + enrichment
  • Sheet Append a leads_enriched

Branch fallidos:

  • Sheet Append a leads_failed con razón

2.7. Wait entre batches

Después del procesamiento de cada batch:

[Wait 1 second]

2.8. Loop back

Conectar el último nodo (Wait) de vuelta a SplitInBatches.

2.9. Done branch

Cuando SplitInBatches termina:

[Done] → [reporte final]

Paso 3: Reporte final con Aggregate

3.1. Leer los Sheets de resultados

Después del Done:

[Sheets: leer 'leads_enriched'] → processed_ok
[Sheets: leer 'leads_failed']    → processed_fail

3.2. Calcular stats

[Set:]
  - total_processed: ok + fail
  - total_ok: $json.processed_ok.length
  - total_fail: $json.processed_fail.length
  - success_rate: total_ok / total_processed * 100
  - total_time: (variable que mantengas con $now al inicio y diferencia al final)

3.3. Slack

[Slack]
  Mensaje:
  📊 *Enrichment completado*

  Total procesados: {{ $json.total_processed }}
  ✅ Exitosos: {{ $json.total_ok }}
  ❌ Fallidos: {{ $json.total_fail }}
  Tasa éxito: {{ $json.success_rate.toFixed(1) }}%

  Tiempo: {{ $json.total_time }} segundos

  Sheets:
  • Enriched: {{ url al sheet }}
  • Failed: {{ url al sheet }}

Paso 4: Estimación de tiempo

Antes de ejecutar, calcula cuánto va a tardar:

1000 items / 10 batch_size = 100 batches
Tiempo por batch:
  - 10 HTTP requests paralelas: ~1-2 segundos
  - Wait: 1 segundo
Total por batch: ~3 segundos

Total: 100 × 3 = 300 segundos = 5 minutos

Si tu plan tiene timeout >5 min, perfecto. Si no, considerar:

  • Reducir batch size (más batches, más rápido por batch)
  • Aumentar paralelismo dentro del batch
  • Dividir en 2 workflows con Schedule

Paso 5: Ejecutar y monitorear

5.1. Test con pocos items primero

No empieces con 1000. Cambia tu Sheet input a 20 items o usa un Filter al inicio que toma solo 20. Valida que todo funciona en pequeño.

5.2. Ejecutar con 1000

Cuando confirmes que funciona:

  • Quita el Filter
  • Click Execute Workflow
  • Monitorear: abre Executions panel, ve progreso

5.3. Si algo falla durante

  • Workflow se detiene → revisa nodo rojo
  • Algunos items fallaron pero el loop continuó (gracias a Continue on Fail)

5.4. Verificar resultados

Al terminar:

  • Sheet leads_enriched debe tener ~950+ filas
  • Sheet leads_failed debe tener ~50 filas con razones
  • Slack message recibido

Variantes opcionales

Si te quedaron ganas:

Variante 1: Resilience al failure mid-loop

¿Qué pasa si n8n se reinicia a mitad del procesamiento? Pierdes los items en progreso.

Solución:

  • Agregar columna already_processed al Sheet input
  • Al inicio del loop, marcar already_processed = true después de procesar
  • Workflow restartable: empieza con Filter already_processed = false

Variante 2: Retry diario de los fallidos

Si tienes 50 fallidos, vale la pena retry mañana (datos cambian, APIs se recuperan):

  • Schedule diario que lee leads_failed
  • Re-procesa solo los que la razón sugiere retry vale la pena (timeout, 5xx — no 404)
  • Marca como permanently_failed después de N retries

Variante 3: Dashboard de progreso en tiempo real

Crear un Sheet progress_tracker que se actualiza cada batch:

  • current_batch, total_batches, ok_so_far, fail_so_far, pct_complete

Útil para procesamientos largos donde quieres ver progreso sin abrir Executions.

Reflexión final

Lo que aplicaste en este proyecto

PatrónDónde
SplitInBatches (cápsula 03)Loop principal de 100 batches
Process all pattern (cápsula 04)Estrategia del loop
Rate limiting (cápsula 05)Wait 1s entre batches
Retry on Fail (G1-M06)HTTP node retry config
Continue on Fail (G1-M06)Para no parar el loop al primer fail
Sheet append durante loopAcumulación durable
Aggregate después del loopSheets read + stats
Reporting con SlackMensaje final

Cobertura total del módulo aplicada en un solo workflow.

Lo que aprendiste en M03 (zoom out)

Antes de M03Después de M03
Procesabas máximo ~100 itemsProcesas 1000+ sin saturar APIs
Iteración implícita era todoSabes cuándo explícita vale
Te confundía SplitInBatchesLo usas con confianza
No pensabas en rate limitsCalculas Wait según API
Te perdían datos al fallarManejas errores en loops

Más importante: ahora puedes escalar workflows a volumen real sin temor.

Resumen y siguiente paso

Lo que construiste:

  • Workflow productivo procesando 1000 items
  • Integración de loops, rate limit, retry, agregación, reporting
  • Tasas de éxito típicas y manejo de fallos

Lo que sabes:

  • Estimar tiempo de procesamientos grandes
  • Diseñar loops resilientes
  • Reportar resultados completos al equipo

Antes de pasar a M04:

  • Workflow funcionando con 1000 items (o equivalente)
  • Sheets de output configurados
  • Reporte de Slack recibido
  • Confianza para procesar listas grandes

Lo que sigue (Módulo 4 — Merge Avanzado y Fan-Out/Fan-In):

Hasta acá los workflows han tenido flujo principal lineal con iteraciones. M04 te enseña flujos paralelos: dividir el procesamiento en N caminos simultáneos (fan-out), procesar cada uno, y combinar resultados (fan-in). Es lo que necesitas cuando un workflow consulta múltiples APIs en paralelo y combina sus respuestas, o cuando procesa categorías distintas que terminan en un reporte único.

Recursos adicionales

  1. Mockaroo - Para generar datos fake de prueba.
  2. Beeceptor - Para mockear API endpoints.
  3. Clearbit Enrichment API - API real de enrichment (free tier limitado).

Creado: Mayo 11, 2026 Versión: 1.0

← AnteriorLoops Complejos: Paginación y Patrones AvanzadosSiguiente →Introducción al Módulo: Merge Avanzado y Fan-Out/Fan-In