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). Ajustes manuais vão em overrides/ (deep-merge), conforme docs/PLANO_N8N_COMMUNITY_NODE.md.

Cobertura

Espelha a collection inteira: 27 resources / 198 operations (as 28 pastas menos a Tenant API, que vive no pacote admin). 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.
• Endpoints multiplexados por action/type (iceBreakers, persistentMenu, greeting, personas, createSession) — o body de exemplo cobre só uma variante.
• Uploads — montagem multipart implementada; validar em runtime do n8n.

Licença

MIT