n8n-nodes-voalle

Node comunitario para conectar o n8n ao ERP Voalle, com foco em automacoes simples, rapidas e uteis para provedores, equipes de atendimento, CRM, financeiro e rotinas de integracao.

A ideia do projeto e facilitar o uso das APIs de terceiros da Voalle dentro do n8n, reduzindo a necessidade de montar chamadas HTTP manualmente para pequenas e ageis automacoes do dia a dia.

Ele foi pensado para transformar tarefas repetitivas em fluxos claros, rastreaveis e faceis de manter, mantendo uma base simples para evoluir conforme surgirem novas necessidades de integracao.

Criado por WillRDNK.

O que ele faz

O n8n-nodes-voalle adiciona um node Voalle ao n8n com credencial propria e operacoes organizadas por recurso.

Principais recursos:

• Autenticacao via credencial Voalle Auth API usando client_credentials.
• Chamadas autenticadas para endpoints de terceiros do Voalle.
• Organizacao por modulos: CRM Voalle, Financeiro, ISP | Telecom, Suite e Service Desk.
• Suporte a parametros de paginacao, filtros e ordenacao nas operacoes que exigem consulta.
• Campos de formulario nativos do n8n para montar payloads sem escrever JSON manualmente nas principais operacoes.
• Selectors pesquisaveis (resourceLocator/listSearch) para campos que podem ser obtidos por APIs de listagem, mantendo no payload final o ID ou codigo esperado pela API Voalle.
• Suporte a envio de anexo em solicitacoes usando dados binarios do n8n.
• Node preparado para workflows, rotinas operacionais e pequenas automacoes assistidas no n8n.

Operacoes disponiveis

CRM:

• Criar lead.
• Nova negociacao.
• Incluir servico no contrato.
• Alterar servico do contrato.
• Remover servico do contrato.
• Consultar viabilidade.
• Cancelar negociacao.
• Consultar tipos de contrato e servicos.
• Consultar campanhas e servicos da lista de preco.

ISP | Telecom:

• Atualizar conexao.
• Buscar status do ponto de acesso por contrato.
• Buscar status do ponto de acesso por cliente.
• Registrar trafego de usuario autenticado em contrato ISP.
• Listar conexoes por cliente.
• Listar scripts de provisionamento por conexao.
• Provisionar conexao.

Financeiro:

• Buscar faturas em aberto por CPF/CNPJ.
• Buscar faturas em aberto por contrato.

Suite:

• Cadastrar pessoa.
• Atualizar pessoa.
• Atualizar ou adicionar endereco do cliente.
• Listar clientes com paginacao.
• Listar locais.
• Buscar cliente por CPF/CNPJ.
• Listar tipos de documentos.
• Buscar documento de assinatura eletronica por contrato.
• Reenviar documento de assinatura eletronica.
• Validar se data e feriado.

Service Desk:

• Buscar detalhes e historico de solicitacoes.
• Listar solicitacoes por cliente.
• Listar e buscar tipos de solicitacao, SLAs, etiquetas, catalogos, itens e subitens.
• Consultar agendamentos do FSM.
• Listar, alocar, efetivar e retornar materiais em solicitacoes.
• Listar equipes, status e motivos para encaminhamento.
• Encaminhar solicitacoes.
• Abrir solicitacoes simples, CRM, externas detalhadas e internas detalhadas.
• Realizar manutencao em solicitacao.
• Abrir e encerrar solicitacoes vinculadas a ponto de acesso ou cliente.
• Adicionar apontamentos e relatos.
• Listar, enviar e baixar anexos em solicitacoes.

Selectors e compatibilidade de payload

Algumas operacoes usam selectors pesquisaveis para reduzir erros de digitacao e facilitar a montagem do fluxo no n8n. Mesmo usando selector na interface, o node envia para a API o valor esperado pelo endpoint, como id, code, CPF/CNPJ ou numero de contrato.

Selectors atualmente disponiveis:

• CRM: tipos de contrato, servicos, campanhas e listas de preco.
• Suite: clientes, locais e tipos de documentos.
• ISP | Telecom: clientes nas operacoes que exigem clientId.
• Service Desk: equipes, status e motivos de encaminhamento.

Campos sem API de consulta correspondente na colecao oficial continuam como campos de texto, numero, booleano ou data. Isso preserva compatibilidade com ambientes Voalle diferentes e evita assumir cadastros que podem variar por cliente.

Referencia da API

As operacoes deste projeto seguem como referencia a documentacao oficial de APIs de terceiros da Voalle:

APIs para Terceiros - ERPVoalle

Como a API pode variar conforme ambiente, permissoes e versao do ERP, valide sempre os endpoints, portas, credenciais e escopos no seu ambiente Voalle antes de colocar fluxos em producao.

Credenciais

Para usar o node, configure a credencial Voalle Auth API no n8n com:

• Base URL: URL base do ambiente Voalle, sem a porta final da API.
• Client ID: identificador da aplicacao.
• Client Secret: segredo da aplicacao.
• Grant Type: normalmente client_credentials.
• Scope: normalmente syngw.
• Additional Body Properties: JSON enviado na chamada de token, normalmente {"syndata":"valor-do-syndata"}.

O node solicita token em ${baseUrl}:45700/connect/token e executa as chamadas da API em ${baseUrl}:45715.

Instalacao local

Requisitos:

• Node.js >=20.15.
• npm.
• n8n instalado no ambiente onde o node sera usado.

Instale as dependencias:

npm install

Compile o projeto:

npm run build

Durante desenvolvimento, use:

npm run dev

Para validar o codigo:

npm run lint

Desenvolvimento

Estrutura principal:

• nodes/Voalle/Voalle.node.ts: entrada principal do node.
• nodes/Voalle/operations: operacoes disponiveis no node.
• nodes/Voalle/transport/voalleApiClient.ts: cliente compartilhado para autenticacao e chamadas HTTP.
• credentials/VoalleAuthApi.credentials.ts: definicao da credencial Voalle.

Ao adicionar novas operacoes, registre-as em nodes/Voalle/operations/index.ts para que aparecam na interface do n8n e sejam executadas pelo dispatcher do node.

Status do projeto

Este e um projeto publico e comunitario. Ele nao e um produto oficial da Voalle e nao possui vinculo comercial com a empresa.

A proposta e evoluir conforme necessidades reais de integracao, mantendo o codigo simples, legivel e util para quem precisa automatizar processos no ecossistema Voalle sem criar integracoes grandes ou complexas quando um fluxo pequeno resolve.

Dedicatoria

Dedico este projeto a quem vive a rotina de operacao, suporte, redes, atendimento e integracoes, onde um fluxo simples e bem feito economiza horas de trabalho invisivel.

Que ele ajude a reduzir cliques repetidos, aproximar a API da rotina operacional e tornar pequenas automacoes mais acessiveis para quem trabalha com Voalle e n8n.

Licenca

MIT