# WAAS API - Referência completa

**Baileys 7.0.0-rc13**  
**URL base:** `https://apiwpp.audreynogueira.com/api/v1`

A WAAS gerencia várias sessões do WhatsApp, QR dinâmico, envio e acompanhamento de mensagens, grupos, contatos, webhooks, usuários, planos e as capacidades públicas disponíveis no socket Baileys.

> **API não oficial.** Esta integração não é afiliada ao WhatsApp. Use somente com consentimento dos destinatários e respeite os termos aplicáveis.

Envie JSON em UTF-8 com `Content-Type: application/json; charset=utf-8`.

Links úteis:

- Painel: <https://apiwpp.audreynogueira.com/>
- Swagger interativo: <https://apiwpp.audreynogueira.com/docs/>
- OpenAPI JSON: <https://apiwpp.audreynogueira.com/openapi.json>
- Health check: <https://apiwpp.audreynogueira.com/health>

## Autenticação e escopos

Use o JWT retornado pelo login em `Authorization: Bearer TOKEN` ou uma chave em `x-api-key: waas_...`.

```http
POST /api/v1/auth/login
Content-Type: application/json; charset=utf-8

{"email":"seu-email@empresa.com","password":"SUA_SENHA"}
```

```http
Authorization: Bearer SEU_TOKEN
```

Ou:

```http
x-api-key: waas_SUA_CHAVE
```

| Método | Endpoint | Descrição |
|---|---|---|
| POST | `/auth/login` | Autentica e retorna JWT. |
| POST | `/auth/refresh` | Renova um JWT válido. |
| GET | `/auth/me` | Retorna usuário, plano e cota efetiva. |

### Escopos de chave

| Escopo | Permite |
|---|---|
| `*` | Acesso total do usuário. |
| `instances:write` | Criar, editar e excluir instâncias. |
| `instances:connect` | Iniciar, parar, atualizar QR e desvincular. |
| `instances:advanced` | Executor genérico de funções públicas Baileys. |
| `messages:send` | Enviar, editar, reagir e excluir mensagens. |
| `groups:write` | Administrar grupos e participantes. |
| `webhooks:write` | Criar, editar e excluir webhooks. |

## Instâncias, conexão e QR Code

| Método | Endpoint | Descrição |
|---|---|---|
| GET | `/instances` | Lista instâncias do usuário. |
| POST | `/instances` | Cria com `name`, `rejectCalls`, `readMessages`, `markOnline` e `syncFullHistory`. |
| GET | `/instances/:id` | Estado e configuração completos. |
| PATCH | `/instances/:id` | Atualiza nome e preferências. |
| DELETE | `/instances/:id` | Apaga sessão e dados persistidos. |
| POST | `/instances/:id/start` | Inicia ou restaura a conexão. |
| POST | `/instances/:id/stop` | Para sem desvincular. |
| POST | `/instances/:id/logout` | Desvincula o WhatsApp. |
| GET | `/instances/:id/qr` | QR atual, versão, geração, expiração e segundos restantes; sem cache. |
| POST | `/instances/:id/qr/refresh` | Força sessão e QR novos. |
| POST | `/instances/:id/pairing-code` | Pareamento por telefone com `{"phoneNumber":"5511..."}`. |

### Sincronização correta do QR

Consulte `GET /qr` a cada segundo ou acompanhe `instance.qr` por SSE/webhook. Substitua a imagem quando `version` aumentar. O painel executa esse fluxo e detecta a conexão automaticamente.

```json
{
  "dataUrl": "data:image/png;base64,...",
  "status": "QR_CODE",
  "version": 3,
  "generatedAt": "2026-07-16T12:00:00.000Z",
  "expiresAt": "2026-07-16T12:00:55.000Z",
  "secondsRemaining": 41,
  "expired": false
}
```

## Mensagens

| Método | Endpoint | Descrição |
|---|---|---|
| GET | `/instances/:id/messages` | Histórico. Filtros: `chatJid`, `limit`, `page`, `includeRaw`. Inclui metadados de mídia quando aplicável. |
| GET | `/instances/:id/messages/:messageId/media?chatJid=...` | Transmite mídia sob demanda, sem gravar o arquivo no servidor. |
| POST | `/instances/:id/messages/history` | Solicita até 50 mensagens anteriores ao aparelho. |
| POST | `/instances/:id/messages/text` | Envia texto, menções, citação e preview. |
| POST | `/instances/:id/messages/media` | Envia imagem, vídeo, áudio/PTT, documento ou figurinha via HTTPS ou base64. |
| POST | `/instances/:id/messages/contact` | Envia contato em vCard. |
| POST | `/instances/:id/messages/location` | Envia latitude, longitude, nome e endereço. |
| POST | `/instances/:id/messages/poll` | Envia enquete com 2 a 12 opções. |
| POST | `/instances/:id/messages/reaction` | Adiciona ou remove reação. |
| PATCH | `/instances/:id/messages/edit` | Edita mensagem enviada. |
| POST | `/instances/:id/messages/delete` | Apaga para todos. |
| POST | `/instances/:id/messages/read` | Marca chaves como lidas. |
| POST | `/instances/:id/presence` | Define `available`, `unavailable`, `composing`, `recording` ou `paused`. |

Cada instância mantém sua própria caixa, dividida em Contatos, Grupos, Status e Canais/listas. Imagens, vídeos e áudios só são descriptografados quando o operador solicita a visualização.

```http
POST /api/v1/instances/INSTANCE_ID/messages/text
Content-Type: application/json; charset=utf-8

{
  "to": "5511999999999",
  "text": "Olá!",
  "mentions": ["5511888888888"],
  "linkPreview": true
}
```

