Description

n8n-nodes-pacto

Node community do n8n para integrar seus fluxos com a
API Pacto Soluções, o sistema de gestão de
academias.

n8n é uma plataforma de automação de fluxos com
licença fair-code.

Instalação · Credenciais · Nós e Operações ·
Exemplos · Tool de IA ·
Desenvolvimento · Versões · Apoie

—

🚀 Funcionalidades

• 1 node unificado — Pacto, com seleção Área → Operação.
• Cobertura do catálogo — 4.620 operações em 488 áreas na especificação oficial consultada em

06/11/2026.

• Registro por lista pesquisável — em node novo (versão 2), as operações que recebem o ID de

um registro (aluno, aula, aparelho, ativo do patrimônio…) mostram a lista da sua conta e
aceitam colar o ID.

• Busca Rápida — nas listagens que aceitam o filtro quicksearchValue, digite o texto em vez

de escrever JSON no campo filters.

• Campos amigáveis — cada operação mostra os campos com nome e descrição da API.
• Datas com seletor — campos de data usam o seletor de data do n8n.
• Secret_Key segura — fica nas credenciais criptografadas do n8n e vai como

Authorization: Bearer SECRET_KEY.

• Return All — pagina as operações GET de listagem.
• Usável como Tool de IA — usableAsTool: true, para AI Agents chamarem as operações.
• Workflows antigos continuam iguais — o node tem as versões 1 e 2; workflow salvo na versão 1

não muda.

• Zero dependências de runtime — usa só os helpers do próprio n8n.

📦 Instalação

Siga o guia de community nodes
do n8n.

No n8n, abra Settings → Community Nodes → Install e informe:

n8n-nodes-pacto

> Requer uma instância n8n com n8nNodesApiVersion 1.

🔑 Credenciais

Crie uma credencial Pacto API, informe o Empresa ID e cole a Secret_Key.

Como gerar a Secret_Key

1. Entre no módulo administrativo da Pacto.
2. Abra Configurações → Integrações.
3. Selecione a empresa e avance.
4. Entre em ADM → API Sistema Pacto.
5. Clique em Gerar credencial.
6. Defina descrição, validade e escopos.
7. Copie a Secret_Key antes de concluir.

> A chave é exibida somente durante a geração. Quando a rede possui várias unidades, gere uma
> credencial para cada unidade.

A credencial tem teste embutido no endpoint oficial GET /psec/credential-validator. A validação
recebe a chave diretamente; as operações da API recebem o padrão Bearer definido pela OpenAPI. O
Empresa ID vai automaticamente no header empresaId em todas as requisições.

🧩 Nós e Operações

1. Adicione o node Pacto.
2. Escolha uma Area, como Clientes, Plano, Produto, Negociação ou Agenda de Aulas.
3. Escolha uma Operation. A lista mostra, por exemplo:

   Consultar um aluno [GET]
   

4. Preencha os campos da operação. Em node novo, o ID do registro aparece como Registro.
5. Execute o node.

A descrição de cada operação informa o escopo e os parâmetros da OpenAPI. A
documentação oficial tem schemas, exemplos e regras de
negócio.

Registro (versão 2)

Nas operações que recebem o ID de um registro no caminho da rota, o campo Registro tem dois
modos:

| Modo | Uso |
| — | — |
| Da Lista | Abre a lista da sua conta, com busca, e traz uma página por vez ao rolar |
| Por ID | Cola o ID (ou uma expressão) quando você já o conhece |

A lista vem da rota de listagem oficial da mesma entidade (por exemplo, GET /psec/alunos para
/psec/alunos/{id}). O gerador só liga a lista quando a documentação confirma a paginação
(page e size), o campo do ID e um campo de nome. Operações sem lista confirmada continuam com
o campo de ID em texto, dentro de Fields.

Busca Rápida (versão 2)

Nas listagens cujo filtro aceita quicksearchValue, o campo Busca Rápida substitui o JSON.
Se o campo filters já tiver um objeto JSON, o node acrescenta o texto a ele.

💡 Exemplos

Consultar um aluno

Area: Clientes
Operation: Consultar um aluno [GET]
Registro: Da Lista → escolha o aluno

O Empresa ID vem da credencial e não precisa ser repetido.

