n8n-nodes-sgp

Nó comunitário oficial para n8n que permite integração completa e nativa com o ERP SGP (Sistema de Gestão para Provedores) de internet.

🚀 Funcionalidades

O nó n8n-nodes-sgp expõe 14 módulos e mais de 60 operações, cobrindo todas as rotas essenciais do SGP:

👤 1. Clientes / Assinantes

• Consultar (Busca Rápida): Consulta por CPF/CNPJ, telefone com DDD ou nome.
• Obter Detalhes: Dados cadastrais completos por ID do cliente.
• Listar Todos: Listagem completa com paginação e busca por nome.

📄 2. Contratos

• Listar Contratos: Filtros por cliente, situação (ativo, suspenso, cancelado, todos).
• Obter Detalhes: Detalhes completos do plano, vencimento, valor e serviços contratados.
• Consultar Resumido (URA): Consulta rápida com status financeiro e pendências.

💳 3. Faturas e Boletos

• Listar Faturas: Filtros por contrato, cliente, status (aberta, paga, vencida, cancelada) e intervalo de datas.
• Obter Detalhes da Fatura: Itens da fatura, encargos e descontos.
• Gerar 2ª Via: Geração de link atualizado com linha digitável e código PIX.
• Listar Faturas por Contrato (URA): Consulta rápida de débitos.
• Boletos: Listar boletos, obter detalhes com linha digitável e gerar novo boleto com nova data de vencimento.

🎧 4. Chamados de Suporte

• CRUD de Chamados: Abrir chamado, atualizar, cancelar, obter detalhes e listar com filtros.
• Fluxo de Atendimento: Iniciar atendimento, finalizar atendimento com registro de solução, atribuir atendente.
• Interações: Adicionar mensagens (públicas ou notas internas) e listar histórico de interações.
• Anexos: Enviar arquivos em Base64, listar e remover anexos.
• Categorias & Equipe: Listar e cadastrar categorias, listar atendentes.

🛠️ 5. Ordens de Serviço (OS)

• Gestão de OS: Criar nova OS (instalação, reparo, troca de plano), listar e obter detalhes.
• Controle de Execução: Iniciar, pausar com motivo, retomar e finalizar OS com solução.
• Agendamento: Reagendar data/hora e transferir OS para outro técnico.
• Comentários & Anexos: Histórico de notas de campo e envio de fotos da instalação.
• Técnicos & Tipos: Listar tipos de OS, listar técnicos e consultar agenda do técnico.

🌐 6. Rede FTTH (Fibra Óptica)

• ONUs / ONTs: Listar ONUs, cadastrar, obter detalhes, provisionar com VLAN/Profile, desprovisionar, reiniciar (reboot) e verificar status em tempo real (RX/TX).
• OLTs: Listar OLTs, cadastrar concentrador, listar portas PON e sincronizar status.
• Caixas & Splitters: Listar caixas de atendimento (CTO/CEO), detalhes de portas ocupadas e splitters ópticos.

📦 7. Estoque & Movimentações

• Produtos: Listar produtos, cadastrar item e obter saldo em estoque.
• Movimentações: Registrar entrada/saída com motivo, cancelar movimentação e listar histórico.
• Fornecedores & Categorias: CRUD de fornecedores e categorias de estoque.
• Inventários: Listar inventários e balanços de estoque.

🔐 8. RADIUS & Conexões

• Usuários RADIUS: Listar logins PPPoE/IPoE, obter detalhes, bloquear, desbloquear e resetar senha.
• Sessões Ativas: Listar conexões ativas nos servidores NAS e derrubar sessão (PoD/Disconnect).
• Concentradores (NAS) & Grupos: Listar servidores NAS, grupos de velocidade e histórico de accounting.

📞 9. URA (Telefonia Inteligente)

• Identificação: Consultar cliente por telefone de origem (ANI) ou CPF/CNPJ.
• Autoatendimento: Consultar contrato, faturas e realizar Desbloqueio de Confiança.
• Chamados & Atendimentos: Abrir chamado pela URA e registrar histórico da ligação (opções discadas, duração).
• Menus & Filas: Listar menus e filas telefônicas.

💼 10. Pré-Cadastros (CRM / Leads)