Destinos aceitam telefone com DDI, JID individual `@s.whatsapp.net` ou grupo `@g.us`. Não existe limite de mensagens na WAAS; a única cota comercial é o número de instâncias.

## Grupos

| Método | Endpoint | Descrição |
|---|---|---|
| GET | `/instances/:id/groups` | Lista grupos participantes. |
| POST | `/instances/:id/groups` | Cria grupo com nome e participantes. |
| GET | `/instances/:id/groups/:jid` | Metadados e participantes. |
| PATCH | `/instances/:id/groups/:jid` | Nome, descrição, anúncios, bloqueio e mensagens temporárias. |
| POST | `/instances/:id/groups/:jid/participants` | Executa `add`, `remove`, `promote` ou `demote`. |
| GET | `/instances/:id/groups/:jid/invite` | Código e URL do convite. |
| POST | `/instances/:id/groups/:jid/invite/revoke` | Revoga o convite. |
| POST | `/instances/:id/groups/join` | Entra por código ou URL. |
| POST | `/instances/:id/groups/:jid/leave` | Sai do grupo. |

## Conversas, contatos e eventos em tempo real

| Método | Endpoint | Descrição |
|---|---|---|
| GET | `/instances/:id/chats` | Conversas individuais e grupos, não lidas e última mensagem. |
| GET | `/instances/:id/contacts` | Contatos sincronizados. |
| GET | `/instances/:id/events` | Log persistido de eventos. |
| GET | `/instances/:id/stream` | Server-Sent Events autenticado em tempo real. |

```js
const response = await fetch('/api/v1/instances/ID/stream', {
  headers: { Authorization: 'Bearer ' + token }
});
// Leia blocos "event: waas" e "data: {...}" de response.body.
```

Eventos disponíveis incluem conexão, QR, mensagens novas/atualizadas/excluídas, confirmações, histórico, contatos, conversas, grupos, participantes, presença, chamadas, etiquetas e credenciais.

## Webhooks assinados

| Método | Endpoint | Descrição |
|---|---|---|
| GET | `/webhooks/events` | Catálogo de eventos. |
| GET | `/webhooks` | Lista endpoints. |
| POST | `/webhooks` | Cria e retorna o segredo uma vez. |
| PATCH | `/webhooks/:id` | Atualiza URL, eventos e estado. |
| DELETE | `/webhooks/:id` | Exclui endpoint e entregas. |

Use `events: ["*"]` para tudo. Entregas têm assinatura HMAC-SHA256 e retentativas automáticas. Guarde o segredo retornado na criação.

```json
{
  "name": "CRM produção",
  "url": "https://seusistema.com/webhooks/waas",
  "events": ["messages.upsert", "instance.connected"],
  "enabled": true
}
```

## Todas as funções públicas do Baileys

| Método | Endpoint | Descrição |
|---|---|---|
| GET | `/instances/:id/capabilities` | Detecta em runtime todas as funções públicas do socket instalado. |
| POST | `/instances/:id/actions/:action` | Executa função pelo nome com `{"args":[]}`. |

O API Lab do painel preenche a lista automaticamente. Funções de protocolo bruto, término interno e logout ficam bloqueadas no executor genérico; use os endpoints seguros dedicados.

```http
POST /api/v1/instances/ID/actions/profilePictureUrl
Content-Type: application/json; charset=utf-8

{"args":["5511999999999@s.whatsapp.net","image"]}
```

## Administração, planos e cotas

| Método | Endpoint | Descrição |
|---|---|---|
| GET | `/dashboard/summary` | Resumo e cota efetiva. |
| GET | `/api-keys` | Lista chaves. |
| POST | `/api-keys` | Gera e exibe o valor uma vez. |
| DELETE | `/api-keys/:id` | Exclui definitivamente. |
| GET | `/admin/users` | Lista usuários (ADMIN). |
| POST | `/admin/users` | Cria com plano e cota individual opcional. |
| PATCH | `/admin/users/:id` | Edita cadastro, plano, status, senha e cota. |
| DELETE | `/admin/users/:id` | Exclui usuário. |
| GET | `/admin/plans` | Lista planos. |
| POST | `/admin/plans` | Cria plano personalizado. |
| PATCH | `/admin/plans/:id` | Edita preço, retenção e máximo de instâncias. |
| DELETE | `/admin/plans/:id` | Exclui plano sem usuários. |
| GET | `/admin/audit` | Auditoria administrativa e avançada. |

A cota efetiva é `instanceQuotaOverride` quando informada; caso contrário, `maxInstances` do plano. Mensagens, chaves e webhooks não têm cota.

## Erros e paginação

| HTTP | Significado |
|---|---|
| 400 | JSON ou parâmetros inválidos. |
| 401 | Credencial ausente, expirada ou revogada. |
| 403 | Escopo insuficiente, usuário suspenso ou recurso ADMIN. |
| 404 | Recurso não encontrado ou QR ainda indisponível. |
| 409 | Conflito, duplicidade, conectado ou limite de instâncias. |
| 429 | Proteção contra excesso de requisições. |
| 500/503 | Falha interna ou socket desconectado. |

Listagens aceitam `?limit=100&offset=0`. Erros usam `{"error":"CODIGO","message":"Descrição"}`.

### cURL com chave de API

```bash
curl -X POST https://apiwpp.audreynogueira.com/api/v1/instances/INSTANCE_ID/messages/text \
  -H "x-api-key: waas_SUA_CHAVE" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"to":"5511999999999","text":"Olá pela WAAS"}'
```

Para executar requisições no navegador, use o [Swagger interativo](https://apiwpp.audreynogueira.com/docs/).