API: Instances¶

Visão Geral¶

Gerenciamento de instâncias WhatsApp conectadas via Evolution API. Cada instância representa um número de telefone conectado.

Endpoints¶

GET /api/instances¶

Lista todas as instâncias do tenant.

Response (200 OK):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Suporte Principal",
    "sessionId": "suporte-01",
    "phoneNumber": "+5511999998888",
    "status": "Connected",
    "agentId": "660e8400-e29b-41d4-a716-446655440001",
    "agentName": "Suporte TI",
    "aiModelId": "770e8400-e29b-41d4-a716-446655440002",
    "aiModelName": "Claude Sonnet",
    "startsWithAI": true,
    "createdAt": "2024-01-15T10:00:00Z",
    "todayConversations": 25
  }
]

GET /api/instances/{id}¶

Retorna detalhes de uma instância.

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Suporte Principal",
  "sessionId": "suporte-01",
  "phoneNumber": "+5511999998888",
  "status": "Connected",
  "agentId": "660e8400-e29b-41d4-a716-446655440001",
  "agentName": "Suporte TI",
  "aiModelId": "770e8400-e29b-41d4-a716-446655440002",
  "aiModelName": "Claude Sonnet",
  "startsWithAI": true,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-20T14:00:00Z",
  "totalConversations": 500,
  "todayConversations": 25
}

POST /api/instances¶

Cria uma nova instância.

Request:

{
  "name": "Suporte Principal",
  "sessionId": "suporte-01",
  "agentId": "660e8400-e29b-41d4-a716-446655440001"
}

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Suporte Principal",
  "sessionId": "suporte-01"
}

PUT /api/instances/{id}¶

Atualiza uma instância.

Request:

{
  "name": "Suporte Principal v2",
  "agentId": "660e8400-e29b-41d4-a716-446655440001",
  "aiModelId": "770e8400-e29b-41d4-a716-446655440002",
  "startsWithAI": true
}

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Suporte Principal v2"
}

DELETE /api/instances/{id}¶

Remove uma instância.

Response: 204 No Content

POST /api/instances/{id}/connect¶

Conecta a instância ao WhatsApp. Retorna QR code se necessário.

Response (200 OK):

{
  "status": "Connecting",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "pairingCode": null
}

POST /api/instances/{id}/disconnect¶

Desconecta a instância do WhatsApp.

Response (200 OK):

{
  "status": "Disconnected"
}

GET /api/instances/{id}/status¶

Retorna o status atual da conexão.

Response (200 OK):

{
  "status": "Connected",
  "phoneNumber": "+5511999998888",
  "profileName": "Empresa XYZ",
  "profilePictureUrl": "https://pps.whatsapp.net/..."
}

Sub-recursos¶

Whitelist¶

Lista de contatos autorizados. Se vazia, aceita todos.

GET /api/instances/{instanceId}/whitelist¶

[
  {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+5511999887766",
    "contactName": "João - Loja 5",
    "notes": "Gerente da loja",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00Z"
  }
]

POST /api/instances/{instanceId}/whitelist¶

{
  "phoneNumber": "+5511999887766",
  "contactName": "João - Loja 5",
  "notes": "Gerente da loja",
  "isActive": true
}

PUT /api/instances/{instanceId}/whitelist/{id}¶

DELETE /api/instances/{instanceId}/whitelist/{id}¶

Blacklist¶

Lista de contatos bloqueados. Mensagens são ignoradas.

GET /api/instances/{instanceId}/blacklist¶

[
  {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+5511999776655",
    "reason": "Spam",
    "blockedAt": "2024-01-18T14:00:00Z",
    "blockedByName": "Admin"
  }
]

POST /api/instances/{instanceId}/blacklist¶

{
  "phoneNumber": "+5511999776655",
  "reason": "Spam"
}

DELETE /api/instances/{instanceId}/blacklist/{id}¶

Status de Conexão¶

Status	Descrição
Disconnected	Desconectado
Connecting	Conectando (aguardando QR)
Connected	Conectado e operacional
Open	Conexão aberta
Close	Conexão fechada

Lógica de Whitelist/Blacklist¶

Blacklist é verificada primeiro - se número está na blacklist, mensagem é ignorada
Whitelist vazia - aceita qualquer número
Whitelist com entradas - só aceita números listados e ativos

Evolution API¶

A instância corresponde a uma sessão no Evolution API. O sessionId deve ser único e é usado para identificar a sessão.

Criação de Sessão¶

Quando uma instância é criada, a API: 1. Cria a sessão no Evolution via POST /instance/create 2. Salva a instância no banco 3. Sessão fica em status Disconnected

Conexão¶

Quando /connect é chamado: 1. API chama Evolution GET /instance/connect/{sessionId} 2. Evolution retorna QR code 3. Usuário escaneia com WhatsApp 4. Webhook connection.update atualiza status para Connected

Erros Comuns¶

Status	Código	Descrição
404	INSTANCE_NOT_FOUND	Instância não encontrada
409	SESSION_ID_EXISTS	SessionId já em uso
400	EVOLUTION_ERROR	Erro na Evolution API