primer commit

2026-01-17 21:43:47 -06:00
commit c8450ed5a8
40 changed files with 11170 additions and 0 deletions
--- a/API_n8n.md
+++ b/API_n8n.md
@@ -0,0 +1,236 @@
+# 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.**