Listar alunos com busca

Area: Clientes
Operation: Consultar alunos da academia [GET]
Busca Rápida: silva
Return All: ligado

O node envia filters={"quicksearchValue":"silva"} e pagina com size 100.

Criar ou atualizar

Para operações POST, PUT ou PATCH, preencha os campos do formulário. O schema varia por
operação e o node monta o corpo sozinho.

🤖 Usar como Tool de Agente de IA

O node Pacto é usável como tool por nós de AI Agent do n8n (Tools Agent). Isso deixa o modelo executar ações na Pacto sozinho — por exemplo: “consulte o aluno de matrícula 1234 e me diga se o plano dele está ativo”. A prática recomendada é criar uma tool por operação liberada para o agente.

Como ligar (2 passos)

1. No servidor n8n, habilite o uso de community nodes como tools (por segurança, vem desligado por padrão). Defina a variável de ambiente:

   N8NCOMMUNITYPACKAGESALLOWTOOL_USAGE=true
   

| Instalação | Onde definir |
| — | — |
| Docker / docker-compose | Adicione em environment: do serviço n8n (ou no .env) e recrie o container (docker compose up -d). |
| npm / npx | Exporte antes de subir: export N8NCOMMUNITYPACKAGESALLOWTOOL_USAGE=true && n8n start. |
| n8n Cloud | Já habilitado nos planos que suportam community nodes. |

Sem essa variável o node não aparece na lista de tools do AI Agent — é a causa nº 1 de “não acho o node como tool”.

2. No workflow, adicione um node AI Agent, conecte um Chat Model e, no conector Tool, adicione o Pacto. Fixe a Area e a Operation que o agente pode usar (ex.: Clientes → Consultar um aluno [GET]). Crie uma tool por operação.

Deixe o modelo preencher os campos ($fromAI)

Em cada campo do node em modo tool aparece o botão “Let the model define this parameter”, que usa a expressão:

{{ $fromAI('busca', 'Nome ou parte do nome do aluno', 'string') }}

• Assinatura: $fromAI(key, description?, type?, defaultValue?) — key de 1–64 caracteres ([a-zA-Z0-9_-]); type = string | number | boolean | json.
• Você pode misturar: fixar a Area e a Operation e deixar o modelo preencher só o ID, a busca ou o corpo.
• Na versão 2 do node, o Registro é um Resource Locator. Para o modelo preencher o ID, mude o campo para o modo Por ID e ponha a expressão $fromAI no valor. A lista Da Lista serve para a pessoa que monta o workflow, não para o agente.
• A descrição de cada operação e de cada campo vem da documentação oficial da Pacto; quanto mais específico o System Message do agente, melhor o resultado.

Exemplos com os campos do node

Consultar um aluno (Clientes → Consultar um aluno [GET]):

• Registro, modo Por ID: o ID vem de uma busca anterior, nunca inventado.

  {{ $fromAI('alunoId', 'ID do aluno na Pacto, obtido de uma listagem anterior. Nunca invente.', 'string') }}
  

Listar alunos (Clientes → Consultar alunos da academia [GET]):

• Busca Rápida: o modelo escreve só o texto; o node monta o JSON de filters.

  {{ $fromAI('busca', 'Nome ou parte do nome do aluno a procurar', 'string') }}
  

• Return All: deixe desligado na tool, para o agente não baixar a base inteira.

Criar ou atualizar (operações POST, PUT, PATCH): as colunas de Fields aceitam $fromAI uma a uma. Preencha com $fromAI só o que o usuário informou e fixe o resto.

Boas práticas

• Exponha apenas as operações necessárias e prefira leitura antes de escrita.
• Use uma Secret_Key dedicada ao agente, com escopos mínimos.
• Nunca deixe o modelo inventar IDs: o ID vem de uma listagem anterior ou do usuário.
• Para operações destrutivas, coloque uma etapa humana de confirmação quando o fluxo for sensível.
• O Registro e a Busca Rápida só existem na versão 2; em workflow salvo na versão 1, o ID e o filters ficam dentro de Fields.

Referências

• Tools Agent — n8n Docs
• Let AI specify tool parameters ($fromAI) — n8n Docs
• Variáveis de ambiente de nodes — n8n Docs

