n8n-nodes-zdg

Community node para n8n que permite integrar automações com a plataforma Z-PRO / ZDG diretamente nos seus workflows.

Desenvolvido pela Comunidade ZDG.

Instalação

Via n8n Community Nodes (Recomendado)

1. Acesse Settings > Community Nodes
2. Clique em Install a community node
3. Digite n8n-nodes-zdg e clique em Install

Via npm

npm install n8n-nodes-zdg

Via Docker

Se você usa o n8n via Docker, adicione ao seu Dockerfile:

RUN cd /usr/local/lib/node_modules/n8n && npm install n8n-nodes-zdg

Ou via variável de ambiente:

N8N_CUSTOM_EXTENSIONS=n8n-nodes-zdg

Configuração das Credenciais

Antes de usar o node, configure suas credenciais ZDG:

1. No n8n, vá em Credentials > Add Credential
2. Busque por ZDG API
3. Preencha os campos:

| Campo | Descrição | Exemplo | |-------|-----------|---------| | URL do Backend | Domínio base do seu backend Z-PRO (sem /v2/api/external/...) | https://backend.seudominio.com.br | | API ID | UUID da API fornecido pela plataforma | a1b2c3d4-e5f6-7890-abcd-ef1234567890 | | Token de Acesso | Bearer Token para autenticação | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |

