WatsappIntegrations/API_n8n.md

WhatsApp Gateway - API Core para n8n

🎯 COMPONENTE 3: API Core (n8n Integration)

API diseñada específicamente para integración con n8n, completamente desacoplada de Baileys.

---

🔐 Autenticación Bearer Token

Generar Token

POST /api/n8n/generate-token
Content-Type: application/json

{
  "permissions": ["send", "status", "messages"]
}

Respuesta:

{
  "success": true,
  "token": "MTY3Mzk4NzIzNDM2Ny1leGFtcGxlLXRva2Vu",
  "permissions": ["send", "status", "messages"],
  "expiresAt": "2026-01-18T22:43:27.367Z",
  "timestamp": "2026-01-17T22:43:27.367Z"
}

Usar Token

Authorization: Bearer MTY3Mzk4NzIzNDM2Ny1leGFtcGxlLXRva2Vu

---

📤 Enviar Mensajes (n8n → WhatsApp)

Endpoint Principal

POST /api/messages/send
Authorization: Bearer <token>
Content-Type: application/json

{
  "to": "50371234567",
  "message": "Hola desde n8n!"
}

Respuesta:

{
  "success": true,
  "messageId": "3EB0A7B5A234567890ABCDEF",
  "to": "50371234567",
  "message": "Hola desde n8n!",
  "timestamp": "2026-01-17T22:43:27.367Z"
}

Errores

{
  "success": false,
  "to": "50371234567",
  "message": "Hola desde n8n!",
  "timestamp": "2026-01-17T22:43:27.367Z",
  "error": "WhatsApp not connected. Please scan QR code first."
}

---

📥 Recibir Mensajes (WhatsApp → n8n)

Webhook para n8n

POST /webhook/whatsapp
Content-Type: application/json

{
  "from": "50371234567@s.whatsapp.net",
  "body": "Hola desde WhatsApp",
  "timestamp": "2026-01-17T22:43:27.367Z",
  "type": "text",
  "messageId": "3EB0A7B5A234567890ABCDEF"
}

Configurar Webhook

POST /api/webhook/configure
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://tu-n8n-instance.com/webhook/whatsapp",
  "enabled": true
}

---

📊 Ver Estado de Conexión

Estado del Gateway

GET /api/status
Authorization: Bearer <token>

Respuesta:

{
  "success": true,
  "status": "connected",
  "sessionId": "default",
  "uptime": 3600,
  "timestamp": "2026-01-17T22:43:27.367Z",
  "capabilities": {
    "send": true,
    "receive": true,
    "webhook": true
  }
}

---

🌐 Configuración CORS

La API acepta peticiones desde:

• http://localhost:3002 (Manager Web)
• http://localhost:5678 (n8n default)
• http://localhost:5679 (n8n alternative)
• Orígenes personalizados via N8N_ORIGINS env var

---

📋 Formato de Teléfonos

Formatos Soportados

{
  "to": "50371234567",    // ✅ Completo con código de país
  "to": "71234567",       // ✅ Agrega código 503 automáticamente
  "to": "+50371234567",   // ✅ Formato internacional
  "to": "01234567",       // ✅ Quita 0 y agrega 503
  "to": "123"             // ❌ Inválido (demasiado corto)
}

---

🔧 Endpoints de Gestión

Validar Token

POST /api/n8n/token
Authorization: Bearer <token>

Estado del Webhook

GET /api/webhook/status
Authorization: Bearer <token>

Probar Webhook

POST /api/webhook/test
Authorization: Bearer <token>

---

🚀 Integración con n8n

Node HTTP Request (Enviar Mensaje)

Method: POST
URL: http://localhost:3001/api/messages/send
Headers:
  Authorization: Bearer {{token}}
Body (JSON):
{
  "to": "50371234567",
  "message": "Hola desde n8n!"
}

Webhook Trigger (Recibir Mensaje)

Webhook URL: http://localhost:3001/webhook/whatsapp
HTTP Method: POST
Content Type: application/json

---

🔒 Consideraciones de Seguridad

1. Tokens expiran en 24 horas
2. Permisos granulares: send, status, messages
3. Validación de formato de teléfono
4. CORS configurado para n8n
5. Logs estructurados para auditoría

---

📝 Ejemplo Completo de Flujo n8n

1. Generar Token

curl -X POST http://localhost:3001/api/n8n/generate-token \
  -H "Content-Type: application/json" \
  -d '{"permissions": ["send", "status"]}'

2. Enviar Mensaje desde n8n

curl -X POST http://localhost:3001/api/messages/send \
  -H "Authorization: Bearer MTY3Mzk4NzIzNDM2Ny1leGFtcGxlLXRva2Vu" \
  -H "Content-Type: application/json" \
  -d '{"to": "50371234567", "message": "Hola mundo!"}'

3. Recibir Mensaje en n8n

El Gateway enviará automáticamente al webhook configurado cuando llegue un mensaje a WhatsApp.

---

🎯 Perfecto para n8n: API simple, segura, sin dependencias de Baileys.