La idea central

n8n es una herramienta de automatización de flujos de trabajo. La idea es simple: conectar aplicaciones y servicios para que hagan cosas automáticamente, sin que una persona tenga que estar en el medio coordinando.

Imagina que cada vez que llega una factura al email de GMO, alguien tiene que: abrir el email, descargar el PDF, revisar los datos, buscar si existe una OC para esa factura, registrar todo en una planilla y notificar al responsable. Eso es trabajo humano repetitivo. n8n hace exactamente eso, solo, las 24 horas del día, sin errores por cansancio.

Los flujos en n8n se construyen visualmente: arrastra bloques (llamados nodos), los conectas con flechas y defines qué hace cada uno. Un flujo puede ser tan simple como "cuando llegue un email, guárdalo en una planilla", o tan complejo como el M8 que procesa facturas con inteligencia artificial.

Por qué GMO usa n8n

n8n es el sistema nervioso de MOVA. Conecta el frontend HTML (lo que ve el equipo), con Claude (la inteligencia), con Google Workspace (los datos) y con servicios externos (SII, PDFs, APIs). Sin n8n, cada módulo MOVA sería una isla — con n8n, todos hablan entre sí.

n8n vs las alternativas

Anatomía de un flujo

Un flujo en n8n es una secuencia de pasos conectados. Cada paso se llama nodo. Los nodos se conectan de izquierda a derecha: el resultado de uno es la entrada del siguiente.

Todo flujo tiene tres partes:

• Trigger (inicio): Qué dispara el flujo. Puede ser un email nuevo, un webhook, una hora programada, o un clic en el frontend MOVA.
• Proceso (medio): Los pasos que transforman los datos. Aquí viven las llamadas a Claude, las validaciones y las transformaciones.
• Output (fin): Qué pasa con el resultado. Normalmente: escribir en Google Sheets, enviar una notificación, o devolver una respuesta al frontend.

Tipos de nodos

El patrón MOVA

Todos los módulos MOVA que usan Claude siguen el mismo esquema de 3 capas. Entender esto es entender la arquitectura completa de MOVA.

Triggers

Webhook — el más usado en MOVA

Recibe una petición HTTP POST desde el frontend y dispara el flujo. Es la base del patrón MOVA.

// Configuración del nodo Webhook:
HTTP Method: POST
Path: /webhook/nombre-modulo          ← ej: /webhook/m8-egresos
Response Mode: When Last Node Finishes ← devuelve resultado al frontend

// URL pública resultante:
https://grupomakingof.app.n8n.cloud/webhook/nombre-modulo

Schedule Trigger — para procesos periódicos

Dispara el flujo en un horario definido. Para M15 (auditoría semanal) o M7 (descarga mensual del SII).

// Ejemplos de expresión cron:
0 8 * * 1      ← Lunes 8:00 AM (M15)
0 2 1 * *      ← Día 1 de cada mes a las 2AM (M7 SII)
0 7 * * 1-5    ← Lunes a viernes 7AM (briefing AXON)

Email Trigger (IMAP) — para M8

// Nodo: Email Trigger (IMAP)
Host: imap.gmail.com  (o el de GoDaddy para mkof.cl)
Port: 993
Mailbox: INBOX
Action: Mark as read  ← para no procesar 2 veces

HTTP Request

El nodo más versátil de n8n. Llama a cualquier API. En GMO lo usamos principalmente para Claude API y para servicios externos (SII, PDF.co).

// Configuración base para Claude API:
Method: POST
URL: https://api.anthropic.com/v1/messages
Authentication: Header Auth → credencial "Anthropic API"
Headers:
  anthropic-version: 2023-06-01
Body (JSON):
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1000,
  "system": "Tu system prompt",
  "messages": [{
    "role": "user",
    "content": "={{ $json.input }}"
  }]
}
Settings:
  Retry On Fail: ON
  Max Tries: 3
  Wait Between Tries: 2000ms

Lógica e iteración

IF — para bifurcar según el resultado de Claude

// Ejemplo: validar que Claude devolvió JSON antes de parsear
Condición: {{ $json.content[0].text }} contains "{"
Branch TRUE  → nodo JSON Parse → continúa el flujo
Branch FALSE → nodo Set (marca error) → notifica al equipo

Split in Batches + Loop — para M15 y otros batches

// Configuración para 750 URLs:
Batch Size: 1         ← procesa de a 1 para control total
Reset: false          ← mantiene el estado entre iteraciones

// SIEMPRE agregar Wait node después del Split:
Wait: 1200ms          ← = 50 requests/min máximo

Datos e integración

Google Sheets — la base de datos de MOVA

// Leer todas las filas activas:
Operation: Get Many Rows
Sheet ID: [ID del Sheet]
Filters: column "estado" equals "activo"

// Actualizar una fila específica por ID:
Operation: Update Row
Row Number: {{ $json.fila_id }}
Column: estado → "procesado"
Column: fecha_proceso → {{ $now.toISO() }}

Code node — para transformaciones complejas

