# GestorStream API - Documentação Completa

## Visão Geral

A API do GestorStream é uma API RESTful completa e profissional que permite integração completa com o sistema de gerenciamento de clientes, servidores, WhatsApp, assinaturas, pagamentos, afiliados e muito mais.

**Base URL:** `https://seu-dominio.com/api/v1`

**Versão:** 1.0.0

**Última atualização:** 2025

## Autenticação

A API utiliza autenticação via Bearer Token (Laravel Sanctum). Existem duas formas de obter um token:

### 1. Login via Email/Senha

```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "usuario@example.com",
  "password": "senha123"
}
```

**Resposta:**
```json
{
  "user": {
    "id": 1,
    "name": "João Silva",
    "email": "usuario@example.com"
  },
  "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

### 2. Token de API (Personal Access Token)

Crie tokens de API na página de perfil, aba "Tokens de API". Estes tokens são ideais para integrações e autenticação de longa duração.

**Uso:**
```http
Authorization: Bearer SEU_TOKEN_AQUI
```

## Rotas Públicas (Não Requerem Autenticação)

### Autenticação Pública

#### POST /v1/auth/login
Realiza login e retorna token de autenticação.

**Rate Limit:** 20 requisições/minuto

**Parâmetros (Body - JSON):**
- `email` (string, obrigatório) - Email do usuário
- `password` (string, obrigatório) - Senha do usuário
- `remember_me` (boolean, opcional) - Se true, token expira em 30 dias; senão, em 24 horas

**Resposta 200:**
```json
{
  "user": {
    "id": 1,
    "name": "João Silva",
    "email": "usuario@example.com",
    "subscription": {...}
  },
  "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2025-01-15T12:00:00Z"
}
```

#### POST /v1/auth/register
Registra novo usuário no sistema.

**Rate Limit:** 20 requisições/minuto

**Parâmetros (Body - JSON):**
- `name` (string, obrigatório, max:255) - Nome do usuário
- `email` (string, obrigatório, email único) - Email do usuário
- `password` (string, obrigatório, min:8) - Senha do usuário
- `password_confirmation` (string, obrigatório) - Confirmação da senha
- `referral_code` (string, opcional) - Código de referência de afiliado

**Resposta 201:**
```json
{
  "user": {
    "id": 1,
    "name": "João Silva",
    "email": "usuario@example.com"
  },
  "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

### Recuperação de Senha

#### POST /v1/password/forgot
Envia email com link para redefinição de senha.

**Rate Limit:** 5 requisições/minuto

**Parâmetros (Body - JSON):**
- `email` (string, obrigatório) - Email do usuário

#### POST /v1/password/reset
Redefine a senha do usuário usando token.

**Rate Limit:** 5 requisições/minuto

**Parâmetros (Body - JSON):**
- `email` (string, obrigatório)
- `token` (string, obrigatório)
- `password` (string, obrigatório, min:8)
- `password_confirmation` (string, obrigatório)

#### POST /v1/password/verify-token
Verifica se o token de redefinição de senha é válido.

**Parâmetros (Body - JSON):**
- `email` (string, obrigatório)
- `token` (string, obrigatório)

### Outras Rotas Públicas

#### GET /v1/terms
Obtém os termos de serviço do sistema.

#### GET /v1/system-settings/system_name
Obtém o nome do sistema (para páginas de login/registro).

**Resposta:**
```json
{
  "success": true,
  "data": {
    "value": "GestorStream"
  }
}
```

#### GET /v1/setup/check
Verifica se o sistema já foi configurado (se existe usuário admin).

**Rate Limit:** 30 requisições/minuto

#### POST /v1/setup/create
Cria o primeiro usuário admin (apenas se sistema não configurado).

**Rate Limit:** 5 requisições/minuto

#### GET /v1/plans
Lista todos os planos disponíveis (público).

#### GET /v1/version
Obtém a versão do sistema.

**Resposta:**
```json
{
  "version": "v1.0.0",
  "timestamp": "2025-01-15T12:00:00Z",
  "timezone": "America/Sao_Paulo"
}
```

#### GET /v1/openapi.json
Retorna a especificação OpenAPI 3.0 da API.

#### GET /api/documentation
Retorna a documentação interativa Swagger UI.

## Endpoints Autenticados (Requerem Bearer Token)

### Autenticação

#### GET /v1/auth/me
Obtém informações do usuário autenticado.

**Resposta:**
```json
{
  "id": 1,
  "name": "João Silva",
  "email": "usuario@example.com",
  "subscription": {...}
}
```

#### PUT /v1/auth/me
Atualiza o perfil do usuário autenticado.

**Parâmetros (Body - JSON):**
- `name` (string, opcional, max:255)
- `email` (string, opcional, email único)
- `password` (string, opcional, min:8)
- `password_confirmation` (string, obrigatório se password fornecido)
- `avatar` (file, opcional) - Arquivo de imagem

#### POST /v1/auth/logout
Faz logout e revoga o token atual.

### Gerenciamento de Tokens de API

#### GET /v1/api-tokens
Lista todos os tokens de API do usuário.

#### POST /v1/api-tokens
Cria um novo token de API.

**Parâmetros (Body - JSON):**
- `name` (string, obrigatório) - Nome do token
- `abilities` (array, opcional) - Permissões do token (padrão: ["*"])

#### DELETE /v1/api-tokens/{id}
Exclui um token de API específico.

#### POST /v1/api-tokens/revoke-all
Revoga todos os tokens de API do usuário.

### Clientes

#### GET /v1/clients
Lista clientes do usuário com filtros e paginação.

**Parâmetros (Query String):**
- `status` (string, opcional) - Filtrar por status: `active`, `inactive`, `expired`, `suspended`
- `server_id` (integer, opcional) - Filtrar por ID do servidor
- `expiring_soon` (integer, opcional) - Clientes expirando em X dias
- `expires_at` (date, opcional) - Filtrar por data de expiração específica (formato: YYYY-MM-DD)
- `expires_from` (date, opcional) - Data inicial do intervalo de expiração
- `expires_to` (date, opcional) - Data final do intervalo de expiração
- `q` (string, opcional) - Busca textual (nome, username, whatsapp, servidor)
- `sort_by` (string, opcional) - Campo para ordenação: `id`, `name`, `username`, `whatsapp`, `status`, `expires_at`, `valor_mensalidade`, `created_at`, `updated_at`, `server_id` (padrão: `expires_at`)
- `sort_dir` (string, opcional) - Direção da ordenação: `asc`, `desc` (padrão: `asc`)
- `per_page` (integer, opcional) - Itens por página (1-200, padrão: 50)
- `limit` (integer, opcional) - Alias para `per_page`

**Resposta:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "João Silva",
      "username": "joao123",
      "whatsapp": "5511999999999",
      "status": "active",
      "expires_at": "2025-12-31T23:59:59Z",
      "valor_mensalidade": 29.90,
      "screens": 1,
      "server": {
        "id": 1,
        "name": "Servidor Principal"
      }
    }
  ],
  "current_page": 1,
  "per_page": 50,
  "total": 100
}
```

#### GET /v1/clients/{id}
Obtém detalhes de um cliente específico.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do cliente

#### POST /v1/clients
Cria um novo cliente.

**Parâmetros (Body - JSON):**
- `name` (string, obrigatório) - Nome do cliente
- `server_id` (integer, obrigatório) - ID do servidor
- `username` (string, opcional) - Nome de usuário
- `password` (string, opcional) - Senha
- `whatsapp` (string, opcional) - Número do WhatsApp
- `valor_mensalidade` (numeric, opcional) - Valor da mensalidade
- `expires_at` (date, opcional) - Data de expiração (formato: YYYY-MM-DD)
- `screens` (integer, opcional, padrão: 1) - Número de telas

**Resposta 201:**
```json
{
  "id": 1,
  "name": "João Silva",
  "server_id": 1,
  "username": "joao123",
  "status": "active",
  "created_at": "2025-01-15T12:00:00Z"
}
```

#### PUT /v1/clients/{id}
Atualiza um cliente existente.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do cliente

**Parâmetros (Body - JSON):** (todos opcionais, mesmos campos do POST)

#### DELETE /v1/clients/{id}
Exclui um cliente.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do cliente

#### POST /v1/clients/{id}/renew
Renova um cliente (estende data de expiração).

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do cliente

**Parâmetros (Body - JSON):**
- `days` (integer, opcional) - Número de dias para adicionar (padrão: 30)

#### GET /v1/clients/export
Exporta clientes para CSV.

**Parâmetros (Query String):** (mesmos filtros do GET /clients)

**Resposta:** Arquivo CSV

#### GET /v1/clients/import/template
Obtém template CSV para importação.

#### POST /v1/clients/import/analyze
Analisa arquivo CSV antes da importação.

**Parâmetros (Body - Form Data):**
- `file` (file, obrigatório) - Arquivo CSV

#### POST /v1/clients/import
Importa clientes de arquivo CSV.

**Parâmetros (Body - Form Data):**
- `file` (file, obrigatório) - Arquivo CSV
- `skip_errors` (boolean, opcional) - Continuar mesmo com erros

### Servidores

#### GET /v1/servers
Lista todos os servidores do usuário.

**Resposta:**
```json
{
  "servers": [
    {
      "id": 1,
      "name": "Servidor Principal",
      "url": "https://servidor.com",
      "active": true,
      "credits_balance": 1000,
      "clients_count": 50
    }
  ]
}
```

#### GET /v1/servers/{id}
Obtém detalhes de um servidor específico.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do servidor

#### POST /v1/servers
Cria um novo servidor.

**Parâmetros (Body - JSON):**
- `name` (string, obrigatório, max:255) - Nome do servidor
- `contact_name` (string, opcional, max:255) - Nome do contato
- `contact_whatsapp` (string, opcional, max:20, regex: /^[0-9]+$/) - WhatsApp do contato
- `panel_url` (string, opcional, url, max:500) - URL do painel
- `panel_username` (string, opcional, max:255) - Username do painel
- `panel_password` (string, opcional, max:255) - Senha do painel
- `active` (boolean, opcional) - Status ativo/inativo

#### PUT /v1/servers/{id}
Atualiza um servidor existente.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do servidor

**Parâmetros (Body - JSON):** (mesmos campos do POST, todos opcionais)

#### DELETE /v1/servers/{id}
Exclui um servidor.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do servidor

#### POST /v1/servers/{id}/migrate-clients
Migra clientes de um servidor para outro.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do servidor de origem

**Parâmetros (Body - JSON):**
- `target_server_id` (integer, obrigatório) - ID do servidor de destino
- `client_ids` (array, opcional) - IDs dos clientes para migrar (se não fornecido, migra todos)

### WhatsApp

#### GET /v1/whatsapp/my-connections
Lista todas as conexões WhatsApp do usuário.

**Resposta:**
```json
{
  "connections": [
    {
      "id": 1,
      "instance_name": "instance_1",
      "status": "connected",
      "phone_number": "5511999999999",
      "qr_code": null,
      "integration": {...}
    }
  ],
  "total": 1
}
```

#### POST /v1/whatsapp/sync-statuses
Sincroniza status de todas as conexões WhatsApp com a API.

#### POST /v1/whatsapp/connect
Conecta uma nova instância WhatsApp.

**Parâmetros (Body - JSON):**
- `integration_id` (integer, obrigatório) - ID da integração WhatsApp
- `instance_name` (string, obrigatório) - Nome da instância
- `qrcode` (boolean, opcional) - Se true, retorna QR Code

#### POST /v1/whatsapp/disconnect/{id}
Desconecta uma instância WhatsApp.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da conexão

#### DELETE /v1/whatsapp/connections/{id}
Exclui uma conexão WhatsApp.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da conexão

#### GET /v1/whatsapp/status/{id}
Verifica o status de uma conexão WhatsApp.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da conexão

#### POST /v1/whatsapp/refresh-qr/{id}
Atualiza o QR Code de uma conexão.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da conexão

#### POST /v1/whatsapp/restart/{id}
Reinicia uma conexão WhatsApp.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da conexão

#### GET /v1/whatsapp/{id}/pairing-code
Obtém código de pareamento para conexão WhatsApp.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da conexão

#### POST /v1/whatsapp/send-message
Envia uma mensagem WhatsApp.

**Rate Limit:** 60 requisições/minuto

**Parâmetros (Body - JSON):**
- `phone` (string, obrigatório) - Número do WhatsApp (formato: 5511999999999)
- `message` (string, obrigatório) - Texto da mensagem
- `message_type` (string, opcional) - Tipo: `text`, `media`, `audio` (padrão: `text`)
- `connection_id` (integer, opcional) - ID da conexão (usa primeira ativa se não fornecido)

#### POST /v1/whatsapp/send-media
Envia uma mídia via WhatsApp.

**Rate Limit:** 30 requisições/minuto

**Parâmetros (Body - Form Data):**
- `phone` (string, obrigatório) - Número do WhatsApp
- `media` (file, obrigatório) - Arquivo de mídia
- `caption` (string, opcional) - Legenda da mídia
- `connection_id` (integer, opcional) - ID da conexão

#### POST /v1/whatsapp/message/{id}/retry
Tenta reenviar uma mensagem que falhou.

**Rate Limit:** 20 requisições/minuto

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da mensagem

#### GET /v1/whatsapp/messages
Lista histórico de mensagens WhatsApp.

**Parâmetros (Query String):**
- `connection_id` (integer, opcional) - Filtrar por conexão
- `status` (string, opcional) - Filtrar por status
- `page` (integer, opcional) - Página
- `per_page` (integer, opcional) - Itens por página

### Fila de Mensagens WhatsApp

#### GET /v1/whatsapp/queue
Lista mensagens na fila de envio.

**Parâmetros (Query String):**
- `status` (string, opcional) - Filtrar por status: `pending`, `processing`, `sent`, `failed`
- `connection_id` (integer, opcional) - Filtrar por conexão
- `page` (integer, opcional) - Página
- `per_page` (integer, opcional) - Itens por página

#### GET /v1/whatsapp/queue/stats
Obtém estatísticas da fila de mensagens.

**Resposta:**
```json
{
  "total": 100,
  "pending": 50,
  "processing": 10,
  "sent": 35,
  "failed": 5
}
```

#### GET /v1/whatsapp/queue/{id}/logs
Obtém logs de uma mensagem na fila.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da mensagem na fila

#### POST /v1/whatsapp/queue/pause
Pausa o processamento da fila.

#### POST /v1/whatsapp/queue/resume
Retoma o processamento da fila.

#### POST /v1/whatsapp/queue/clear
Limpa mensagens processadas da fila.

**Parâmetros (Body - JSON):**
- `status` (string, opcional) - Status das mensagens a limpar: `sent`, `failed`, `all`

#### DELETE /v1/whatsapp/queue/{id}
Remove uma mensagem da fila.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID da mensagem na fila

### Assinaturas

#### GET /v1/subscriptions
Obtém a assinatura atual do usuário (alias: GET /v1/subscriptions/current).

**Resposta:**
```json
{
  "id": 1,
  "plan": {
    "id": 1,
    "name": "Plano Premium",
    "price": 99.90
  },
  "status": "active",
  "starts_at": "2025-01-01T00:00:00Z",
  "expires_at": "2025-01-31T23:59:59Z",
  "whatsapp_connections_purchased": 5
}
```

#### GET /v1/subscriptions/usage
Obtém estatísticas de uso da assinatura.

**Resposta:**
```json
{
  "clients": {
    "used": 45,
    "limit": 100,
    "percentage": 45
  },
  "whatsapp": {
    "used": 3,
    "purchased": 5,
    "percentage": 60
  },
  "servers": {
    "used": 2,
    "limit": 5,
    "percentage": 40
  }
}
```

#### POST /v1/subscriptions/calculate-proration
Calcula proratação para mudança de plano.

**Parâmetros (Body - JSON):**
- `plan_id` (integer, obrigatório) - ID do novo plano
- `effective_date` (date, opcional) - Data de início da mudança

#### POST /v1/subscriptions/renew
Renova a assinatura atual.

#### POST /v1/subscriptions
Cria uma nova assinatura.

**Parâmetros (Body - JSON):**
- `plan_id` (integer, obrigatório) - ID do plano
- `payment_method` (string, opcional) - Método de pagamento

#### POST /v1/subscriptions/extra
Compra instâncias WhatsApp extras.

**Parâmetros (Body - JSON):**
- `quantity` (integer, obrigatório) - Quantidade de instâncias

#### POST /v1/subscriptions/reactivate-from-payment
Reativa assinatura após pagamento aprovado.

### Pagamentos

#### GET /v1/payments
Lista pagamentos do usuário.

**Parâmetros (Query String):**
- `status` (string, opcional) - Filtrar por status
- `page` (integer, opcional) - Página
- `per_page` (integer, opcional) - Itens por página

#### GET /v1/payments/{id}
Obtém detalhes de um pagamento específico.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do pagamento

#### GET /v1/payments/{id}/status
Verifica status atualizado de um pagamento.

**Rate Limit:** 30 requisições/minuto

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do pagamento

### Recargas

#### GET /v1/recharges
Lista recargas do usuário.

**Parâmetros (Query String):**
- `server_id` (integer, opcional) - Filtrar por servidor
- `type` (string, opcional) - Filtrar por tipo: `purchase`, `sale`, `adjustment`, `refund`
- `from_date` (date, opcional) - Data inicial
- `to_date` (date, opcional) - Data final
- `page` (integer, opcional) - Página

#### POST /v1/recharges/purchase
Cria recarga de compra.

**Parâmetros (Body - JSON):**
- `server_id` (integer, obrigatório) - ID do servidor
- `quantity` (integer, obrigatório) - Quantidade
- `unit_price` (numeric, opcional) - Preço unitário
- `client_id` (integer, opcional) - ID do cliente
- `description` (string, opcional, max:500)
- `notes` (string, opcional)

#### POST /v1/recharges
Cria uma recarga (genérico).

**Parâmetros (Body - JSON):**
- `server_id` (integer, obrigatório)
- `type` (string, obrigatório) - `purchase`, `sale`, `adjustment`, `refund`
- `quantity` (integer, obrigatório)
- `unit_price` (numeric, opcional)
- `client_id` (integer, opcional)
- `description` (string, opcional)
- `notes` (string, opcional)

### Relatórios

#### GET /v1/reports/level
Obtém o nível de acesso a relatórios do usuário.

**Resposta:**
```json
{
  "level": "advanced",
  "allowed_endpoints": [...]
}
```

#### GET /v1/reports/overview
Visão geral (nível básico).

#### GET /v1/reports/server-breakdown
Relatório por servidor (nível básico).

#### GET /v1/reports/analytics
Análises e estatísticas (nível padrão).

#### GET /v1/reports/whatsapp
Relatório WhatsApp (nível padrão).

#### GET /v1/reports/clients-detailed
Clientes detalhado (nível avançado).

#### GET /v1/reports/revenue-analysis
Análise de receita (nível avançado).

#### GET /v1/reports/export
Exporta relatórios (nível avançado).

**Parâmetros (Query String):**
- `format` (string, opcional) - Formato: `csv`, `xlsx` (padrão: `csv`)
- `type` (string, opcional) - Tipo de relatório

### Marketing

#### POST /v1/marketing/preview
Visualiza clientes filtrados antes do envio.

**Rate Limit:** 30 requisições/minuto

**Parâmetros (Body - JSON):**
- `filters` (object, opcional) - Filtros de clientes (mesmos filtros do GET /clients)
- `template` (string, opcional) - Template da mensagem

#### POST /v1/marketing/send
Envia campanha de marketing para clientes filtrados.

**Rate Limit:** 10 requisições/minuto

**Parâmetros (Body - JSON):**
- `filters` (object, opcional) - Filtros de clientes
- `message` (string, obrigatório) - Mensagem da campanha
- `media_url` (string, opcional) - URL da mídia
- `template_id` (integer, opcional) - ID do template
- `schedule_at` (datetime, opcional) - Agendar envio

#### POST /v1/marketing/upload-media
Faz upload de mídia para campanha.

**Rate Limit:** 20 requisições/minuto

**Parâmetros (Body - Form Data):**
- `media` (file, obrigatório) - Arquivo de mídia

### MCP (Model Context Protocol)

O GestorStream implementa o protocolo MCP (Model Context Protocol) para permitir que agentes de IA interajam com o sistema através de ferramentas padronizadas.

#### GET /v1/mcp/tools
Lista todas as ferramentas MCP disponíveis.

**Resposta:**
```json
{
  "tools": [
    {
      "name": "list_clients",
      "description": "Lista todos os clientes do usuário com filtros opcionais",
      "inputSchema": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["active", "inactive", "expired", "suspended"]
          },
          "server_id": {"type": "integer"},
          "limit": {"type": "integer", "default": 50}
        }
      }
    }
  ]
}
```

#### POST /v1/mcp/tools/call
Executa uma ferramenta MCP específica.

**Parâmetros (Body - JSON):**
- `tool` (string, obrigatório) - Nome da ferramenta
- `arguments` (object, obrigatório) - Argumentos da ferramenta

**Ferramentas MCP Disponíveis:**

1. **list_clients** - Lista clientes do usuário
   - Argumentos: `status` (string, opcional), `server_id` (integer, opcional), `limit` (integer, opcional, padrão: 50)

2. **get_client** - Obtém detalhes de um cliente
   - Argumentos: `client_id` (integer, obrigatório)

3. **create_client** - Cria um novo cliente
   - Argumentos: `name` (string, obrigatório), `server_id` (integer, obrigatório), `username` (string, opcional), `password` (string, opcional), `whatsapp` (string, opcional), `valor_mensalidade` (number, opcional), `expires_at` (string, formato: date, opcional), `screens` (integer, opcional, padrão: 1)

4. **update_client** - Atualiza um cliente existente
   - Argumentos: `client_id` (integer, obrigatório), outros campos opcionais (mesmos do create_client)

5. **delete_client** - Exclui um cliente
   - Argumentos: `client_id` (integer, obrigatório)

6. **list_servers** - Lista servidores do usuário
   - Argumentos: nenhum

7. **get_server** - Obtém detalhes de um servidor
   - Argumentos: `server_id` (integer, obrigatório)

8. **send_whatsapp_message** - Envia mensagem WhatsApp
   - Argumentos: `client_id` (integer, obrigatório), `message` (string, obrigatório), `message_type` (string, opcional, enum: ["text", "media", "audio"], padrão: "text")

9. **get_statistics** - Obtém estatísticas gerais
   - Argumentos: nenhum

**Exemplo de Requisição:**
```json
{
  "tool": "list_clients",
  "arguments": {
    "status": "active",
    "limit": 10
  }
}
```

**Resposta:**
```json
{
  "error": false,
  "data": [
    {
      "id": 1,
      "name": "João Silva",
      "status": "active",
      "expires_at": "2025-12-31T23:59:59Z"
    }
  ]
}
```

### Logs de Auditoria

#### GET /v1/audit-logs
Lista logs de auditoria do usuário.

**Parâmetros (Query String):**
- `action` (string, opcional) - Filtrar por ação
- `model_type` (string, opcional) - Filtrar por tipo de modelo
- `model_id` (integer, opcional) - Filtrar por ID do modelo
- `page` (integer, opcional) - Página
- `per_page` (integer, opcional) - Itens por página

#### GET /v1/audit-logs/{id}
Obtém detalhes de um log de auditoria.

**Parâmetros (Path):**
- `id` (integer, obrigatório) - ID do log

#### GET /v1/audit-logs/model/by-model
Obtém logs agrupados por modelo.

**Parâmetros (Query String):**
- `model_type` (string, opcional)
- `model_id` (integer, opcional)

#### GET /v1/audit-logs/recent
Obtém logs recentes.

**Parâmetros (Query String):**
- `limit` (integer, opcional, padrão: 20) - Número de logs

#### GET /v1/audit-logs/stats
Obtém estatísticas dos logs.

#### GET /v1/audit-logs/queue/logs
Obtém logs da fila de processamento.

### Templates de Mensagem

#### GET /v1/message-templates
Lista templates de mensagem do usuário.

#### GET /v1/message-templates/{id}
Obtém detalhes de um template.

#### POST /v1/message-templates
Cria um novo template.

**Parâmetros (Body - JSON):**
- `name` (string, obrigatório) - Nome do template
- `content` (string, obrigatório) - Conteúdo do template
- `variables` (array, opcional) - Variáveis disponíveis

#### PUT /v1/message-templates/{id}
Atualiza um template.

#### DELETE /v1/message-templates/{id}
Exclui um template.

#### GET /v1/message-templates-variables
Lista variáveis disponíveis para templates.

### Afiliados (Usuário)

#### GET /v1/affiliates
Obtém informações de afiliado do usuário.

#### GET /v1/affiliates/stats
Obtém estatísticas do afiliado.

#### GET /v1/affiliates/referrals
Lista referências (usuários indicados).

#### GET /v1/affiliates/commissions
Lista comissões do afiliado.

#### GET /v1/affiliates/payouts
Lista saques do afiliado.

#### PUT /v1/affiliates/pix
Atualiza dados PIX para saque.

**Parâmetros (Body - JSON):**
- `pix_key` (string, obrigatório) - Chave PIX
- `pix_key_type` (string, obrigatório) - Tipo: `cpf`, `cnpj`, `email`, `phone`, `random`

### Notificações

#### GET /v1/notifications/settings
Obtém configurações de notificações do usuário.

#### PUT /v1/notifications/settings
Atualiza configurações de notificações.

**Parâmetros (Body - JSON):**
- `telegram_enabled` (boolean, opcional)
- `telegram_bot_token` (string, opcional)
- `telegram_chat_id` (string, opcional)
- `email_enabled` (boolean, opcional)

#### POST /v1/notifications/test-telegram
Testa conexão Telegram.

#### GET /v1/system-notifications
Lista notificações do sistema.

#### GET /v1/system-notifications/unread-count
Obtém contagem de notificações não lidas.

#### POST /v1/system-notifications/{id}/mark-as-read
Marca notificação como lida.

#### POST /v1/system-notifications/mark-all-as-read
Marca todas as notificações como lidas.

### Suporte

#### GET /v1/support/level
Obtém nível de suporte do usuário.

#### GET /v1/support/tickets
Lista tickets de suporte do usuário.

#### GET /v1/support/tickets/{id}
Obtém detalhes de um ticket.

#### POST /v1/support/tickets
Cria um novo ticket de suporte.

**Parâmetros (Body - JSON):**
- `subject` (string, obrigatório) - Assunto
- `message` (string, obrigatório) - Mensagem
- `priority` (string, opcional) - Prioridade: `low`, `medium`, `high`

#### POST /v1/support/tickets/{id}/reply
Adiciona resposta a um ticket.

**Parâmetros (Body - JSON):**
- `message` (string, obrigatório) - Mensagem da resposta

### Anúncios

#### GET /v1/announcements/active
Obtém anúncios ativos.

#### GET /v1/announcements/unread-count
Obtém contagem de anúncios não lidos.

#### POST /v1/announcements/{id}/viewed
Marca anúncio como visualizado.

### Onboarding/Tutorial

#### GET /v1/onboarding/status
Obtém status do onboarding do usuário.

#### POST /v1/onboarding/complete-step
Completa uma etapa do onboarding.

**Parâmetros (Body - JSON):**
- `step` (string, obrigatório) - Nome da etapa

#### POST /v1/onboarding/reset
Reinicia o onboarding.

### Blog

#### GET /v1/blog/posts
Lista posts do blog.

**Parâmetros (Query String):**
- `page` (integer, opcional) - Página
- `per_page` (integer, opcional) - Itens por página

#### GET /v1/blog/posts/{slug}
Obtém detalhes de um post do blog.

**Parâmetros (Path):**
- `slug` (string, obrigatório) - Slug do post

### Informações da API

#### GET /v1/
Obtém informações gerais da API.

#### GET /v1/stats
Obtém estatísticas gerais da API.

## Rotas Administrativas (Requerem Role: Admin)

Todas as rotas administrativas requerem autenticação e role de administrador.

### Gerenciamento de Planos (Admin)

#### GET /v1/admin/plans
Lista todos os planos (admin).

#### POST /v1/admin/plans
Cria um novo plano.

**Parâmetros (Body - JSON):**
- `name` (string, obrigatório, max:255)
- `description` (string, opcional)
- `price` (numeric, obrigatório, min:0)
- `client_limit` (integer, opcional) - null = ilimitado
- `whatsapp_limit` (integer, opcional) - null = ilimitado
- `whatsapp_extra_price` (numeric, obrigatório, min:0)
- `whatsapp_extra_instance_price` (numeric, opcional, min:0)
- `duration_days` (integer, obrigatório, min:1)
- `features` (array, opcional)
- `active` (boolean, opcional)
- `is_popular` (boolean, opcional)
- `servers_limit` (integer, opcional) - null = ilimitado
- `support_level` (string, opcional) - `basic`, `standard`, `premium`, `enterprise`
- `reports_level` (string, opcional) - `basic`, `standard`, `advanced`
- `integrations` (array, opcional)
- `api_requests_limit` (integer, opcional)
- `mcp_enabled` (boolean, opcional)

#### PUT /v1/admin/plans/{id}
Atualiza um plano.

#### DELETE /v1/admin/plans/{id}
Exclui um plano.

#### POST /v1/admin/plans/{id}/migrate
Migra assinantes de um plano para outro.

**Parâmetros (Body - JSON):**
- `target_plan_id` (integer, obrigatório) - ID do plano de destino

#### POST /v1/admin/plans/{id}/toggle-active
Ativa/desativa um plano.

### Gerenciamento de Assinaturas (Admin)

#### GET /v1/admin/subscriptions
Lista todas as assinaturas.

#### GET /v1/admin/subscriptions/stats
Obtém estatísticas de assinaturas.

#### GET /v1/admin/subscriptions/{id}
Obtém detalhes de uma assinatura.

#### PUT /v1/admin/subscriptions/{id}
Atualiza uma assinatura.

#### POST /v1/admin/subscriptions/{id}/cancel
Cancela uma assinatura.

#### POST /v1/admin/subscriptions/{id}/extend
Estende uma assinatura.

**Parâmetros (Body - JSON):**
- `days` (integer, obrigatório) - Número de dias para adicionar

### Gerenciamento de Pagamentos (Admin)

#### GET /v1/admin/payments
Lista todos os pagamentos.

#### GET /v1/admin/payments/{id}
Obtém detalhes de um pagamento.

### Gerenciamento de Usuários (Admin)

#### GET /v1/admin/users
Lista todos os usuários.

#### POST /v1/admin/users
Cria um novo usuário.

#### PUT /v1/admin/users/{id}
Atualiza um usuário.

#### DELETE /v1/admin/users/{id}
Exclui um usuário.

#### GET /v1/admin/users/statistics
Obtém estatísticas de usuários.

#### POST /v1/admin/users/{id}/subscription
Atualiza assinatura de um usuário.

### Gerenciamento de Afiliados (Admin)

#### GET /v1/admin/affiliates
Lista todos os afiliados.

#### GET /v1/admin/affiliates/stats
Obtém estatísticas de afiliados.

#### GET /v1/admin/affiliates/pending
Lista aprovações pendentes.

#### GET /v1/admin/affiliates/{id}
Obtém detalhes de um afiliado.

#### POST /v1/admin/affiliates/{id}/approve
Aprova um afiliado.

#### POST /v1/admin/affiliates/{id}/reject
Rejeita um afiliado.

#### POST /v1/admin/affiliates/{id}/block
Bloqueia um afiliado.

#### POST /v1/admin/affiliates/{id}/unblock
Desbloqueia um afiliado.

#### GET /v1/admin/affiliates/{id}/commissions
Lista comissões de um afiliado.

#### GET /v1/admin/affiliates/{id}/payouts
Lista saques de um afiliado.

#### POST /v1/admin/affiliates/{id}/payout
Cria um saque para um afiliado.

#### POST /v1/admin/affiliates/commissions/{commissionId}/approve
Aprova uma comissão.

#### POST /v1/admin/affiliates/commissions/{commissionId}/invalidate
Invalida uma comissão.

#### GET /v1/admin/affiliates/payouts
Lista todos os saques.

#### POST /v1/admin/affiliates/payouts/{payoutId}/paid
Marca saque como pago.

#### POST /v1/admin/affiliates/payouts/{payoutId}/cancel
Cancela um saque.

### Gerenciamento de Suporte (Admin)

#### GET /v1/admin/support/tickets
Lista todos os tickets de suporte.

#### GET /v1/admin/support/tickets/stats
Obtém estatísticas de tickets.

#### GET /v1/admin/support/tickets/{id}
Obtém detalhes de um ticket.

#### PUT /v1/admin/support/tickets/{id}
Atualiza um ticket.

#### POST /v1/admin/support/tickets/{id}/reply
Adiciona resposta a um ticket.

#### GET /v1/admin/support/settings
Obtém configurações de suporte.

#### POST /v1/admin/support/settings
Atualiza configurações de suporte.

### Anúncios (Admin)

#### GET /v1/admin/announcements
Lista todos os anúncios.

#### POST /v1/admin/announcements
Cria um novo anúncio.

#### GET /v1/admin/announcements/targets
Obtém opções de destinos para anúncios.

#### PUT /v1/admin/announcements/{id}
Atualiza um anúncio.

#### DELETE /v1/admin/announcements/{id}
Exclui um anúncio.

### Configurações do Sistema (Admin)

#### GET /v1/admin/system-settings
Lista todas as configurações do sistema.

#### POST /v1/admin/system-settings/bulk
Atualiza configurações em lote.

### Configurações de Pagamento (Admin)

#### POST /v1/admin/payment-settings/openpix
Atualiza configurações OpenPix.

#### POST /v1/admin/payment-settings/{provider}/test
Testa configuração de gateway de pagamento.

**Parâmetros (Path):**
- `provider` (string, obrigatório) - Provedor: `openpix`, `mercadopago`

#### POST /v1/admin/payment-settings/{provider}/test-webhook
Testa webhook de gateway de pagamento.

### Gateways de Pagamento (Admin)

#### GET /v1/admin/payment-gateways
Lista gateways de pagamento disponíveis.

#### POST /v1/admin/payment-gateways/{gateway}/toggle
Ativa/desativa um gateway de pagamento.

### Integrações WhatsApp (Admin)

#### GET /v1/admin/whatsapp/integrations
Lista integrações WhatsApp.

#### POST /v1/admin/whatsapp/integrations
Cria uma nova integração WhatsApp.

#### PUT /v1/admin/whatsapp/integrations/{id}
Atualiza uma integração WhatsApp.

#### DELETE /v1/admin/whatsapp/integrations/{id}
Exclui uma integração WhatsApp.

#### POST /v1/admin/whatsapp/integrations/{id}/default
Define integração como padrão.

#### POST /v1/admin/whatsapp/integrations/{id}/test
Testa uma integração WhatsApp.

### Armazenamento (Admin)

#### GET /v1/admin/storage/integrations
Lista integrações de armazenamento (MinIO/S3).

#### GET /v1/admin/storage/integrations/active
Obtém integração de armazenamento ativa.

#### POST /v1/admin/storage/integrations
Cria uma nova integração de armazenamento.

#### POST /v1/admin/storage/integrations/test
Testa conexão de armazenamento.

#### DELETE /v1/admin/storage/integrations/{id}
Exclui uma integração de armazenamento.

### Configurações SMTP (Admin)

#### GET /v1/admin/smtp/settings
Obtém configurações SMTP.

#### POST /v1/admin/smtp/settings
Atualiza configurações SMTP.

#### POST /v1/admin/smtp/test
Testa conexão SMTP.

### Termos de Serviço (Admin)

#### GET /v1/admin/terms
Obtém termos de serviço.

#### POST /v1/admin/terms
Atualiza termos de serviço.

**Parâmetros (Body - JSON):**
- `content` (string, obrigatório) - Conteúdo dos termos

### Blog (Admin)

#### GET /v1/admin/blog/posts
Lista posts do blog (admin).

#### GET /v1/admin/blog/posts/{id}
Obtém detalhes de um post (admin).

#### POST /v1/admin/blog/posts
Cria um novo post.

#### PUT /v1/admin/blog/posts/{id}
Atualiza um post.

#### DELETE /v1/admin/blog/posts/{id}
Exclui um post.

#### POST /v1/admin/blog/posts/{id}/toggle-publish
Publica/despublica um post.

### Backup de Banco de Dados (Admin)

#### GET /v1/admin/database/config
Obtém configuração do banco de dados.

#### POST /v1/admin/database/backup
Cria backup do banco de dados.

#### GET /v1/admin/database/backups
Lista backups disponíveis.

#### POST /v1/admin/database/restore
Restaura um backup.

**Parâmetros (Body - JSON):**
- `backup_id` (integer, obrigatório) - ID do backup

#### POST /v1/admin/database/migrate
Executa migrações do banco de dados.

#### GET /v1/admin/database/backup/download
Download de backup.

#### POST /v1/admin/database/backup/upload
Upload de backup.

#### GET /v1/admin/database/auto-backup/settings
Obtém configurações de backup automático.

#### POST /v1/admin/database/auto-backup/settings
Atualiza configurações de backup automático.

### Atualizações do Sistema (Admin)

#### GET /v1/admin/updates/status
Obtém status das atualizações.

#### GET /v1/admin/updates/releases
Lista releases disponíveis.

#### POST /v1/admin/updates/check
Verifica novas atualizações.

#### POST /v1/admin/updates/update/{version}
Atualiza sistema para versão específica.

#### POST /v1/admin/updates/rollback/{version}
Reverte para versão anterior.

#### GET /v1/admin/updates/history
Histórico de atualizações.

#### GET /v1/admin/updates/logs/{id}
Logs de uma atualização.

#### GET /v1/admin/updates/gitea/settings
Obtém configurações Gitea.

#### POST /v1/admin/updates/gitea/settings
Atualiza configurações Gitea.

#### POST /v1/admin/updates/gitea/test
Testa conexão Gitea.

### Dashboard Admin

#### GET /v1/admin/dashboard/system
Dados do sistema para dashboard admin.

#### GET /v1/admin/dashboard/machine
Dados da máquina para dashboard admin.

### Relatórios Admin

#### GET /v1/admin/reports/subscriptions
Relatório de assinaturas (admin).

#### GET /v1/admin/reports/revenue
Relatório de receita (admin).

#### GET /v1/admin/reports/users
Relatório de usuários (admin).

### Telegram (Admin)

#### POST /v1/admin/telegram/set-webhook
Configura webhook do Telegram.

**Parâmetros (Body - JSON):**
- `url` (string, obrigatório) - URL do webhook

### Teste OpenPix (Admin)

#### GET /v1/test-openpix
Testa configuração OpenPix.

## Model Context Protocol (MCP)

O GestorStream implementa o protocolo MCP, permitindo que agentes de IA interajam com o sistema através de ferramentas padronizadas.

### Servidor MCP via stdio

Para usar o servidor MCP com agentes de IA:

```bash
php artisan mcp:server --token=SEU_TOKEN_AQUI
```

O servidor se comunica via stdin/stdout usando JSON-RPC 2.0.

### Protocolo MCP via HTTP

O GestorStream também expõe endpoints HTTP REST para usar ferramentas MCP diretamente via API HTTP.

**Endpoint:** `POST /v1/mcp/tools/call`

**Headers:**
```
Authorization: Bearer SEU_TOKEN
Content-Type: application/json
```

**Body:**
```json
{
  "tool": "list_clients",
  "arguments": {
    "status": "active",
    "limit": 10
  }
}
```

**Resposta:**
```json
{
  "error": false,
  "data": [
    {
      "id": 1,
      "name": "João Silva",
      "status": "active",
      "expires_at": "2025-12-31T23:59:59Z",
      "valor_mensalidade": 29.90,
      "server": {
        "id": 1,
        "name": "Servidor Principal"
      }
    }
  ]
}
```

### Protocolo MCP via JSON-RPC (stdio)

O servidor MCP via stdio usa JSON-RPC 2.0. Exemplo de requisição:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_clients",
    "arguments": {
      "status": "active",
      "limit": 10
    }
  }
}
```

