API de Instâncias

Documentação completa dos endpoints para gerenciar instâncias WhatsApp.

Visão Geral

Uma instância representa uma conexão individual com o WhatsApp. Cada instância mantém sua própria sessão, autenticação e configurações independentes.

Importante: A maioria das rotas identifica a instância automaticamente através do header apikey (token da instância). Apenas rotas administrativas usam :instanceId na URL e exigem a GLOBAL_API_KEY configurada no ambiente.

Endpoints Disponíveis

Gerenciamento Básico (Administrativo - usa GLOBAL_API_KEY)

POST /instance/create - Criar nova instância
GET /instance/all - Listar todas as instâncias
GET /instance/info/:instanceId - Informações da instância
DELETE /instance/delete/:instanceId - Deletar instância

Conexão (usa token da instância)

POST /instance/connect - Conectar via QR Code
GET /instance/qr - Obter QR Code
POST /instance/pair - Conectar via código de pareamento
GET /instance/status - Status da conexão
POST /instance/disconnect - Desconectar
POST /instance/reconnect - Reconectar
DELETE /instance/logout - Fazer logout

Gerenciamento Avançado (Administrativo - usa GLOBAL_API_KEY)

POST /instance/proxy/:instanceId - Configurar proxy
DELETE /instance/proxy/:instanceId - Remover proxy
POST /instance/forcereconnect/:instanceId - Forçar reconexão
GET /instance/logs/:instanceId - Obter logs
GET /instance/:instanceId/advanced-settings - Configurações avançadas
PUT /instance/:instanceId/advanced-settings - Atualizar configurações

Criar Instância

Cria uma nova instância WhatsApp.

Endpoint

POST /instance/create

Headers

Content-Type: application/json
apikey: SUA-GLOBAL-API-KEY

⚠️ Atenção: Esta rota usa a GLOBAL_API_KEY (variável de ambiente), não o token da instância.

Body

