# Zapini API — Instâncias

**Versão:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticação

Todos os endpoints requerem um Bearer Token:

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

Gere tokens de API no painel admin em **API Docs → Gerenciar Tokens**.

---

## Instâncias WhatsApp

### GET /instances

Listar todas as instâncias WhatsApp.

**Parâmetros de Consulta:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| status | string | Filtrar por status (connected, disconnected, qr_ready, pending) |

**Resposta:**

```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 detalhes da instância.

---

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

Obter QR Code para conexão com o WhatsApp.

**Resposta:**

```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 o status de conexão da instância.

**Parâmetros de Consulta:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| realtime | boolean | Obter status em tempo real do servidor |

---

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

Retorna estatísticas da instância.

**Resposta:**

```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 a instância WhatsApp.

---

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

Iniciar processo de reconexão.

---

## Endpoints Diretos do WhatsApp (Subdomínio da Instância)

Estes endpoints estão disponíveis **apenas** via URL do subdomínio da instância (`https://instance-{id}.zapini.app`). Eles fornecem acesso direto às operações do WhatsApp com menor latência.

### GET /status

Obter status de conexão em tempo real.

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

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

---

### GET /qr

Obter QR code para autenticação.

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

---

### POST /send-message

Enviar uma mensagem de texto diretamente via WhatsApp.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| number | string | Sim | Número do destinatário (ex: 5511999999999) |
| message | string | Sim | Conteúdo da mensagem |

**Exemplo:**
```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!"
  }'
```

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

---

### POST /send-media

Enviar mídia (imagem, vídeo, áudio, documento).

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| number | string | Sim | Número do destinatário |
| media_url | string | Sim | URL pública do arquivo de mídia |
| media_type | string | Sim | Tipo: image, video, audio, document |
| caption | string | Não | Legenda da mídia |
| filename | string | Não | Nome do arquivo (para documentos) |

---

### POST /send-reaction

Reagir a uma mensagem com um emoji.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| message_id | string | Sim | ID da mensagem no WhatsApp |
| remote_jid | string | Sim | JID do chat |
| emoji | string | Sim | Emoji de reação |

---

### POST /delete-message

Excluir uma mensagem enviada.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| message_id | string | Sim | ID da mensagem no WhatsApp |
| remote_jid | string | Sim | JID do chat |

---

### GET /groups

Listar todos os grupos do WhatsApp.

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

---

### POST /group/create

Criar um novo grupo do WhatsApp.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| subject | string | Sim | Nome do grupo |
| participants | array | Sim | Array de números de telefone |

---

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

Obter detalhes e participantes do grupo.

---

### POST /reconnect

Forçar reconexão com o WhatsApp.

---

### POST /logout

Fazer logout e limpar sessão (requer novo QR scan).

---

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