API de Instâncias

Uma instância representa uma conexão com o WhatsApp. Cada instância pode estar conectada a um número de telefone diferente.

Endpoints

Listar Instâncias

Lista todas as instâncias da sua conta.

GET /v1/whatsapp/instances

Resposta de Sucesso (200)

{
  "success": true,
  "data": [
    {
      "id": "inst_abc123",
      "name": "Atendimento Principal",
      "description": "Instância para atendimento ao cliente",
      "status": "connected",
      "phoneNumber": "+5511999999999",
      "active": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "lastConnection": "2024-01-15T14:22:00Z"
    }
  ]
}

Criar Instância

Cria uma nova instância do WhatsApp.

POST /v1/whatsapp/instances

Corpo da Requisição

{
  "name": "Nova Instância",
  "description": "Descrição opcional",
  "webhookUrl": "https://seu-dominio.com/webhook",
  "webhookEvents": [
    "messages.upsert",
    "messages.update",
    "connection.update"
  ]
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da instância (3-100 caracteres)
description	string	Não	Descrição da instância (máx 500 caracteres)
webhookUrl	string	Não	URL para receber eventos
webhookEvents	array	Não	Lista de eventos para notificar

Eventos Disponíveis

• messages.upsert - Nova mensagem recebida
• messages.update - Mensagem atualizada
• messages.delete - Mensagem deletada
• connection.update - Status de conexão mudou
• qr.update - QR Code atualizado

Resposta de Sucesso (201)

{
  "success": true,
  "data": {
    "id": "inst_xyz789",
    "name": "Nova Instância",
    "status": "initializing",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "webhookUrl": "https://seu-dominio.com/webhook",
    "webhookSecret": "whsec_abcd1234...",
    "createdAt": "2024-01-15T15:00:00Z"
  }
}

Erros Possíveis

• 400 - Dados inválidos
• 403 - Limite de instâncias atingido
• 409 - Nome duplicado

Obter Instância

Retorna detalhes de uma instância específica.

GET /v1/whatsapp/instances/{instanceId}

Resposta de Sucesso (200)

{
  "success": true,
  "data": {
    "id": "inst_abc123",
    "name": "Atendimento Principal",
    "description": "Instância para atendimento ao cliente",
    "status": "connected",
    "phoneNumber": "+5511999999999",
    "active": true,
    "webhookUrl": "https://seu-dominio.com/webhook",
    "webhookEvents": ["messages.upsert", "connection.update"],
    "createdAt": "2024-01-15T10:30:00Z",
    "lastConnection": "2024-01-15T14:22:00Z",
    "statistics": {
      "messagesSent": 1543,
      "messagesReceived": 2104,
      "mediaSize": 104857600
    }
  }
}

Atualizar Instância

Atualiza informações de uma instância.

PUT /v1/whatsapp/instances/{instanceId}

Corpo da Requisição

{
  "name": "Novo Nome",
  "description": "Nova descrição",
  "webhookUrl": "https://novo-webhook.com/endpoint",
  "webhookEvents": ["messages.upsert"]
}

Deletar Instância

Remove permanentemente uma instância.

DELETE /v1/whatsapp/instances/{instanceId}

Cuidado

Esta ação é irreversível! Todos os dados da instância serão perdidos.

Resposta de Sucesso (200)

{
  "success": true,
  "message": "Instance deleted successfully"
}

Ativar/Desativar Instância

Alterna o status ativo/inativo de uma instância.

POST /v1/whatsapp/instances/{instanceId}/toggle

Resposta de Sucesso (200)

{
  "success": true,
  "data": {
    "id": "inst_abc123",
    "active": false,
    "message": "Instance deactivated"
  }
}

Status da Instância

Uma instância pode ter os seguintes status:

Status	Descrição
initializing	Instância criada, aguardando conexão
qr_code	QR Code disponível para escanear
connecting	Conectando ao WhatsApp
connected	Conectado e operacional
disconnected	Desconectado temporariamente
error	Erro na conexão

QR Code

Obter QR Code

Obtém o QR Code para conectar a instância.

GET /v1/whatsapp/instances/{instanceId}/qr

Resposta de Sucesso (200)

{
  "success": true,
  "data": {
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "expiresAt": "2024-01-15T15:05:00Z"
  }
}

Dica

O QR Code expira em 60 segundos. Se expirar, faça uma nova requisição.

Fluxo de Conexão

1. Criar instância - Status: initializing
2. Obter QR Code - Status: qr_code
3. Escanear com WhatsApp - Status: connecting
4. Conexão estabelecida - Status: connected

Webhooks da Instância

Configurar Webhook

POST /v1/whatsapp/instances/{instanceId}/webhook

Corpo da Requisição

{
  "url": "https://seu-dominio.com/webhook",
  "events": ["messages.upsert", "connection.update"]
}

Testar Webhook

Envia um evento de teste para o webhook configurado.

POST /v1/whatsapp/instances/{instanceId}/webhook/test

Resposta de Sucesso (200)

{
  "success": true,
  "data": {
    "status": "sent",
    "response": {
      "statusCode": 200,
      "body": "OK"
    }
  }
}

Limites

Os limites de instâncias dependem do seu plano:

Plano	Máximo de Instâncias
Starter	1
Pro	5
Enterprise	50

Exemplos de Código

Criar e Conectar Instância

Node.js

const axios = require('axios');

async function createAndConnect() {
  const apiKey = 'SUA_API_KEY';
  const baseURL = 'https://api.zapflare.io/v1';
  
  // 1. Criar instância
  const createResponse = await axios.post(
    `${baseURL}/whatsapp/instances`,
    {
      name: 'Minha Instância',
      webhookUrl: 'https://meu-site.com/webhook'
    },
    {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }
  );
  
  const instance = createResponse.data.data;
  console.log('Instância criada:', instance.id);
  console.log('QR Code:', instance.qrCode);
  
  // 2. Aguardar conexão (polling)
  let connected = false;
  while (!connected) {
    await new Promise(resolve => setTimeout(resolve, 5000)); // 5 segundos
    
    const statusResponse = await axios.get(
      `${baseURL}/whatsapp/instances/${instance.id}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );
    
    if (statusResponse.data.data.status === 'connected') {
      connected = true;
      console.log('Conectado!', statusResponse.data.data.phoneNumber);
    }
  }
}

createAndConnect().catch(console.error);

Python

import requests
import time
import qrcode
from io import BytesIO
import base64

def create_and_connect():
    api_key = 'SUA_API_KEY'
    base_url = 'https://api.zapflare.io/v1'
    headers = {'Authorization': f'Bearer {api_key}'}
    
    # 1. Criar instância
    create_response = requests.post(
        f'{base_url}/whatsapp/instances',
        json={
            'name': 'Minha Instância',
            'webhookUrl': 'https://meu-site.com/webhook'
        },
        headers=headers
    )
    
    instance = create_response.json()['data']
    print(f'Instância criada: {instance["id"]}')
    
    # Mostrar QR Code
    qr_data = instance['qrCode'].split(',')[1]
    qr_img = qrcode.make(base64.b64decode(qr_data))
    qr_img.show()
    
    # 2. Aguardar conexão
    connected = False
    while not connected:
        time.sleep(5)
        
        status_response = requests.get(
            f'{base_url}/whatsapp/instances/{instance["id"]}',
            headers=headers
        )
        
        status = status_response.json()['data']['status']
        if status == 'connected':
            connected = True
            phone = status_response.json()['data']['phoneNumber']
            print(f'Conectado! Número: {phone}')

create_and_connect()

Próximos Passos

• Enviar mensagens
• Configurar webhooks
• Gerenciar grupos