# Zapini API — Instancias

**Versión:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticación

Todos los endpoints requieren un Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Genera tokens de API en el panel admin en **API Docs → Gestionar Tokens**.

---

## Instancias de WhatsApp

### GET /instances

Listar todas las instancias de WhatsApp.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| status | string | Filtrar por estado (connected, disconnected, qr_ready, pending) |

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "instances": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "phone_number": "15551234567",
        "status": "connected",
        "connected": true,
        "messages_sent_today": 50,
        "remaining_quota": 450,
        "can_send_messages": true,
        "last_activity_at": "2025-01-15T10:30:00Z",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ]
  }
}
```

---

### GET /instances/{uuid}

Retorna detalles de la instancia.

---

### GET /instances/{uuid}/qr

Obtener Código QR para conexión con WhatsApp.

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "status": "qr_ready",
    "qr_code": "data:image/png;base64,...",
    "qr_code_text": "2@...",
    "qr_generated_at": "2025-01-15T10:30:00Z",
    "qr_expired": false,
    "message": "QR code ready to scan"
  }
}
```

---

### GET /instances/{uuid}/status

Retorna el estado de conexión de la instancia.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| realtime | boolean | Obtener estado en tiempo real del servidor |

---

### GET /instances/{uuid}/stats

Retorna estadísticas de la instancia.

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "messages_sent_today": 50,
    "remaining_quota": 450,
    "daily_limit": 500,
    "messages_this_week": 200,
    "messages_this_month": 800,
    "messages_received_today": 30,
    "conversations_count": 150,
    "contacts_count": 500,
    "failed_attempts": 0,
    "last_activity_at": "2025-01-15T10:30:00Z"
  }
}
```

---

### POST /instances/{uuid}/disconnect

Desconectar la instancia de WhatsApp.

---

### POST /instances/{uuid}/reconnect

Iniciar proceso de reconexión.

---

## Endpoints Directos de WhatsApp (Subdominio de Instancia)

Estos endpoints están disponibles **solo** vía la URL del subdominio de la instancia (`https://instance-{id}.zapini.app`). Proporcionan acceso directo a las operaciones de WhatsApp con menor latencia.

### GET /status

Obtener estado de conexión en tiempo real.

```bash
curl https://instance-18.zapini.app/status \
  -H "Authorization: Bearer sk_abc123..."
```

**Respuesta:**
```json
{
  "success": true,
  "status": "connected",
  "connected": true,
  "connecting": false,
  "uptime": 3600.5,
  "phoneNumber": "5511999999999",
  "lastHeartbeat": "2025-01-15T10:30:00Z"
}
```

---

### GET /qr

Obtener código QR para autenticación.

**Respuesta:**
```json
{
  "success": true,
  "status": "qr_ready",
  "qr_code": "data:image/png;base64,...",
  "qr_code_text": "2@abc..."
}
```

---

### POST /send-message

Enviar un mensaje de texto directamente vía WhatsApp.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| number | string | Sí | Número del destinatario (ej: 5511999999999) |
| message | string | Sí | Contenido del mensaje |

**Ejemplo:**
```bash
curl -X POST https://instance-18.zapini.app/send-message \
  -H "Authorization: Bearer sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "message": "Hello from the API!"
  }'
```

**Respuesta:**
```json
{
  "success": true,
  "messageId": "3EB0...",
  "timestamp": 1705312200
}
```

---

### POST /send-media

Enviar multimedia (imagen, video, audio, documento).

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| number | string | Sí | Número del destinatario |
| media_url | string | Sí | URL pública del archivo de medios |
| media_type | string | Sí | Tipo: image, video, audio, document |
| caption | string | No | Pie de foto del medio |
| filename | string | No | Nombre del archivo (para documentos) |

---

### POST /send-reaction

Reaccionar a un mensaje con un emoji.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| message_id | string | Sí | ID del mensaje en WhatsApp |
| remote_jid | string | Sí | JID del chat |
| emoji | string | Sí | Emoji de reacción |

---

### POST /delete-message

Eliminar un mensaje enviado.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| message_id | string | Sí | ID del mensaje en WhatsApp |
| remote_jid | string | Sí | JID del chat |

---

### GET /groups

Listar todos los grupos de WhatsApp.

**Respuesta:**
```json
{
  "success": true,
  "groups": [
    {
      "jid": "120363001234567890@g.us",
      "subject": "My Group",
      "participants_count": 15,
      "creation": 1705312200
    }
  ]
}
```

---

### POST /group/create

Crear un nuevo grupo de WhatsApp.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| subject | string | Sí | Nombre del grupo |
| participants | array | Sí | Array de números de teléfono |

---

### GET /group/{jid}/metadata

Obtener detalles y participantes del grupo.

---

### POST /reconnect

Forzar reconexión a WhatsApp.

---

### POST /logout

Cerrar sesión y limpiar sesión (requiere nuevo escaneo de QR).

---

*Generado por Zapini — https://zapini.app*