• Gestão de Leads: Listar oportunidades de venda, cadastrar novo lead com plano pretendido.
• Conversão: Converter lead aprovado em cliente efetivo e contrato ativo.
• Origens & Status: Listar canais de captação (Google, Instagram, Site) e status do funil.

📱 11. Central do Assinante

• Autenticação: Operações com CPF/CNPJ e Senha do assinante.
• Faturas & PIX: Consulta de faturas e geração de código Copia e Cola / QR Code PIX.
• Autoatendimento: Abrir chamados, solicitar Desbloqueio de Confiança, extrato de consumo e alteração de senha.

🏦 12. Remessa & Retorno Bancário

• Remessa: Gerar arquivo de remessa CNAB (240/400), listar e fazer download.
• Retorno: Processar arquivo de retorno bancário (.ret/.crm) para baixa automática.
• Boletos: Baixa manual de boletos.

📝 13. Termos de Aceite & LGPD

• Termos: Listar e cadastrar termos de adesão e políticas de privacidade.
• Versões: Versionamento de conteúdo e publicação de revisões.
• Aceites: Registrar aceite eletrônico com IP e consultar histórico por cliente.

⚙️ 14. Sistema & Utilitários

• Localização: Consulta de CEP (busca de endereço), listagem de cidades e estados.
• Auditoria & Alertas: Consulta de logs de auditoria e notificações do sistema.
• Relatórios: Geração de consolidados de financeiro, clientes, suporte e ordens de serviço.

📦 Instalação

Pela Interface Web do n8n (Recomendado)

1. No seu n8n, acesse Settings > Community Nodes.
2. Clique em Install a community node.
3. No campo npm package name, digite:

   n8n-nodes-sgp
   

4. Marque a caixa de aceite e clique em Install.

Via Terminal (Docker / Self-Hosted)

No diretório de dados do seu n8n (geralmente ~/.n8n/):

npm install n8n-nodes-sgp

Ou se estiver rodando com Docker Compose:

environment:
  - N8N_COMMUNITY_PACKAGES_ENABLED=true

🔑 Configuração de Credenciais

No n8n, adicione uma nova credencial do tipo SGP API:

💡 Dica: O n8n possui um botão Test Connection que valida automaticamente a comunicação e autenticação com seu SGP utilizando o endpoint /api/ura/clientes/.

💡 Exemplos de Workflows

1. Cobrança e Notificação Automática de Fatura via WhatsApp

1. Cron / Schedule Trigger: Executa todos os dias às 08:00.
2. SGP (Fatura > Listar Faturas): Busca faturas vencendo hoje (status = aberta).
3. SGP (Fatura > Gerar 2ª Via / PIX): Gera o link de pagamento e código PIX copia e cola.
4. WhatsApp Node / Evolution API: Envia mensagem com o código PIX para o cliente.

2. Autoatendimento de Suporte e Desbloqueio de Confiança

1. Webhook (Chatbot WhatsApp / Typebot / Telegram): Recebe o CPF do cliente.
2. SGP (Cliente > Consultar): Identifica o cliente e seus contratos.
3. SGP (Fatura > Listar Faturas por Contrato): Verifica se há bloqueio financeiro.
4. SGP (URA > Desbloqueio de Confiança): Libera a conexão temporariamente.
5. SGP (RADIUS > Encerrar Sessão): Envia comando PoD para reconectar a ONU com velocidade liberada.

3. Provisionamento Automático de Fibra FTTH

1. Webhook (CRM / Assinatura de Contrato): Recebe novo contrato aprovado.
2. SGP (Ordem de Serviço > Criar): Cria OS de instalação para a equipe técnica.
3. SGP (FTTH > Cadastrar ONU & Provisionar): Vincula a ONU na OLT correspondente com a VLAN do plano.

🛠️ Desenvolvimento Local

# 1. Clone o repositório
git clone https://github.com/rodolfoportalles/n8n-nodes-sgp.git
cd n8n-nodes-sgp

# 2. Instale as dependências
npm install

# 3. Compile o código TypeScript e copie os ícones
npm run build

# 4. Para linkar localmente com sua instância do n8n
npm link
cd ~/.n8n/custom
npm link n8n-nodes-sgp

📄 Licença

Distribuído sob a licença MIT.

🤝 Suporte e Contribuições

Contribuições são muito bem-vindas! Sinta-se à vontade para abrir uma Issue ou enviar um Pull Request.