Wafly › Tutoriais › Migração no n8n
Como migrar Evolution API ou Z-API no n8n sem refazer o fluxo
O que realmente muda entre as APIs
| Camada | Z-API | Evolution API | Wafly |
|---|---|---|---|
| Autenticação | ID e token na URL; Client-Token da conta | Header apikey | Client-Token, instância e token |
| Recebimento | Webhooks POST configurados por evento | Webhook por instância ou global, com eventos selecionados | Webhooks de recebimento, entrega e conexão |
| n8n | HTTP Request | HTTP Request ou nodes da comunidade | Node dedicado ou HTTP Request |
| Infraestrutura | Gerenciada | Normalmente self-host ou serviço de terceiro | Gerenciada |
A documentação oficial da Z-API alerta que ID e token devem ficar no servidor, nunca no frontend. A documentação atual da Evolution mostra autenticação por apikey e webhooks com eventos como MESSAGES_UPSERT e CONNECTION_UPDATE. A migração deve tratar essas diferenças somente nas bordas do fluxo.
O desenho que evita refazer tudo
O erro comum é deixar dezenas de expressões do n8n lendo diretamente campos como body.data.key.remoteJid. Quando o fornecedor muda, todas quebram. Crie um node “Normalizar WhatsApp” logo após o webhook e faça o resto do fluxo consumir apenas seu contrato interno.
Migração em 7 passos
- Duplique o workflow. A cópia recebe um sufixo de homologação e fica desativada até os testes.
- Separe configuração. URL base, instância e tokens vão para Credentials ou Variables. Não espalhe valores em cada HTTP Request.
- Normalize a entrada. Depois do webhook, gere sempre os mesmos campos: provedor, instância, ID da mensagem, telefone, texto, tipo e flag de grupo.
- Normalize a saída. Antes do envio, a regra entrega apenas
phone,messagee mídia opcional. - Troque o transporte. Substitua o HTTP Request antigo pelo node Wafly ou pela nova chamada REST.
- Teste com outro número. Não tente manter o mesmo WhatsApp conectado nos dois fornecedores.
- Faça o corte. Desative o workflow antigo, desconecte a sessão anterior, conecte a nova e acompanhe os eventos.
Exemplo de contrato normalizado
{
"provider": "wafly",
"instance": "cliente-acme",
"message_id": "3EB0...",
"phone": "5511999999999",
"text": "Quero falar com vendas",
"type": "text",
"is_group": false,
"received_at": "2026-08-28T23:00:00Z"
}No n8n, um Set/Edit Fields ou Code node transforma o evento recebido nesse objeto. A partir daí CRM, agente de IA, filtros e banco não precisam saber se o evento veio da Evolution, Z-API ou Wafly.
Para enviar pela Wafly via HTTP Request:
POST https://wafly.com.br/api-bridge-whats/instances/SUA_INSTANCIA/token/SEU_TOKEN/send-text
Client-Token: SEU_CLIENT_TOKEN
Content-Type: application/json
{
"phone": "{{$json.phone}}",
"message": "{{$json.message}}"
}Matriz mínima antes do corte
| Caso | Validar | Resultado esperado |
|---|---|---|
| Texto enviado | Telefone, resposta HTTP e ID | Uma mensagem, um ID persistido |
| Texto recebido | Telefone, texto e instância | Contrato normalizado completo |
| Mídia | Tipo, URL/base64 e tamanho | Fluxo não tenta tratar mídia como texto |
| Status | ID da mensagem | Atualiza o mesmo registro do envio |
| Evento duplicado | Mesmo message_id | Segunda execução é ignorada |
| Desconexão | Instância e alerta | Responsável correto é notificado |
| Erro da API | Timeout e resposta 4xx/5xx | Retry limitado, sem loop infinito |
Como executar o corte e preservar rollback
- Congele mudanças no workflow durante a janela.
- Desative o workflow antigo para impedir resposta duplicada.
- Desconecte o número da sessão anterior e conecte na nova API.
- Envie e receba uma mensagem controlada.
- Confirme que o CRM e os status foram atualizados.
- Mantenha o workflow antigo desativado por 24 horas antes de arquivá-lo.
Valide a migração antes do corte
Crie uma instância de homologação na Wafly e teste o fluxo por 3 dias sem cartão.
Criar instância de testeConferir endpointsFontes oficiais consultadas
- Z-API: ID, token e segurança.
- Z-API: funcionamento dos webhooks.
- Evolution Foundation: instalação e autenticação por apikey.
- Evolution Foundation: configuração e eventos de webhook.
- n8n: instalação de community nodes.
Perguntas frequentes
Preciso refazer o workflow inteiro?
Não. Quando entrada e saída são normalizadas, CRM, IA e regras continuam iguais. A troca acontece nas bordas.
Posso usar o mesmo número nos dois fornecedores?
Não como estratégia de teste. Use outro número em homologação; no corte, desconecte a sessão anterior antes de conectar a nova.
Como evito duplicidade?
Persista o ID da mensagem e descarte IDs já processados. Desative o workflow antigo antes de ativar produção.
Evolution API é oficial?
A Evolution atualmente suporta conexão via Baileys e também integração com a Cloud API da Meta. Verifique qual provider está configurado. Wafly e Z-API por QR são não oficiais.