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
```http
POST /api/n8n/generate-token
Content-Type: application/json

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

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

### Usar Token
```http
Authorization: Bearer MTY3Mzk4NzIzNDM2Ny1leGFtcGxlLXRva2Vu
```

---

## 📤 **Enviar Mensajes (n8n → WhatsApp)**

### Endpoint Principal
```http
POST /api/messages/send
Authorization: Bearer <token>
Content-Type: application/json

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

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

### Errores
```json
{
  "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
```http
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
```http
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
```http
GET /api/status
Authorization: Bearer <token>
```

**Respuesta:**
```json
{
  "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
```json
{
  "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
```http
POST /api/n8n/token
Authorization: Bearer <token>
```

### Estado del Webhook
```http
GET /api/webhook/status
Authorization: Bearer <token>
```

### Probar Webhook
```http
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
```bash
curl -X POST http://localhost:3001/api/n8n/generate-token \
  -H "Content-Type: application/json" \
  -d '{"permissions": ["send", "status"]}'
```

### 2. Enviar Mensaje desde n8n
```bash
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.**