🛠️ Desenvolvimento

npm install          # dependências
npm run build        # n8n-node build: tsc + cópia de ícones
npm test             # compila e roda node --test sobre o dist
npm run lint         # lint oficial do n8n (n8n-node lint)
npm run lint:fix

Atualizar o catálogo oficial

npm run update:catalog

Exige Node 24 ou mais novo. O gerador (scripts/update-pacto-catalog.mjs):

1. descobre o bundle atual da documentação e lê o source map publicado;
2. extrai a OpenAPI oficial e monta nodes/Pacto/helpers/catalog.generated.ts;
3. preserva o que o pacote já publicou: operação que a documentação removeu fica marcada
legacy (só a versão 1 do node a lista) e área com acento perdido volta ao nome antigo;
4. gera nodes/Pacto/helpers/lookups.generated.ts com as listas dos seletores e as operações
com Busca Rápida, e imprime as bases que ficaram sem lista, com o motivo.

Melhorias de campo entram no gerador, nunca à mão nos arquivos *.generated.ts.

Estrutura:

n8n-nodes-pacto/
├── credentials/PactoApi.credentials.ts
├── nodes/Pacto/
│   ├── helpers/        # catálogo e listas gerados, regras de ID e Busca Rápida
│   ├── methods/        # operações, mapeador de campos e lista do seletor
│   ├── transport/      # chamada HTTP com credencial e timeout
│   └── Pacto.node.ts
├── scripts/            # gerador do catálogo (catalog-builder.mjs e a casca)
├── test/               # node --test com contexto falso do n8n
└── .github/workflows/  # ci.yml e publish.yml

✅ Compatibilidade

• n8n Community Nodes API v1, compilado com n8n-workflow 2.47.
• Node.js 24 no CI e na publicação.
• API base: https://apigw.pactosolucoes.com.br; OpenAPI 3.0.1.
• Autenticação por Secret_Key.
• Atualizando do 1.0.x: workflows salvos continuam na versão 1 do node e enviam as mesmas

requisições. Para usar o Registro e a Busca Rápida, adicione um node novo (versão 2).

📚 Recursos

• Documentação da API Pacto
• Central de Ajuda Pacto — gerar Secret_Key
• Community nodes do n8n

🚀 Publicação

A tag vX.Y.Z dispara o workflow publish.yml, que valida a tag contra a versão do
package.json, roda lint, testes e build e envia o pacote com npm stage publish e provenance. A
versão fica em espera: ela só vai ao ar depois que o dono a aprova, com 2FA, na aba **Staged
Packages** do npmjs.com.

📈 Versões

• 1.1.0 — Registro por lista e Busca Rápida. Chega a versão 2 do node: os IDs de caminho das

operações com lista (aluno, aula, aparelho, ativo do patrimônio e outros) mostram a lista da
conta e aceitam colar o ID; a Busca Rápida troca o JSON de filters. Migração para o
@n8n/node-cli 0.55.5 (lint oficial sem erros, testes e CI), n8n-workflow 2.47, catálogo
regenerado com 4.620 operações e as 131 operações removidas pela documentação preservadas
(legacy) para workflows salvos. Corrige o cabeçalho que não é da credencial, que quebrava a
execução. Os campos que a documentação viva tirou de 7 operações continuam aceitos como opcionais; só o
PUT /psec/atividades/{id} muda de forma: a documentação hoje exige Cod Atividade Original.

• 1.0.1–1.0.3 — Nomes de operação simplificados, Empresa ID na credencial e seletor de data nos campos de data. Veja o histórico no Git.
• 1.0.0 — Lançamento: node unificado, catálogo OpenAPI, Secret_Key, paginação, AI Tool e npm

provenance.

🆘 Suporte

Se algo não funcionar:

1. Confira o Empresa ID e a Secret_Key (o teste da credencial usa o endpoint oficial).
2. Verifique se a versão do n8n é compatível.
3. Consulte os logs do n8n para o erro da API.
4. Abra uma issue no GitHub.

☕ Apoie o projeto

Este node é mantido de forma independente. Se ele ajuda suas automações, você pode apoiar o
desenvolvimento e as novas integrações pelo
Buy Me a Coffee.

📄 Licença

MIT