{
  "name": "vendas",
  "token": "token-seguro-unico",
  "webhook": "https://seu-servidor.com/webhook",
  "webhookEvents": ["messages.upsert", "connection.update"],
  "proxy": {
    "host": "proxy.exemplo.com",
    "port": "8080",
    "username": "usuario",
    "password": "senha"
  }
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
name	string	✅ Sim	Nome único da instância
token	string	✅ Sim	Token de autenticação da instância
webhook	string	❌ Não	URL para receber webhooks
webhookEvents	array	❌ Não	Eventos específicos para webhook
proxy	object	❌ Não	Configuração de proxy

Resposta Sucesso (200)

{
  "message": "success",
  "data": {
    "name": "vendas",
    "token": "token-seguro-unico",
    "webhook": "https://seu-servidor.com/webhook",
    "status": "created",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

Resposta Erro (400)

{
  "error": "name is required"
}

Exemplo cURL

curl -X POST http://localhost:4000/instance/create   -H "Content-Type: application/json"   -H "apikey: SUA-CHAVE-API"   -d '{
    "name": "vendas",
    "token": "meu-token-seguro"
  }'

Conectar Instância

Inicia o processo de conexão via QR Code.

Endpoint

POST /instance/connect

Headers

Content-Type: application/json
apikey: TOKEN-DA-INSTANCIA

⚠️ Atenção: Use o token que você definiu ao criar a instância, NÃO a GLOBAL_API_KEY.

Body

{
  "webhookUrl": "https://seu-servidor.com/webhook",
  "subscribe": ["messages.upsert", "connection.update"]
}

Resposta Sucesso (200)

{
  "message": "success",
  "data": {
    "jid": "5511999999999@s.whatsapp.net",
    "webhookUrl": "https://seu-servidor.com/webhook",
    "eventString": "messages.upsert,connection.update"
  }
}

Exemplo cURL

curl -X POST http://localhost:4000/instance/connect \
  -H "Content-Type: application/json" \
  -H "apikey: token-da-instancia-vendas" \
  -d '{
    "webhookUrl": "https://seu-servidor.com/webhook",
    "subscribe": ["messages.upsert"]
  }'

Obter QR Code

Retorna o QR Code para escanear com WhatsApp.

Endpoint

GET /instance/qr

Headers

apikey: TOKEN-DA-INSTANCIA

Importante: A instância é identificada automaticamente pelo token no header.

Resposta Sucesso (200)

{
  "message": "success",
  "data": {
    "qrcode": "2@abcd1234...",
    "code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

Exemplo cURL

curl "http://localhost:4000/instance/qr" \
  -H "apikey: token-da-instancia-vendas"

Conectar via Código de Pareamento

Conecta usando código de 8 dígitos em vez de QR Code.

Endpoint

POST /instance/pair

Headers

Content-Type: application/json
apikey: TOKEN-DA-INSTANCIA

Body

{
  "phone": "5511999999999"
}

Resposta Sucesso (200)

{
  "message": "success",
  "data": {
    "code": "12345678"
  }
}

Como Usar

Faça a requisição com seu número
Receba o código de 8 dígitos
No WhatsApp: Aparelhos conectados > Conectar dispositivo > Conectar com número de telefone
Digite o código recebido

Exemplo cURL

curl -X POST http://localhost:4000/instance/pair \
  -H "Content-Type: application/json" \
  -H "apikey: token-da-instancia-vendas" \
  -d '{"phone": "5511999999999"}'

Status da Conexão

Verifica o status atual da instância.

Endpoint

GET /instance/status

Headers

apikey: TOKEN-DA-INSTANCIA

Resposta Sucesso (200)

{
  "message": "success",
  "data": {
    "connected": true,
    "loggedIn": true,
    "name": "Minha Empresa",
    "myJid": "5511999999999@s.whatsapp.net"
  }
}

Status Possíveis

connected: false, loggedIn: false - Instância criada mas não conectada
connected: true, loggedIn: false - Conectando (aguardando QR Code)
connected: true, loggedIn: true - Conectado e ativo
connected: false, loggedIn: true - Sessão válida mas desconectado temporariamente

Exemplo cURL

curl "http://localhost:4000/instance/status" \
  -H "apikey: token-da-instancia-vendas"

Listar Todas as Instâncias

Retorna todas as instâncias cadastradas.

Endpoint

GET /instance/all

Headers

apikey: SUA-GLOBAL-API-KEY

⚠️ Atenção: Esta rota usa a GLOBAL_API_KEY (administrativa).

Resposta Sucesso (200)

{
  "message": "success",
  "data": [
    {
      "id": "abc123",
      "name": "vendas",
      "connected": true,
      "jid": "5511999999999@s.whatsapp.net"
    },
    {
      "id": "def456",
      "name": "suporte",
      "connected": false,
      "jid": null
    }
  ]
}

Exemplo cURL

curl "http://localhost:4000/instance/all" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Informações da Instância

Obtém informações detalhadas de uma instância específica.

Endpoint

GET /instance/info/:instanceId

Headers

apikey: SUA-GLOBAL-API-KEY

⚠️ Atenção: Esta rota usa a GLOBAL_API_KEY (administrativa) e o ID da instância no path.

Resposta Sucesso (200)

{
  "message": "success",
  "data": {
    "id": "abc123",
    "name": "vendas",
    "token": "token-seguro",
    "webhook": "https://seu-servidor.com/webhook",
    "events": "messages.upsert,connection.update",
    "connected": true,
    "jid": "5511999999999@s.whatsapp.net",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

Exemplo cURL

curl "http://localhost:4000/instance/info/vendas" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Desconectar Instância

Desconecta a instância mas mantém os dados.

Endpoint

POST /instance/disconnect

Headers

apikey: TOKEN-DA-INSTANCIA

Body

{}

Nota: O body pode ser vazio. A instância é identificada pelo header apikey.

Resposta Sucesso (200)

{
  "message": "success"
}

Exemplo cURL

curl -X POST http://localhost:4000/instance/disconnect \
  -H "Content-Type: application/json" \
  -H "apikey: token-da-instancia-vendas" \
  -d '{}'

Reconectar Instância

Reconecta uma instância desconectada.

Endpoint

POST /instance/reconnect

Headers

apikey: TOKEN-DA-INSTANCIA

Body

{}

Resposta Sucesso (200)

{
  "message": "success"
}

Exemplo cURL

curl -X POST http://localhost:4000/instance/reconnect \
  -H "Content-Type: application/json" \
  -H "apikey: token-da-instancia-vendas" \
  -d '{}'

Logout

Faz logout completo, removendo a sessão WhatsApp.

Endpoint

DELETE /instance/logout

Headers

apikey: TOKEN-DA-INSTANCIA

Body

{}

Resposta Sucesso (200)

{
  "message": "success"
}

⚠️ Atenção: Após logout, será necessário escanear QR Code novamente.

Exemplo cURL

curl -X DELETE http://localhost:4000/instance/logout \
  -H "Content-Type: application/json" \
  -H "apikey: token-da-instancia-vendas" \
  -d '{}'

Deletar Instância

Remove completamente a instância e todos os seus dados.

Endpoint

DELETE /instance/delete/:instanceId

Headers

apikey: SUA-GLOBAL-API-KEY

⚠️ Atenção: Esta rota usa a GLOBAL_API_KEY (administrativa). Esta ação é irreversível!

Resposta Sucesso (200)

{
  "message": "success"
}

Exemplo cURL

curl -X DELETE "http://localhost:4000/instance/delete/vendas" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Configurar Proxy

Configura proxy HTTP para a instância.

Endpoint

POST /instance/proxy/:instanceId

Headers

Content-Type: application/json
apikey: SUA-GLOBAL-API-KEY

Body

{
  "host": "proxy.exemplo.com",
  "port": "8080",
  "username": "usuario",
  "password": "senha"
}

Resposta Sucesso (200)

{
  "message": "success",
  "data": {
    "host": "proxy.exemplo.com",
    "port": "8080",
    "hasAuth": true
  }
}

Exemplo cURL

curl -X POST "http://localhost:4000/instance/proxy/vendas" \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-GLOBAL-API-KEY" \
  -d '{
    "host": "proxy.exemplo.com",
    "port": "8080",
    "username": "usuario",
    "password": "senha"
  }'

Remover Proxy

Remove configuração de proxy da instância.

Endpoint

DELETE /instance/proxy/:instanceId

Headers

apikey: SUA-GLOBAL-API-KEY

Resposta Sucesso (200)

{
  "message": "success"
}

Exemplo cURL

curl -X DELETE "http://localhost:4000/instance/proxy/vendas" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Forçar Reconexão

Força reconexão com número específico (útil para resolver problemas).

Endpoint

POST /instance/forcereconnect/:instanceId

Headers

Content-Type: application/json
apikey: SUA-GLOBAL-API-KEY

Body

{
  "number": "5511999999999"
}

Resposta Sucesso (200)

{
  "message": "success"
}

Exemplo cURL

curl -X POST "http://localhost:4000/instance/forcereconnect/vendas" \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-GLOBAL-API-KEY" \
  -d '{"number": "5511999999999"}'

Obter Logs

Obtém logs da instância.

Endpoint

GET /instance/logs/:instanceId?start_date=DATA&end_date=DATA&level=NIVEL&limit=N

Headers

apikey: SUA-GLOBAL-API-KEY

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
start_date	string	❌ Não	Data inicial (YYYY-MM-DD)
end_date	string	❌ Não	Data final (YYYY-MM-DD)
level	string	❌ Não	Nível do log (INFO, DEBUG, ERROR)
limit	integer	❌ Não	Número de registros (padrão: 100)

Resposta Sucesso (200)

[
  {
    "timestamp": "2025-01-15T10:30:00Z",
    "level": "INFO",
    "message": "Instance connected successfully",
    "instanceId": "vendas"
  }
]

Exemplo cURL

curl "http://localhost:4000/instance/logs/vendas?start_date=2025-01-01&limit=50" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Configurações Avançadas

Obter Configurações

GET /instance/:instanceId/advanced-settings

Headers

apikey: SUA-GLOBAL-API-KEY

Resposta (200)

{
  "rejectCall": false,
  "msgCall": "Não estou disponível para chamadas",
  "groupsIgnore": true,
  "alwaysOnline": false,
  "readMessages": false,
  "readStatus": false,
  "syncFullHistory": false
}

Atualizar Configurações

PUT /instance/:instanceId/advanced-settings

Headers

Content-Type: application/json
apikey: SUA-GLOBAL-API-KEY

Body

{
  "rejectCall": true,
  "msgCall": "Por favor, envie mensagem",
  "groupsIgnore": false,
  "alwaysOnline": true,
  "readMessages": true,
  "readStatus": true,
  "syncFullHistory": false
}

Exemplo cURL

curl -X PUT "http://localhost:4000/instance/vendas/advanced-settings" \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-GLOBAL-API-KEY" \
  -d '{
    "rejectCall": true,
    "alwaysOnline": true
  }'

Fluxo Completo de Uso

1. Criar Instância (Administrativo)

curl -X POST http://localhost:4000/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-GLOBAL-API-KEY" \
  -d '{
    "name": "vendas",
    "token": "token-vendas-123"
  }'

2. Conectar (Usando Token da Instância)

curl -X POST http://localhost:4000/instance/connect \
  -H "Content-Type: application/json" \
  -H "apikey: token-vendas-123" \
  -d '{
    "webhookUrl": "https://meu-servidor.com/webhook",
    "subscribe": ["messages.upsert"]
  }'

3. Obter QR Code

curl "http://localhost:4000/instance/qr" \
  -H "apikey: token-vendas-123"

4. Escanear QR Code com WhatsApp

Abra o WhatsApp → Aparelhos conectados → Conectar um aparelho → Escanear QR Code

5. Verificar Status

curl "http://localhost:4000/instance/status" \
  -H "apikey: token-vendas-123"

Boas Práticas

1. Gestão de Tokens

GLOBAL_API_KEY:

Use para rotas administrativas (criar, deletar, listar instâncias)
Mantenha em segredo (variável de ambiente)
Nunca exponha em código frontend
Rotacione periodicamente

Token da Instância:

Defina ao criar a instância (token no body)
Use para operações da instância específica (enviar mensagens, obter status)
Um token único por instância
Use UUIDs: uuidgen ou python3 -c "import uuid; print(uuid.uuid4())"

2. Nome de Instância

Use nomes descritivos e únicos
Apenas letras, números e hífen
Exemplo: vendas-empresa, suporte-01

3. Webhooks

Configure webhook para receber eventos em tempo real
Use HTTPS em produção
Valide os eventos recebidos
Retorne status 200 rapidamente

4. Gerenciamento

Monitore o status das instâncias regularmente
Configure reconexão automática se necessário
Mantenha logs para debug
Use configurações avançadas conforme necessário

Erros Comuns

"not authorized"

Causa: API key incorreta ou ausente Solução:

Rotas administrativas: Use GLOBAL_API_KEY
Rotas de operação: Use token da instância

"instance not found"

Causa: Instância não existe ou token incorreto Solução: Verifique se a instância foi criada e se está usando o token correto

"name is required"

Causa: Campo obrigatório não enviado Solução: Inclua todos os campos obrigatórios no body

QR Code Expira

Causa: QR Code tem validade de ~40 segundos Solução: Use /instance/reconnect para gerar novo QR

"session already logged in"

Causa: Tentou obter QR Code de instância já conectada Solução: Instância já está conectada, não precisa de QR Code

Próximos Passos

API de Mensagens - Enviar diferentes tipos de mensagens
API de Usuários - Gerenciar perfil e contatos
Sistema de Eventos - Webhooks e eventos
Configuração - Variáveis de ambiente

Dica: Use o Swagger em http://localhost:4000/swagger/index.html para testar os endpoints interativamente!

FilesExpand file tree

api-instances.md

Latest commit

History

api-instances.md

File metadata and controls

API de Instâncias

Visão Geral

Endpoints Disponíveis

Gerenciamento Básico (Administrativo - usa GLOBAL_API_KEY)

Conexão (usa token da instância)

Gerenciamento Avançado (Administrativo - usa GLOBAL_API_KEY)

Criar Instância

Endpoint

Headers

Body

Parâmetros

Resposta Sucesso (200)

Resposta Erro (400)

Exemplo cURL

Conectar Instância

Endpoint

Headers

Body

Resposta Sucesso (200)

Exemplo cURL

Obter QR Code

Endpoint

Headers

Resposta Sucesso (200)

Exemplo cURL

Conectar via Código de Pareamento

Endpoint

Headers

Body

Resposta Sucesso (200)

Como Usar

Exemplo cURL

Status da Conexão

Endpoint

Headers

Resposta Sucesso (200)

Status Possíveis

Exemplo cURL

Listar Todas as Instâncias

Endpoint

Headers

Resposta Sucesso (200)

Exemplo cURL

Informações da Instância

Endpoint

Headers

Resposta Sucesso (200)

Exemplo cURL

Desconectar Instância

Endpoint

Headers

Body

Resposta Sucesso (200)

Exemplo cURL

Reconectar Instância

Endpoint

Headers

Body

Resposta Sucesso (200)

Exemplo cURL

Logout

Endpoint

Headers

Body

Resposta Sucesso (200)

Exemplo cURL

Deletar Instância

Endpoint

Headers

Resposta Sucesso (200)

Exemplo cURL

Configurar Proxy

Endpoint

Headers