zap-gateway

n8n Community Node para ZAP Gateway — WhatsApp abstraction layer (Z-API / UAZAPI)

Package Information

Released: 1 mo ago
Downloads: 406 weekly / 716 monthly
Latest Version: 3.2.0

Available Nodes

ZAP Gateway icon
ZAP Gateway
Envia mensagens WhatsApp via ZAP Gateway (Z-API / UAZAPI)

Documentation

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

Licença

MIT

Discussion