Como integrar Evolution API ao sistema do escritório contábil

Evolution API é a stack open source mais popular no Brasil para automatizar WhatsApp Business sem depender direto da API oficial da Meta (cara e burocrática). Para escritório contábil que envia centenas de holerites e DARFs por mês, é a opção que combina baixo custo, controle total e auditabilidade. Esse artigo cobre arquitetura, custos e os passos de integração.

Por que Evolution API e não a API oficial

A API oficial WhatsApp Business da Meta exige aprovação de templates, BSP intermediário, custo por sessão e onboarding longo. Para volume médio de escritório (3.000-30.000 mensagens/mês), os provedores baseados em Baileys (Evolution API, Z-API, WPPConnect) costumam custar 10-20x menos e entram no ar em horas.

Trade-off: você assume o risco de banimento de número se mandar conteúdo abusivo. Para envio transacional de documento autorizado pelo cliente, o risco é baixo.

Arquitetura mínima recomendada

Para um escritório típico:

• VPS Linux (2 vCPU, 4 GB RAM) rodando Evolution API via Docker.
• PostgreSQL para persistir sessões e fila.
• Redis para cache e estado.
• Nginx reverse proxy com SSL (Let's Encrypt).
• Webhook receiver no seu sistema para capturar status de mensagens.

Subindo o Evolution via Docker

docker-compose.yml mínimo:

services:
  evolution:
    image: atendai/evolution-api:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_PROVIDER=postgresql
      - DATABASE_CONNECTION_URI=postgresql://user:pass@postgres:5432/evolution
      - REDIS_URI=redis://redis:6379
      - AUTHENTICATION_API_KEY=sua-chave-secreta-longa
      - WEBHOOK_GLOBAL_URL=https://seu-sistema.com/webhook/whatsapp
    depends_on: [postgres, redis]
  postgres:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=evolution
    volumes: ["postgres-data:/var/lib/postgresql/data"]
  redis:
    image: redis:7-alpine
    volumes: ["redis-data:/data"]
volumes: { postgres-data: {}, redis-data: {} }

Conectando uma instância (número WhatsApp)

Cada número conectado vira uma "instância". Você cria via REST:

curl -X POST https://evo.seudominio.com/instance/create \
  -H "apikey: sua-chave-secreta-longa" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "escritorio-principal",
    "qrcode": true,
    "integration": "WHATSAPP-BAILEYS"
  }'

A resposta traz um QR code. Você escaneia uma vez com o app WhatsApp Business no celular do escritório e a sessão fica persistida no banco.

Enviando documento via link rastreado

Não envie o PDF como anexo — mande texto + link único:

curl -X POST https://evo.seudominio.com/message/sendText/escritorio-principal \
  -H "apikey: sua-chave-secreta-longa" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511987654321",
    "text": "Olá! Seu holerite de maio/2026 está disponível.\nAcesse: https://meudoc.cloud/d/abc123\n— Escritório Modelo"
  }'

O link curto aponta para sua plataforma de tracking, que registra IP, dispositivo, horário e devolve eventos via webhook.

Tratando o webhook

Quando o usuário lê a mensagem, o Evolution dispara webhook tipo:

POST /webhook/whatsapp
{
  "event": "messages.update",
  "data": {
    "key": { "id": "ABCDEF...", "remoteJid": "5511987654321@s.whatsapp.net" },
    "status": "READ",
    "messageTimestamp": 1715283600
  }
}

Você correlaciona o key.id com o envio original e atualiza o status do documento. Combinado com o tracking do link (clique → leitura → download), você fecha a linha do tempo.

Custos típicos

• VPS: R$ 30-80/mês (Hetzner, DigitalOcean, BlueHost BR).
• Domínio + SSL: R$ 40/ano + Let's Encrypt grátis.
• Manutenção: ~2h/mês de DevOps.
• Risco de banimento: zero se uso transacional, com mensagens curtas e número reservado pra envio (não pra receber spam).

Comparado à API oficial (R$ 0,06-0,10 por mensagem template + BSP setup), você economiza 80-90% em volumes a partir de 1.000 mensagens/mês.

O atalho: usar plataforma que já integra

Se você não quer gerenciar Evolution API direto, plataformas como o meudoc.cloud já integram nativamente — basta apontar a URL e a chave da sua instância. O sistema cuida de envio, retry, webhook, tracking e arquivamento. Veja também por que WhatsApp puro não comprova leitura — Evolution API resolve só metade do problema, sem o tracking do link.