whatsappNucleo/README.md

# WhatsApp Nucleo

Sistema de gestión centralizada de múltiples instancias de WhatsApp para Nucleo V3.

## MCP Server para Claude Code

Agregar el MCP a tu proyecto (usa tu NUXT_MASTER_API_KEY):

```bash
claude mcp add --transport http whatsapp https://whatsapp.nucleoriofrio.com/api/mcp --header "Authorization: Bearer <NUXT_MASTER_API_KEY>"
```

---

## Setup

```bash
npm install
```

## Development

```bash
npm run dev
```

## Production

```bash
npm run build
node .output/server/index.mjs
```

---

## API REST

### Autenticación

Todos los endpoints requieren autenticación mediante API Key:

```
Authorization: Bearer <NUXT_MASTER_API_KEY>
```

### Instancias

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/api/instances` | Listar todas las instancias |
| POST | `/api/instances` | Crear nueva instancia |
| GET | `/api/instances/:id` | Obtener detalles de instancia |
| GET | `/api/instances/:id/qr` | Obtener código QR |
| POST | `/api/instances/:id/connect` | Conectar instancia |
| POST | `/api/instances/:id/disconnect` | Desconectar instancia |
| DELETE | `/api/instances/:id` | Eliminar instancia |

**Ejemplo - Listar instancias:**
```bash
curl -X GET "https://whatsapp.nucleoriofrio.com/api/instances" \
  -H "Authorization: Bearer <API_KEY>"
```

**Ejemplo - Crear instancia:**
```bash
curl -X POST "https://whatsapp.nucleoriofrio.com/api/instances" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mi WhatsApp"}'
```

### Chats y Contactos

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/api/messages/:instanceId/chats` | Listar todos los chats |
| POST | `/api/messages/:instanceId/new-chat` | Crear nuevo chat |

**Ejemplo - Listar chats:**
```bash
curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/chats" \
  -H "Authorization: Bearer <API_KEY>"
```

**Respuesta:**
```json
[
  {
    "id": "abc123",
    "jid": "5491155551234@s.whatsapp.net",
    "name": "Juan Pérez",
    "isGroup": false,
    "unreadCount": 2,
    "lastMessageAt": "2025-01-15T10:30:00Z"
  }
]
```

### Mensajes

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/api/messages/:instanceId/:chatId` | Obtener mensajes del chat |
| POST | `/api/messages/send` | Enviar mensaje (simple) |
| POST | `/api/messages/:instanceId/:chatId/send` | Enviar mensaje (avanzado) |

**Ejemplo - Obtener mensajes:**
```bash
curl -X GET "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}?limit=50" \
  -H "Authorization: Bearer <API_KEY>"
```

**Ejemplo - Enviar mensaje de texto:**
```bash
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "inst_abc123",
    "to": "5491155551234",
    "message": "Hola! Este es un mensaje de prueba"
  }'
```

**Ejemplo - Enviar imagen:**
```bash
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@imagen.jpg" \
  -F "caption=Descripción de la imagen"
```

**Ejemplo - Enviar documento:**
```bash
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@documento.pdf" \
  -F "caption=Reporte mensual"
```

**Ejemplo - Enviar contacto:**
```bash
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contact",
    "contacts": [{
      "displayName": "Juan Pérez",
      "phoneNumber": "+5491155551234"
    }]
  }'
```

**Ejemplo - Enviar encuesta:**
```bash
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/{chatId}/send" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "poll",
    "name": "¿Qué día prefieres?",
    "options": ["Lunes", "Martes", "Miércoles"],
    "selectableCount": 1
  }'
```

### Reacciones

**Ejemplo - Reaccionar a mensaje:**
```bash
curl -X POST "https://whatsapp.nucleoriofrio.com/api/messages/{instanceId}/react" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "3EB0A1B2C3D4E5F6",
    "emoji": "👍"
  }'
```

**Quitar reacción:** enviar `emoji` como string vacío `""`

### Formato de Destinatarios (JID)

- **Contacto individual:** `5491155551234@s.whatsapp.net` (código país sin +)
- **Grupo:** `123456789012345678@g.us`

### Tipos de Mensaje Soportados

| Tipo | Descripción |
|------|-------------|
| `text` | Mensaje de texto |
| `image` | Imagen con caption opcional |
| `video` | Video con caption opcional |
| `audio` | Audio o nota de voz |
| `document` | Documento/archivo |
| `sticker` | Sticker |
| `contact` | Tarjeta de contacto |
| `poll` | Encuesta (2-12 opciones) |
| `event` | Evento con fecha/ubicación |

### Límites de Archivos

| Tipo | Tamaño Máximo |
|------|---------------|
| Imagen | 16 MB |
| Video | 64 MB |
| Audio | 16 MB |
| Documento | 100 MB |
| Sticker | 500 KB |

---

## Stack

- **Frontend:** Nuxt 3, Vue 3, Nuxt UI, TailwindCSS
- **Backend:** Nitro, PostgreSQL
- **WhatsApp:** Baileys v6.7.9
- **Auth:** Authentik + Traefik