**Resposta:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":false,\"data\":[...]}"
      }
    ]
  }
}
```

### Detalhamento das Ferramentas MCP

#### list_clients
Lista clientes do usuário com filtros opcionais.

**Argumentos:**
- `status` (string, opcional) - Status: `active`, `inactive`, `expired`, `suspended`
- `server_id` (integer, opcional) - Filtrar por servidor
- `limit` (integer, opcional, padrão: 50) - Limite de resultados

**Retorna:** Array de clientes com informações resumidas

#### get_client
Obtém detalhes completos de um cliente específico.

**Argumentos:**
- `client_id` (integer, obrigatório) - ID do cliente

**Retorna:** Objeto com detalhes completos do cliente

#### create_client
Cria um novo cliente no sistema.

**Argumentos:**
- `name` (string, obrigatório) - Nome do cliente
- `server_id` (integer, obrigatório) - ID do servidor
- `username` (string, opcional) - Nome de usuário
- `password` (string, opcional) - Senha
- `whatsapp` (string, opcional) - Número WhatsApp
- `valor_mensalidade` (number, opcional) - Valor mensalidade
- `expires_at` (string, formato: YYYY-MM-DD, opcional) - Data expiração
- `screens` (integer, opcional, padrão: 1) - Número de telas

**Retorna:** Cliente criado com ID e nome

#### update_client
Atualiza um cliente existente.

**Argumentos:**
- `client_id` (integer, obrigatório) - ID do cliente
- Outros campos opcionais (mesmos do create_client)

**Retorna:** Cliente atualizado

#### delete_client
Exclui um cliente do sistema.

**Argumentos:**
- `client_id` (integer, obrigatório) - ID do cliente

**Retorna:** Confirmação de exclusão

#### list_servers
Lista todos os servidores do usuário.

**Argumentos:** Nenhum

**Retorna:** Array de servidores

#### get_server
Obtém detalhes de um servidor específico.

**Argumentos:**
- `server_id` (integer, obrigatório) - ID do servidor

**Retorna:** Objeto com detalhes do servidor incluindo contagem de clientes

#### send_whatsapp_message
Envia uma mensagem WhatsApp para um cliente.

**Argumentos:**
- `client_id` (integer, obrigatório) - ID do cliente
- `message` (string, obrigatório) - Texto da mensagem
- `message_type` (string, opcional) - Tipo: `text`, `media`, `audio` (padrão: `text`)

**Retorna:** Confirmação de enfileiramento

#### get_statistics
Obtém estatísticas gerais do sistema do usuário.

**Argumentos:** Nenhum

**Retorna:** Objeto com estatísticas de clientes, servidores, WhatsApp e receita

## Webhooks

O GestorStream suporta webhooks para integração com serviços externos.

### Webhooks de Pagamento

#### POST /v1/webhooks/openpix
Webhook da OpenPix para notificações de pagamento.

**Headers:**
- `X-OpenPix-Signature` (string, obrigatório) - Assinatura HMAC para validação

**Body:** Payload do OpenPix conforme documentação oficial

#### POST /webhooks/openpix
Webhook OpenPix (rota legada, mantida para compatibilidade).

### Webhook do Telegram

#### POST /v1/webhooks/telegram
Webhook do Telegram para receber mensagens.

**Body:** Payload do Telegram conforme documentação oficial

### Webhook do Gitea

#### POST /v1/webhooks/gitea
Webhook do Gitea para atualizações automáticas do sistema.

**Body:** Payload do Gitea conforme documentação oficial

#### POST /webhooks/gitea
Webhook Gitea (rota legada, mantida para compatibilidade).

## Documentação Interativa

Acesse a documentação interativa Swagger UI em:

**URL:** `/api/documentation`

Ou visualize a especificação OpenAPI em:

**URL:** `/api/v1/openapi.json`

## Códigos de Status HTTP

- `200` - Sucesso
- `201` - Criado com sucesso
- `400` - Requisição inválida
- `401` - Não autenticado
- `403` - Não autorizado
- `404` - Não encontrado
- `422` - Erro de validação
- `500` - Erro interno do servidor

## Rate Limiting

A API implementa rate limiting para proteger contra abuso. Os limites variam por endpoint:

- **Autenticação (login/register):** 20 requisições por minuto
- **Recuperação de senha:** 5 requisições por minuto
- **Setup:** 30 requisições/minuto (check), 5 requisições/minuto (create)
- **WhatsApp - send-message:** 60 requisições por minuto
- **WhatsApp - send-media:** 30 requisições por minuto
- **WhatsApp - retry:** 20 requisições por minuto
- **Marketing - preview:** 30 requisições por minuto
- **Marketing - send:** 10 requisições por minuto
- **Marketing - upload-media:** 20 requisições por minuto
- **Pagamentos - status:** 30 requisições por minuto
- **Endpoints gerais:** Sem limite específico (limitado pelo middleware geral)
- **Endpoints administrativos:** Sem limite específico (limitado por role de admin)

## Exemplos de Uso

### Criar um Cliente

```bash
curl -X POST https://seu-dominio.com/api/v1/clients \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "server_id": 1,
    "username": "joao123",
    "password": "senha123",
    "whatsapp": "5511999999999",
    "valor_mensalidade": 29.90,
    "expires_at": "2025-12-31",
    "screens": 1
  }'
```

### Enviar Mensagem WhatsApp

```bash
curl -X POST https://seu-dominio.com/api/v1/whatsapp/send-message \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "message": "Olá! Esta é uma mensagem de teste.",
    "message_type": "text"
  }'
```

### Usar MCP Tool

```bash
curl -X POST https://seu-dominio.com/api/v1/mcp/tools/call \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_clients",
    "arguments": {
      "status": "active",
      "limit": 10
    }
  }'
```

## Segurança

- Todos os endpoints (exceto login/register) requerem autenticação
- Tokens expiram automaticamente se configurado
- Logs de auditoria registram todas as ações
- Rate limiting protege contra abuso
- Validação rigorosa de entrada
- Sanitização de dados de saída

## Suporte

Para mais informações, entre em contato:
- Email: suporte@gestorstream.com
- Documentação: `/api/documentation`