Importante: No campo URL do Backend, coloque apenas o domínio (ex: https://backend.seudominio.com.br). O node monta automaticamente o caminho /v2/api/external/{ApiID}/....

Recursos e Operações

O node ZDG Chat oferece 10 recursos com mais de 60 operações para gerenciar toda a sua plataforma Z-PRO.

1. Mensagem

Envio de mensagens individuais via WhatsApp.

| Operação | Descrição | |----------|-----------| | Enviar Texto | Envia uma mensagem de texto simples | | Enviar Arquivo por URL | Envia um arquivo a partir de uma URL pública | | Enviar Áudio | Envia uma mensagem de voz a partir de URL | | Enviar Arquivo Binário | Envia arquivo binário recebido de outro node (imagem, PDF, áudio, etc.) | | Enviar Base64 | Envia conteúdo codificado em Base64 | | Obter Parâmetros | Obtém parâmetros de mensagem via GET |

Campos comuns:

• Número do Destinatário - Número do WhatsApp com DDI+DDD (ex: 5511900000000)
• Chave Externa - Identificador externo para rastreamento
• Fechar Ticket Após Envio - Opção para fechar o ticket automaticamente

Exemplo - Enviar Texto:

• Número: 5511900000000
• Mensagem: Olá! Esta é uma mensagem automática.
• Chave Externa: pedido-12345

Exemplo - Enviar Base64:

• Número: 5511900000000
• Base64: conteúdo puro em base64 (sem prefixo data:)
• Nome do Arquivo: documento.pdf
• Tipo MIME: application/pdf
• Legenda: Segue o documento solicitado

Dica: O node aceita tanto base64 puro quanto data URLs (data:image/png;base64,...). O prefixo é removido automaticamente antes do envio.

2. Mensagem em Grupo

Envio de mensagens para grupos do WhatsApp.

| Operação | Descrição | |----------|-----------| | Enviar Texto | Envia texto para um grupo | | Enviar Mídia por URL | Envia mídia para um grupo via URL |

Campos:

• ID do Grupo - Identificador do grupo no WhatsApp (ex: [email protected])
• Mensagem / URL - Conteúdo a ser enviado
• Legenda - Legenda da mídia (opcional)

3. Template WABA

Envio de templates aprovados pela API Oficial do WhatsApp Business (WABA).

| Operação | Descrição | |----------|-----------| | Enviar Template | Envia template simples (sem variáveis no body) | | Enviar Template com Body | Envia template com variáveis no corpo | | Enviar Template Marketing | Envia template de marketing com variáveis |

Campos:

• Número - Número do destinatário
• Nome do Template - Nome do template aprovado (ex: boas_vindas)
• Idioma - Código do idioma (ex: pt_BR)
• Parâmetros do Body - JSON com variáveis (ex: ["João", "Pedido #1234"])

Opções adicionais:

• URL do Header - URL de mídia para o header do template
• Parâmetros do Header - JSON com variáveis do header

4. WABA Interativo

Mensagens interativas da API Oficial do WhatsApp Business.

| Operação | Descrição | |----------|-----------| | Enviar Botões | Envia mensagem com botões de resposta rápida | | Enviar Lista | Envia mensagem com lista de opções |

Exemplo - Enviar Botões:

• Número: 5511900000000
• Mensagem: Escolha uma opção:
• Botões (JSON):

[
  { "id": "btn_1", "title": "Opção 1" },
  { "id": "btn_2", "title": "Opção 2" },
  { "id": "btn_3", "title": "Opção 3" }
]

Exemplo - Enviar Lista:

• Número: 5511900000000
• Mensagem: Veja nossos produtos:
• Texto do Botão: Ver Produtos
• Seções (JSON):

[
  {
    "title": "Categoria A",
    "rows": [
      { "id": "prod_1", "title": "Produto 1", "description": "Descrição do produto 1" },
      { "id": "prod_2", "title": "Produto 2", "description": "Descrição do produto 2" }
    ]
  }
]

Opções adicionais:

• Header - Texto do cabeçalho
• Footer - Texto do rodapé

5. Contato

Gerenciamento completo de contatos na plataforma.

| Operação | Descrição | |----------|-----------| | Criar Contato | Cria um novo contato | | Buscar Contato | Busca contato por número | | Atualizar Contato | Atualiza dados de um contato | | Bloquear Contato | Bloqueia um contato | | Pesquisar Contato | Pesquisa avançada de contatos | | Atualizar Kanban | Atualiza status do contato no Kanban | | Atualizar Carteira | Atualiza a carteira (wallet) do contato | | Obter Info Extra | Obtém campos extras do contato | | Atualizar Info Extra | Atualiza campos extras do contato |

Campos para criar contato:

• Nome - Nome do contato
• Número - Número do WhatsApp (ex: 5511900000000)
• Email - Email do contato (opcional)

Exemplo - Atualizar Info Extra:

• ID do Contato: 42
• Info Extra (JSON):

[
  { "name": "cpf", "value": "000.000.000-00" },
  { "name": "empresa", "value": "Empresa Exemplo LTDA" }
]

6. Ticket

Gerenciamento de tickets/atendimentos.

| Operação | Descrição | |----------|-----------| | Criar Ticket | Cria um novo ticket para um contato | | Buscar Ticket | Busca ticket por ID | | Buscar Ticket (Chatbot) | Busca ticket com dados do chatbot | | Buscar Ticket (Completo) | Busca ticket com todas as informações | | Listar Mensagens | Lista todas as mensagens de um ticket | | Definir Fila | Define a fila de um ticket | | Definir Tag | Define (substitui) a tag de um ticket | | Adicionar Tag | Adiciona uma tag ao ticket | | Remover Tag | Remove uma tag do ticket | | Atualizar Info | Atualiza status do ticket | | Atualizar Canal | Muda o canal/WhatsApp do ticket | | Criar Nota | Cria uma nota interna no ticket | | Atualizar Nota | Atualiza uma nota existente | | Listar Notas | Lista notas de um ticket | | Enviar Presença | Envia indicador de presença (digitando) |

Campos:

• ID do Ticket - ID numérico do ticket
• Número do Contato - Para criação de ticket
• ID da Fila / ID da Tag - Para atribuição
• Status - Status do ticket (ex: open, closed, pending)

7. Oportunidade

Gerenciamento de oportunidades (CRM/Pipeline).

| Operação | Descrição | |----------|-----------| | Criar Oportunidade | Cria uma nova oportunidade | | Atualizar Oportunidade | Atualiza uma oportunidade existente | | Excluir Oportunidade | Remove uma oportunidade |

Campos:

• Nome - Nome da oportunidade
• ID do Contato - Contato vinculado
• ID da Oportunidade - Para atualização/exclusão

Campos adicionais: value (valor), pipelineId, stageId, description, dueDate

8. Usuário

Gerenciamento de usuários/atendentes do sistema.

| Operação | Descrição | |----------|-----------| | Criar Usuário | Cria um novo usuário | | Atualizar Usuário | Atualiza dados de um usuário | | Listar Usuários | Lista todos os usuários | | Obter Status | Obtém status online/offline do usuário |

Campos para criar:

• Nome - Nome do usuário
• Email - Email do usuário
• Senha - Senha de acesso

9. Listagens

Consultas gerais para obter dados da plataforma.

| Operação | Descrição | |----------|-----------| | Listar Canais | Lista todos os canais/WhatsApp conectados | | Listar Sessões | Lista todas as sessões ativas | | Listar Filas | Lista todas as filas de atendimento | | Listar Tags | Lista todas as tags/etiquetas | | Listar Contatos | Lista contatos com paginação e filtros | | Listar Tickets | Lista tickets com filtros | | Listar Oportunidades | Lista oportunidades com filtros |

Filtros disponíveis (Listar Contatos):

• Página - Número da página
• Busca - Texto para buscar
• ID da Carteira / ID da Tag - Filtros específicos

Filtros disponíveis (Listar Tickets):

• Status - open, closed, pending
• Busca - Texto para buscar
• IDs das Filas / IDs dos WhatsApp - Filtros por fila/canal

10. Canal e Sessão

Gerenciamento de canais WhatsApp e sessões de conexão.

| Operação | Descrição | |----------|-----------| | Buscar Canal por Nome | Busca um canal pelo nome | | Buscar Canal por ID | Busca um canal pelo ID | | Listar Grupos | Lista grupos de WhatsApp de um canal | | Criar Sessão | Cria uma nova sessão de WhatsApp | | Excluir Sessão | Remove uma sessão | | Iniciar Sessão | Inicia uma sessão existente | | QR Code | Obtém QR Code para conectar um WhatsApp |

Endpoints da API

Referência dos endpoints utilizados pelo node:

| Recurso | Endpoint | Método | |---------|----------|--------| | Enviar Texto | /v2/api/external/{ApiID} | POST | | Enviar Arquivo URL | /v2/api/external/{ApiID}/url | POST | | Enviar Áudio | /v2/api/external/{ApiID}/voice | POST | | Enviar Base64 | /v2/api/external/{ApiID}/base64 | POST | | Obter Parâmetros | /v2/api/external/{ApiID}/params/ | GET | | Mensagem Grupo | /v2/api/external/{ApiID}/group | POST | | Mídia Grupo URL | /v2/api/external/{ApiID}/groupMediaUrl | POST | | Template | /v2/api/external/{ApiID}/template | POST | | Template Body | /v2/api/external/{ApiID}/templateBody | POST | | Template Marketing | /v2/api/external/{ApiID}/templateMarketingBody | POST | | Botões WABA | /v2/api/external/{ApiID}/sendButtonWABA | POST | | Lista WABA | /v2/api/external/{ApiID}/sendListWABA | POST | | Criar Contato | /v2/api/external/{ApiID}/createContact | POST | | Buscar Contato | /v2/api/external/{ApiID}/showcontact | POST | | Atualizar Contato | /v2/api/external/{ApiID}/updateContact | POST | | Bloquear Contato | /v2/api/external/{ApiID}/blockContact | POST | | Pesquisar Contato | /v2/api/external/{ApiID}/contacts/search | POST | | Kanban Contato | /v2/api/external/{ApiID}/updateContactKanban | POST | | Carteira Contato | /v2/api/external/{ApiID}/updateContactWallet | POST | | Info Extra (GET) | /v2/api/external/{ApiID}/getContactExtraInfo | GET | | Info Extra (POST) | /v2/api/external/{ApiID}/updateContactExtraInfo | POST | | Criar Ticket | /v2/api/external/{ApiID}/createTicket | POST | | Buscar Ticket | /v2/api/external/{ApiID}/showticket | POST | | Ticket Chatbot | /v2/api/external/{ApiID}/showticketchatbot | POST | | Ticket Completo | /v2/api/external/{ApiID}/showallticket | POST | | Mensagens Ticket | /v2/api/external/{ApiID}/showAllMessages | POST | | Definir Fila | /v2/api/external/{ApiID}/updatequeue | POST | | Definir Tag | /v2/api/external/{ApiID}/updatetag | POST | | Adicionar Tag | /v2/api/external/{ApiID}/addTag | POST | | Remover Tag | /v2/api/external/{ApiID}/removeTag | POST | | Atualizar Info Ticket | /v2/api/external/{ApiID}/updateticketinfo | POST | | Atualizar Canal Ticket | /v2/api/external/{ApiID}/updateTicketChannel | POST | | Criar Nota | /v2/api/external/{ApiID}/createNotes | POST | | Atualizar Nota | /v2/api/external/{ApiID}/updateNote | POST | | Listar Notas | /v2/api/external/{ApiID}/listNotes | GET | | Enviar Presença | /v2/api/external/{ApiID}/sendPresence | POST | | Criar Oportunidade | /v2/api/external/{ApiID}/createOpportunity | POST | | Atualizar Oportunidade | /v2/api/external/{ApiID}/updateOpportunity | POST | | Excluir Oportunidade | /v2/api/external/{ApiID}/deleteOpportunity | POST | | Criar Usuário | /v2/api/external/{ApiID}/createUser | POST | | Atualizar Usuário | /v2/api/external/{ApiID}/updateUser | POST | | Listar Usuários | /v2/api/external/{ApiID}/listUsers | GET | | Status Usuário | /v2/api/external/{ApiID}/getUserStatus | GET | | Listar Canais | /v2/api/external/{ApiID}/listChannels | GET | | Listar Sessões | /v2/api/external/{ApiID}/listSessions | GET | | Listar Filas | /v2/api/external/{ApiID}/listQueues | GET | | Listar Tags | /v2/api/external/{ApiID}/listTags | GET | | Listar Contatos | /v2/api/external/{ApiID}/listContacts | GET | | Listar Tickets | /v2/api/external/{ApiID}/listTickets | GET | | Listar Oportunidades | /v2/api/external/{ApiID}/listOpportunities | GET | | Buscar Canal (Nome) | /v2/api/external/{ApiID}/showChannel | POST | | Buscar Canal (ID) | /v2/api/external/{ApiID}/showChannelById | POST | | Listar Grupos | /v2/api/external/{ApiID}/listGroupInfo | POST | | Criar Sessão | /v2/api/external/{ApiID}/createtSession | POST | | Excluir Sessão | /v2/api/external/{ApiID}/deleteSession | POST | | Iniciar Sessão | /v2/api/external/{ApiID}/startSession | POST | | QR Code | /v2/api/external/{ApiID}/qrCodeSession | POST |

Compatibilidade

• n8n: >= 1.0.0
• Node.js: >= 18.0.0

Licença

MIT