n8n-nodes-zpro

Community node do n8n para a API externa da Z-PRO (plataforma de multiatendimento WhatsApp e outros canais).

Os nodes são gerados a partir da collection Postman oficial (Z-PRO v4.x.x.x) por um gerador versionado (codegen/gen-from-postman.mjs) — quando a API muda, regera-se o node.

A gestão de tenants (SuperAdmin, cross-tenant) fica num pacote separado por segurança: n8n-nodes-zpro-admin. Não instale o pacote admin em ambientes onde qualquer usuário do n8n possa usá-lo.

Instalação

Em Settings → Community Nodes do n8n, instale n8n-nodes-zpro. Ou, para desenvolvimento local:

npm install
npm run build
# copie/linke a pasta para ~/.n8n/custom (ou use npm link)

Credencial — Z-PRO API

| Campo | Descrição | |---|---| | Base URL | URL da instalação, com https:// e sem barra final (ex.: https://app.zpro.com.br) | | API ID | Segmento :apiId de /v2/api/external/:apiId | | Bearer Token | Token da API externa | | Secret Key | externalKey opcional (deduplicação em alguns envios) |

As requisições usam https://<baseUrl>/v2/api/external/<apiId>/... com header Authorization: Bearer <token>. A resposta da API vem no envelope { success, data, pagination }; o node extrai automaticamente data.

Regenerar os nodes

npm run gen                          # espelha a collection INTEIRA (padrão)
npm run gen -- --only "Campanha|Contato"   # subconjunto de pastas

Lê ../../docs/Z-PRO v4.x.x.x.postman_collection.json.

O gerador:

• usa um parser JSONC (os bodies da collection têm comentários //) e aproveita esses comentários como descrição dos campos;
• normaliza variáveis inconsistentes ({{BASE_URL}}/{{apiId}}/{{API_TOKEN}});
• chaveia operações pelo nome do request (há colisões de path na collection);
• infere tipos de forma conservadora (telefone fica string; ISO 8601 vira dateTime; objetos/arrays viram json).

Arquivo gerado: nodes/Zpro/descriptions/generated.ts (não editar à mão). O único ajuste por operação fica em codegen/n8n-options.json: as operações listadas ali têm os campos obrigatórios no topo e os opcionais em Additional Fields (só vai na requisição o campo que o usuário adicionar). Operação fora da lista sai exatamente como a collection descreve.

Cobertura

Espelha a collection inteira: 32 resources / 241 operations (todas as pastas menos a Tenant API, que vive no pacote admin; regerado em 30/10/2026).

Atualizando de 0.2.0 (versão 0.3.0):

• Novo resource Agentes de IA (18 operações): agentes, base de conhecimento (artigos) e fontes (documento, link e FAQ). Criar e editar usam Additional Fields: no editar, só muda o que você adicionar. Texto deixado vazio vai como "" e, no editar, limpa o campo; JSON deixado vazio não é enviado. Lista enviada substitui a lista inteira.
• AI Agent Source Document: o arquivo precisa ter extensão no nome (.pdf, .docx, .xlsx, .csv, .txt); binário sem nome vira file e é recusado.
• External Key deixou de vir preenchido com um valor de exemplo. O servidor ignora envio repetido com a mesma chave por cerca de 2 minutos, então o valor fixo fazia mensagens seguidas do n8n serem ignoradas. Quem preencheu a própria chave não muda nada.
• Corrigidas três operações que não funcionavam: Gallery Upload (o arquivo ia no campo errado), as 14 operações de Interativo Instagram/Messenger (URL quebrada; somem os campos "Base URL"/"API ID", a credencial já informa os dois) e Send Message Params (o token da credencial vai na URL, como a rota exige; ganhou o campo External Key). Atenção: por ir na URL, o token fica nos logs de acesso do servidor; para enviar sem expor o token, prefira as operações de envio por POST (Send Message API Text e afins).
• O campo API Key dos agentes fica oculto na tela do node, mas continua em texto no JSON do workflow exportado (o n8n só cifra credenciais). Para não deixar a chave no workflow, use uma expressão com variável de ambiente no campo ou crie o agente com Use Platform AI.

Atualizando de 0.1.3: a operação List Groups Info saiu do resource Canais e Sessões e passou para Grupos WhatsApp (onde a collection já a tinha). Fluxo salvo com ela precisa reescolher a operação no novo resource; os campos são os mesmos. Nenhuma outra operação mudou de lugar ou de nome; as novas são Google Agenda, Formulários, Envio por Ticket, Interativo Zapo e itens avulsos de Contatos, Grupos, Galeria e Tickets. Inclui os 3 endpoints de upload (SendMessageAPIFile, SendGroupMessageAPIFile, CreateTicketFile) via campo binário + montagem multipart.

Pontos que herdam o comportamento literal da collection e podem precisar de polimento (Fase 3, ver docs/PLANO_N8N_COMMUNITY_NODE.md):

• Paginação (returnAll) nos GETs de listagem — hoje retorna a 1ª página.
• Google Agenda → Google Calendar Event List pagina por cursor (pageToken), e o node devolve só o data do envelope: o nextPageToken (em pagination) não chega ao fluxo, então só a 1ª página é lida. Contorno: aumentar o limit (até 250) ou estreitar timeMin/timeMax.
• Endpoints multiplexados por action/type (iceBreakers, persistentMenu, greeting, personas, createSession) — o body de exemplo cobre só uma variante.
• Uploads (6 operações, inclusive o documento da base de conhecimento) — montagem multipart com o nome do campo de arquivo que a collection descreve; validar em runtime do n8n.

Licença

MIT