n8n-nodes-zap-gateway

Nó Community para n8n que integra com o ZAP Gateway — camada de abstração centralizada sobre Z-API e UAZAPI para envio de mensagens WhatsApp.

Por que usar?

Sem o ZAP Gateway, cada troca de instância ou token exige atualizar dezenas de nós nos fluxos do n8n. Com ele, uma única variável de ambiente no gateway resolve.

Instalação

No n8n: Settings → Community Nodes → Install → n8n-nodes-zap-gateway

Ou via CLI:

npm install n8n-nodes-zap-gateway

Configuração

1. Faça o deploy do ZAP Gateway (veja docs/DEPLOY.md)
2. No n8n, crie a credencial ZAP Gateway API com:
   • URL do Gateway: ex. https://gateway.seudominio.com
   • API Key: valor de GATEWAY_API_KEY_1 configurado no gateway
3. Adicione o nó ZAP Gateway nos seus fluxos

Operações disponíveis

Mensagens

| Operação | Endpoint | |---|---| | Enviar Texto | POST /api/v1/send/text | | Enviar Imagem | POST /api/v1/send/image | | Enviar Documento | POST /api/v1/send/document | | Enviar Áudio | POST /api/v1/send/audio | | Enviar Link | POST /api/v1/send/link | | Enviar Botões | POST /api/v1/send/button-list | | Enviar Lote | POST /api/v1/send/bulk |

Instância

| Operação | Endpoint | |---|---| | Obter Status | GET /api/v1/instance/status | | Obter QR Code | GET /api/v1/instance/qrcode | | Verificar Telefone | GET /api/v1/instance/check/:phone | | Full - Verifica Telefone Fallback | GET /api/v1/instance/check-smart/:phone |

Verificação de telefone — campo phoneChatwoot

As operações Verificar Telefone (checkPhone) e Full - Verifica Telefone Fallback (checkPhoneSmart) retornam, além dos campos já existentes, o campo phoneChatwoot — o número já no formato que o Chatwoot espera (E.164: + seguido apenas de dígitos, sem espaços nem separadores). Use-o direto no campo phone_number do contato, sem refazer '+' + phone.replace(/\D/g,'') em cada fluxo.

• phone continua inalterado, em dígitos puros (ex.: 5547999999999) — é a chave usada em lookups/dedup, participantes de grupo e destino de envio.
• phoneChatwoot é derivado do número resolvido (o mesmo que popula o phone). Garante exatamente um + no início (nunca ++).
• Números BR sem DDI (o gateway às vezes resolve para a variante crua, ex.: 31998840478) recebem o 55 na frente no phoneChatwoot → +5531998840478. Móvel sem DDI = 11 díg com 9 na 3ª posição; fixo sem DDI = 10 díg. Números que já têm 55 ou internacionais (com DDI próprio) não são alterados. O phone continua exatamente como veio do gateway.
• Quando o número não existe (exists: false) ou é inválido, phoneChatwoot é null — o campo nunca fica ausente, então o consumidor pode confiar que a chave sempre existe.

Exemplo de saída do checkPhoneSmart:

{
  "exists": true,
  "phone": "5547999999999",
  "phoneChatwoot": "+5547999999999",
  "originalInput": "+55 (47) 99999-9999",
  "cleanedInput": "5547999999999",
  "profile": { "name": "Fulano", "pictureUrl": null, "isBusiness": false },
  "variants": [{ "phone": "5547999999999", "exists": true }]
}

Número inexistente:

{ "exists": false, "phone": "5547999999999", "phoneChatwoot": null, "variants": [/* ... */] }

Como funciona

Este nó não se comunica diretamente com Z-API ou UAZAPI. Ele chama seu próprio ZAP Gateway, que:

• Gerencia a conexão com os providers
• Faz fallback automático via Circuit Breaker (Z-API → UAZAPI)
• Centraliza tokens e instâncias

Trocar de instância Z-API = atualizar uma variável no gateway. Os fluxos do n8n não precisam ser alterados.

Opções do nó

• Continuar em caso de erro (continueOnFail): se ativo, erros em um item não interrompem o fluxo — o item recebe { error: "..." } e o próximo é processado
• Incluir Resposta Completa: retorna todos os metadados da resposta do gateway

Links

• ZAP Gateway — Repositório
• Documentação de instalação do nó
• Strat Academy

Licença

MIT