n8n-nodes-zapclass

Pacote de node customizado do n8n para integração com a API do ZapClass. Permite enviar mensagens de texto e mídia via WhatsApp através da plataforma ZapClass.

📦 Instalação

Via npm (quando publicado)

npm install n8n-nodes-zapclass

Desenvolvimento Local

1. Clone o repositório:

git clone https://github.com/zapclass/n8n-nodes-zapclass.git
cd n8n-nodes-zapclass

2. Instale as dependências:

npm install

3. Inicie o ambiente de desenvolvimento:

npm run dev

Isso iniciará o n8n com o node carregado e hot reload habilitado.

🚀 Recursos Implementados

Node: ZapClass API

Permite interação completa com a API do ZapClass para envio de mensagens WhatsApp.

23 Operações Disponíveis

📱 Operações de Gerenciamento

• Baixar Arquivo - Download de mídias recebidas (com suporte a transcrição via OpenAI)
• Buscar Mensagem - Pesquisar mensagens por ID, chat_id, message_source ou message_id
• Deletar Mensagem - Remover mensagens enviadas (remoção permanente)
• Editar Mensagem - Editar mensagens de texto (até 15 minutos após envio)
• Marcar Como Lida - Marcar até 50 mensagens como lidas
• Reagir à Mensagem - Adicionar ou remover reações emoji (mensagens até 7 dias)

📝 Mensagens de Texto

• Enviar Texto - Mensagens com suporte a:
  • Preview de link customizado (título, descrição, imagem)
  • Responder mensagens específicas
  • Mencionar contatos
  • Delay de envio
  • Rastreamento com message_source e message_id

📎 Envio de Mídia

• Enviar Imagem (JPEG, PNG - até 5 MB)
• Enviar Vídeo (3GP, MP4 - até 16 MB)
• Enviar Áudio (AAC, AMR, MP3, M4A, OGG - até 16 MB)
• Enviar Gravação (formato de áudio de voz)
• Enviar Documento (TXT, XLS, XLSX, DOC, DOCX, PPT, PPTX, PDF - até 100 MB)

🎯 Mensagens Interativas

• Enviar Lista - Listas interativas com seções e itens selecionáveis
• Enviar Botões - Botões interativos (máximo 3) com ações: reply, copy, call, URL
• Enviar Enquete - Enquetes com até 12 opções de votação
• Enviar Carrossel - Carrosséis de cards com imagens e botões

📍 Conteúdo Rico

• Enviar Contato - Cartões de contato com informações completas
• Enviar Localização - Localização com coordenadas geográficas
• Enviar Status - Status do WhatsApp (texto, imagem, vídeo, áudio)

Todas as operações suportam: delay, responder mensagens, menções, rastreamento e marcação de leitura.

🔑 Configuração

Credenciais ZapClass API

Para usar este node, você precisa:

1. Uma conta no ZapClass
2. Uma API Key (começa com zc_)

No n8n:

1. Vá em Credentials → New
2. Selecione ZapClass API
3. Insira sua API Key
4. Teste a conexão
5. Salve

💻 Desenvolvimento

Comandos Disponíveis

# Desenvolvimento com hot reload
npm run dev

# Build para produção
npm run build

# Build com watch mode
npm run build:watch

# Verificar erros de linting
npm run lint

# Corrigir erros de linting automaticamente
npm run lint:fix

# Criar nova release
npm run release

Estrutura do Projeto

n8n-nodes-zapclass/
├── credentials/
│   └── ZapClassApi.credentials.ts    # Definição de credenciais
├── nodes/
│   └── ZapClassApi/
│       ├── ZapClass.node.ts          # Node principal
│       ├── execute/
│       │   ├── index.ts              # Mapeamento de operações
│       │   ├── zapClassRequest.ts    # Helper de requisições
│       │   └── messages/
│       │       ├── text.ts           # Envio de texto
│       │       └── media.ts          # Envio de mídia
│       └── properties/
│           ├── index.ts              # Agregador de propriedades
│           ├── messages.operations.ts # Operações de mensagens
│           └── messages.fields.ts    # Campos das operações
├── icons/                            # Ícones do node
└── dist/                            # Build (gerado automaticamente)

Arquitetura

O node usa o padrão resource-operation:

1. Properties Layer: Define a interface do usuário

   • Recursos disponíveis (messages-api)
   • Operações por recurso (send-text, send-media)
   • Campos de entrada para cada operação

2. Execution Layer: Implementa a lógica de API

   • Funções de execução para cada operação
   • Helper zapClassRequest() para requisições autenticadas
   • Tratamento de erros em português

Adicionando Novas Operações

Consulte o arquivo CLAUDE.md para instruções detalhadas sobre como adicionar novas operações ao node.

📚 Recursos

• Documentação ZapClass - Documentação completa da API
• Documentação n8n - Guia completo de desenvolvimento de nodes
• n8n Community Forum - Obtenha ajuda da comunidade
• @n8n/node-cli - CLI tool usada neste projeto

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/NovaFuncionalidade)
3. Commit suas mudanças (git commit -m 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/NovaFuncionalidade)
5. Abra um Pull Request

📄 Licença

MIT

🏢 ZapClass

Este é um projeto oficial do ZapClass - Plataforma de automação e integração WhatsApp.

---

Desenvolvido com ❤️ pela equipe ZapClass