// Extraer y parsear JSON de respuesta Claude:
const rawText = $input.first().json.content[0].text;
const clean = rawText.replace(/```json|```/g, '').trim();
try {
  const parsed = JSON.parse(clean);
  return [{ json: parsed }];
} catch(e) {
  return [{ json: { error: 'JSON inválido', raw: rawText } }];
}

Configurar el nodo base

Antes de cualquier flujo que use Claude, crea la credencial en n8n:

1. Settings → Credentials → New Credential → Header Auth
2. Name: Anthropic API
3. Header Name: x-api-key
4. Header Value: sk-ant-XXXXXXXX

Una vez creada, la referencias en todos los nodos HTTP Request que llamen a Claude sin volver a pegar la key.

Extraer el texto de la respuesta

// En el nodo siguiente al HTTP Request:
{{ $json.content[0].text }}

// Tokens usados (para monitoreo de costo):
Input:  {{ $json.usage.input_tokens }}
Output: {{ $json.usage.output_tokens }}

Pasar PDFs e imágenes

// Body JSON para PDF adjunto de email:
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1000,
  "system": "Extractor de facturas. Solo JSON válido.",
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "document",
        "source": {
          "type": "base64",
          "media_type": "application/pdf",
          "data": "={{ $binary.data }}"
        }
      },
      {
        "type": "text",
        "text": "Extrae los datos de esta factura."
      }
    ]
  }]
}

Para imágenes: cambia "document" por "image" y "application/pdf" por "image/jpeg" o "image/png".

Batch con Loop (patrón M15)

// Arquitectura completa de un flujo batch:

Google Sheets → [todas las filas]
  ↓
Split In Batches (size: 1)
  ↓
Wait (1200ms)         ← OBLIGATORIO — rate limit
  ↓
HTTP Request → URL del ítem  ← scraping
  ↓
Code → limpia el HTML, extrae texto
  ↓
HTTP Request → Claude API  ← análisis
  ↓
IF → ¿JSON válido?
  ├── TRUE → Google Sheets Update (escribe resultado)
  └── FALSE → Google Sheets Update (marca error)
  ↓
[vuelve al Loop]
  ↓
[fin] → Slack/Email notificación de completado

Parsear el output de Claude

El problema más frecuente en producción: Claude responde con texto envuelto en backticks de markdown. El JSON Parse de n8n falla.

// Code node después del HTTP Request a Claude:
const raw = $input.first().json.content[0].text;

// Limpiar backticks y espacios:
const clean = raw
  .replace(/```json\n?/g, '')
  .replace(/```\n?/g, '')
  .trim();

// Intentar parsear con manejo de error:
try {
  const data = JSON.parse(clean);
  return [{ json: { ...data, _raw_ok: true } }];
} catch (e) {
  // Si falla, devolver el texto crudo para debug:
  return [{ json: { _raw_ok: false, _raw: clean, _error: e.message } }];
}

Luego usa un IF que verifica _raw_ok === true para bifurcar el flujo.

Infraestructura GMO

Regla de los dos entornos

Siempre desarrolla en n8n Cloud primero. Cuando un flujo está probado y estable, se migra al droplet de producción. Nunca experimentes directamente en el droplet — si el flujo falla en producción afecta módulos reales que el equipo está usando.

Errores comunes y solución

Seguridad y credenciales

• API keys siempre en Credentials de n8n — nunca en el body JSON de un nodo, nunca en variables de texto plano, nunca en el código de un nodo Code.
• Webhooks con shared secret — para webhooks que reciben datos desde el frontend MOVA, agrega un header secreto que n8n verifica antes de procesar. Evita que cualquier persona pueda llamar al webhook si conoce la URL.
• Variables de entorno en el droplet — las credenciales más sensibles (cert SII, DB password) van en variables de entorno del sistema, no dentro de n8n.
• Google OAuth restringido a @mkof.cl — las integraciones con Google Workspace solo permiten autenticación con cuentas del dominio GMO.

// Shared secret en webhook MOVA:
// En el nodo Webhook de n8n, agregar validación:
Header: X-MOVA-Secret
Value: {{ $env.MOVA_WEBHOOK_SECRET }}

// En el frontend HTML:
headers: {
  'Content-Type': 'application/json',
  'X-MOVA-Secret': '[valor del secret]'
}

URLs y endpoints GMO

Snippets de código

Fetch desde frontend al webhook n8n

async function llamarMOVA(endpoint, datos) {
  const res = await fetch(
    `https://grupomakingof.app.n8n.cloud/webhook/${endpoint}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-MOVA-Secret': '[secret]'
    },
    body: JSON.stringify(datos)
  });
  return await res.json();
}

Limpiar y parsear output de Claude

const raw = $input.first().json.content[0].text;
const clean = raw.replace(/```json\n?|```\n?/g, '').trim();
try {
  return [{ json: JSON.parse(clean) }];
} catch(e) {
  return [{ json: { _error: true, _raw: clean } }];
}

Google Sheets: update de fila por número

// Nodo Google Sheets:
Operation: Update Row
Spreadsheet: [ID del Sheet]
Sheet: BBDD Egresos
Row Number: {{ $json.fila_numero }}
Columns: estado = "procesado", fecha = {{ $now.toFormat('yyyy-MM-dd') }}

Tabla de errores rápida