n8n-nodes-hotmart

Este pacote contém nós personalizados para integrar a API Hotmart com o n8n, permitindo automação completa de operações na plataforma líder de produtos digitais da América Latina.

A Hotmart é uma plataforma de negócios digitais para criação, hospedagem e venda de produtos digitais e assinaturas, com recursos para gerenciamento de membros, pagamentos e análises de vendas.

n8n é uma plataforma de automação de fluxo de trabalho fair-code licensed.

Índice

• Instalação
• Nós Disponíveis
• Operações Suportadas
• Arquitetura
• Credenciais
• Compatibilidade
• Exemplos de Uso
• Webhooks Hotmart
• Recursos e APIs
• Desenvolvimento
• Solução de Problemas
• Histórico de Versões
• Licença
• Contribuição
• Autores e Mantenedores

Instalação

Instalação via n8n

A maneira mais simples de instalar é diretamente através da interface do n8n:

1. Abra seu n8n
2. Vá para Configurações > Nós Comunitários
3. Pesquise por "n8n-nodes-hotmart"
4. Clique em Instalar
5. Reinicie seu n8n

Instalação Manual

Para instalação manual, siga os passos abaixo:

1. Instalar as dependências do projeto

No diretório raiz do seu projeto:

npm install

Este comando vai instalar todas as dependências listadas no seu package.json, como TypeScript, Gulp, e as bibliotecas core do n8n.

2. Compilar os nodes

npm run build

Este comando executa o script de build definido no seu package.json, que geralmente inclui:

• Limpeza dos diretórios de saída (dist/, nodes/, credentials/)
• Compilação do TypeScript
• Execução das tarefas Gulp para copiar ícones e outros recursos

3. Verificar a compilação

# Verificar estrutura de diretórios
ls -la dist/

# Verificar se os ícones foram copiados corretamente
ls -la dist/nodes/*/

4. Para desenvolvimento contínuo (Opcional)

npm run dev

Próximos passos após compilar seu node n8n

1. Verificar a compilação

ls -la dist/
ls -la dist/nodes/
ls -la dist/credentials/ # se aplicável

Certifique-se de que:

• Os arquivos JavaScript (.js) foram gerados
• Os ícones (.svg ou .png) foram copiados corretamente
• Os arquivos de mapeamento (.map) estão presentes (para depuração)

2. Testar localmente

Opção A: Instalação local a partir do arquivo

# No diretório do seu node, crie um pacote
npm install
npm run build
npm pack

# Isso criará um arquivo .tgz (ex: n8n-nodes-hotmart-0.4.0.tgz)
# Instale-o na sua instalação do n8n
cd ~/.n8n/node
npm install /caminho/para/n8n-nodes-hotmart-0.4.0.tgz

3. Reiniciar o n8n

# Se estiver usando n8n instalado globalmente
n8n stop
n8n start

# Ou se estiver usando em modo desenvolvimento
n8n restart

Nós Disponíveis

Hotmart

O nó Hotmart permite interagir com a API Hotmart para acessar e gerenciar todos os recursos da plataforma.

Características:

• ✅ Suporte completo para API RESTful Hotmart
• ✅ Paginação automática para conjuntos grandes de dados
• ✅ Formatação inteligente dos retornos da API
• ✅ Tratamento de erros robusto com mensagens específicas

Hotmart Trigger

O nó Hotmart Trigger permite receber eventos da Hotmart via webhook, possibilitando automação baseada em eventos.

Características:

• ✅ Três modos de operação: Padrão, Smart e Super Smart
• ✅ Separação automática de tipos de eventos
• ✅ Detecção inteligente de assinaturas e métodos de pagamento
• ✅ Processamento avançado de eventos para boleto e PIX

Operações Suportadas

Hotmart

Assinaturas

Operação	Descrição	Parâmetros Obrigatórios
Obter Assinaturas	Lista todas as assinaturas com suporte a filtros e paginação	Nenhum
Cancelar Assinatura	Cancela uma assinatura específica	ID da Assinatura
Cancelar Lista de Assinaturas	Cancela múltiplas assinaturas	Lista de IDs
Alterar Dia de Cobrança	Modifica a data de cobrança de uma assinatura	ID da Assinatura, Novo Dia
Obter Compras de Assinantes	Lista compras de um assinante específico	ID do Assinante
Reativar e Cobrar Assinatura	Reativa uma assinatura cancelada	ID da Assinatura
Sumário de Assinaturas	Obtém dados sumarizados de assinaturas	Nenhum
Transações de Assinatura	Lista transações relacionadas a assinaturas	Nenhum

Vendas

Operação	Descrição	Parâmetros Obrigatórios
Histórico de Vendas	Obter todas as transações de vendas com filtros	Nenhum
Sumário de Vendas	Relatório resumido de vendas	Nenhum
Detalhamento de Preços	Visualizar detalhamento de preços por venda	ID da Venda
Comissões de Vendas	Listar comissões por transação	Nenhum
Participantes de Vendas	Visualizar produtores e afiliados	Nenhum
Solicitar Reembolso	Reembolsar uma venda específica	ID da Venda

Produtos

Operação	Descrição	Parâmetros Obrigatórios
Obter Produtos	Listar todos os produtos disponíveis	Nenhum

Cupons

Operação	Descrição	Parâmetros Obrigatórios
Criar Cupom	Gerar um novo cupom para produtos	Nome do Cupom, Desconto, Produto
Obter Cupom	Obter detalhes de um cupom existente	Nome do Cupom
Excluir Cupom	Remover um cupom	Nome do Cupom

Área de Membros (Club)

Operação	Descrição	Parâmetros Obrigatórios
Obter Alunos	Listar todos os alunos	ID do Produto
Obter Módulos	Listar módulos de um produto	ID do Produto
Obter Páginas	Listar páginas de um módulo	ID do Produto, ID do Módulo
Obter Progresso	Visualizar progresso de um aluno	ID do Produto, Email do Aluno

Ingressos

Operação	Descrição	Parâmetros Obrigatórios
Obter Informações do Evento	Detalhes do evento	ID do Evento
Listar Ingressos	Verificar ingressos e participantes	ID do Evento

Hotmart Trigger

O nó Hotmart Trigger oferece três modos de operação:

Modo Padrão

Recebe um evento específico ou todos os eventos em uma única saída.

Modo Smart

Separa automaticamente cada tipo de evento em saídas distintas, facilitando a criação de fluxos específicos.

Modo Super Smart

Separa compras únicas, novas assinaturas e renovações de assinaturas, permitindo mensagens personalizadas para cada situação.

Novos Metadados no Super Smart Mode:

{
  "event_type": "PURCHASE_APPROVED",
  "event_data": { ... },
  
  // Metadados enriquecidos (v0.3.1+)
  "isSubscription": true,
  "isRenewal": false,
  "paymentType": "CREDIT_CARD",
  
  // Informações de pagamento parcelado
  "hasInstallments": true,
  "installmentsCount": 12,
  "installmentValue": 97.00,
  
  // Informações de abandono (quando aplicável)
  "isCartAbandonment": false,
  "cartAbandonmentData": null
}

O modo Super Smart permite criar fluxos de trabalho sofisticados baseados nestes metadados, como enviar ofertas especiais para clientes de alto valor, criar lembretes para pagamentos parcelados, ou implementar estratégias de recuperação de carrinho abandonado.

Arquitetura

O pacote segue uma arquitetura modular para integrar-se com a API Hotmart:

n8n-nodes-hotmart/
   credentials/
      HotmartOAuth2Api.credentials.ts     # Autenticação OAuth2
   nodes/
      Hotmart/
         Hotmart.node.json                # Definição do nó
         Hotmart.node.ts                  # Ponto de entrada do nó
         hotmart.svg                      # Logo do Hotmart
         v1/
            HotmartV1.node.ts            # Implementação da versão 1
            actions/                     # Recursos e operações
               club/                    # Área de membros
               coupon/                  # Cupons
               product/                 # Produtos
               sales/                   # Vendas
               subscription/            # Assinaturas
               tickets/                 # Ingressos
            config/                     # Configurações centralizadas
               api.config.ts           # URLs e endpoints
               constants.ts            # Constantes e enums
            errors/                     # Tratamento de erros
               HotmartApiError.ts      # Classe personalizada de erro
               errorHandler.ts         # Manipuladores de erro
            helpers/                    # Funções auxiliares
               dateUtils.ts            # Utilidades para datas
               outputFormatter.ts      # Formatação de resultados
               pagination.ts           # Paginação automática
            logging/                    # Sistema de logs
               logger.ts               # Logger estruturado
            transport/                  # Comunicação HTTP
               request.ts              # Cliente HTTP
            types/                      # Definições de tipos
               common.types.ts         # Tipos compartilhados
               subscription.types.ts   # Tipos específicos
               webhook.types.ts        # Tipos e processamento de webhooks
         HotmartTrigger.node.ts         # Nó de trigger para webhooks

Fluxo de Execução

1. Hotmart.node.ts define a entrada do nó e seus recursos
2. HotmartV1.node.ts implementa a versão 1 da API
3. A camada de transporte gerencia requisições HTTP e autenticação
4. Helpers como pagination.ts e dateUtils.ts fornecem funcionalidades comuns
5. O sistema de logs e tratamento de erros garantem robustez

Sistema de Processamento de Webhooks

O processamento de webhooks foi significativamente aprimorado na versão 0.3.1:

1. Recebimento e Validação: O HotmartTrigger.node.ts recebe e valida eventos
2. Processamento de Eventos: O módulo webhook.types.ts processa os eventos brutos
3. Detecção Inteligente:
   • Identificação de tipo de pagamento (PIX, Boleto, Cartão, etc.)
   • Detecção de assinaturas vs. compras únicas
   • Reconhecimento de renovações vs. novas assinaturas
   • Processamento de pagamentos parcelados
4. Enriquecimento de Metadados:
   • Extração de informações de pagamento detalhadas
   • Identificação e processamento de abandonos de carrinho
5. Saídas Formatadas: Os eventos processados são distribuídos para as saídas apropriadas no modo Smart e Super Smart

Credenciais

Este pacote utiliza autenticação OAuth 2.0 com client credentials. Para configurar:

1. Acesse o Hotmart Developers
2. Crie uma credencial para o ambiente desejado (produção ou sandbox)
3. Anote o Client ID e Client Secret
4. Configure essas credenciais no n8n, selecionando "Hotmart OAuth2 API"

Campos de Credenciais

Campo	Descrição	Obrigatório
Client ID	Identificador do cliente fornecido pela Hotmart	Sim
Client Secret	Chave secreta do cliente fornecida pela Hotmart	Sim
Ambiente	Produção ou Sandbox	Sim

Compatibilidade

• Requer n8n versão 0.214.0 ou superior
• Testado com n8n versões 0.214.0 até 1.3.0
• Não requer dependências externas
• Funcionamento em ambientes Docker e instalações locais

Exemplos de Uso

Listar Assinaturas Ativas e Enviar Notificação

Verifica diariamente as assinaturas ativas e envia notificações para aquelas que estão prestes a vencer.

1. Nó Trigger: Agendamento (a cada dia)
2. Nó Hotmart:
   • Recurso: Assinatura
   • Operação: Obter Assinaturas
   • Retornar Todos os Resultados: Sim
   • Filtros: Status = ACTIVE
3. Nó Filter: Filtrar assinaturas que vencem em 3 dias
4. Nó WhatsApp/Email: Enviar notificação com lista de assinaturas

// Exemplo de código para filtrar assinaturas que vencem em 3 dias
const today = new Date();
const expiryDate = new Date(item.json.next_charge_date);
const daysDifference = Math.ceil((expiryDate - today) / (1000 * 60 * 60 * 24));
return daysDifference === 3;

Cancelar Assinaturas Atrasadas

Identifica assinaturas atrasadas e as cancela automaticamente.

1. Nó Trigger: Webhook ou Agendamento
2. Nó Hotmart:
   • Recurso: Assinatura
   • Operação: Obter Assinaturas
   • Filtros: Status = DELAYED
3. Nó Loop: Iterar sobre as assinaturas atrasadas
4. Nó Hotmart:
   • Recurso: Assinatura
   • Operação: Cancelar Assinatura
   • ID da Assinatura: ={{$json.id}}
   • Motivo: "Cancelamento automático por atraso"

Automação de Webhook para Vendas

Utiliza o webhook Hotmart para processar diferentes tipos de eventos de vendas e assinaturas.

1. Nó Hotmart Trigger:
   • Modo: Super Smart
   • Configurar webhook no painel Hotmart apontando para a URL fornecida
2. Conecte diferentes fluxos para cada tipo de saída:
   • Compra Única: Enviar email de boas-vindas para produto único
   • Assinatura: Enviar email específico para novos assinantes
   • Renovação: Agradecer pela renovação da assinatura

Webhooks Hotmart

Para configurar um webhook Hotmart:

1. No painel da Hotmart, acesse Ferramentas > Webhooks
2. Clique em Criar webhook
3. Insira a URL fornecida pelo nó Hotmart Trigger
4. Selecione os eventos que deseja receber

Eventos Suportados

• PURCHASE_APPROVED: Compra aprovada
• PURCHASE_COMPLETE: Compra completa
• PURCHASE_CANCELED: Compra cancelada
• PURCHASE_REFUNDED: Compra reembolsada
• PURCHASE_CHARGEBACK: Compra com chargeback
• PURCHASE_BILLET_PRINTED: Boleto impresso
• PURCHASE_PROTEST: Compra em disputa
• PURCHASE_EXPIRED: Compra expirada
• PURCHASE_DELAYED: Compra atrasada
• PURCHASE_OUT_OF_SHOPPING_CART: Abandono de carrinho
• SUBSCRIPTION_CANCELLATION: Assinatura cancelada
• SWITCH_PLAN: Troca de plano de assinatura
• UPDATE_SUBSCRIPTION_CHARGE_DATE: Troca de dia de cobrança
• CLUB_FIRST_ACCESS: Primeiro acesso à área de membros
• CLUB_MODULE_COMPLETED: Módulo de curso completado

Metadados Avançados nos Eventos (v0.3.1+)

A partir da versão 0.3.1, o modo Super Smart inclui metadados enriquecidos que fornecem informações detalhadas sobre os eventos:

Detecção de Parcelamento

• hasInstallments: Indica se o pagamento foi parcelado
• installmentsCount: Número de parcelas do pagamento
• installmentValue: Valor de cada parcela

Abandono de Carrinho

• isCartAbandonment: Indica se o evento é de abandono de carrinho
• cartAbandonmentData: Dados detalhados sobre o carrinho abandonado
• recoveryUrl: URL para recuperação do carrinho (quando disponível)
• abandonmentReason: Motivo do abandono quando identificável

Exemplo de Uso

// Verificar se é um pagamento parcelado
if ($node["Hotmart Trigger"].json.hasInstallments) {
  // Número de parcelas: $node["Hotmart Trigger"].json.installmentsCount
  // Valor de cada parcela: $node["Hotmart Trigger"].json.installmentValue
}

// Recuperar carrinho abandonado
if ($node["Hotmart Trigger"].json.isCartAbandonment) {
  // URL para recuperação: $node["Hotmart Trigger"].json.cartAbandonmentData.recoveryUrl
}

Recursos e APIs

• Taxa de Limitação: A API Hotmart tem um limite de 60 requisições por minuto
• Paginação: Suporte para 50-100 itens por página, com paginação automática
• Sandbox: Ambiente de teste disponível para desenvolvimento seguro
• Formatos: Todos os endpoints usam JSON para requisições e respostas

Documentação de Referência

• Documentação da API Hotmart
• Webhooks da Hotmart
• Autenticação API Hotmart
• Documentação de nós comunitários n8n

Estrutura do Código

O código segue uma arquitetura modular para facilitar manutenção e extensão:

• Recursos e Operações: Cada recurso (subscription, sales, etc.) está em pasta separada
• Operações: Cada operação é um arquivo independente com sua própria lógica
• Configurações Centralizadas: Endpoints e constantes são mantidos em arquivos específicos
• Tratamento de Erros: Sistema robusto e específico para erros da API Hotmart
• Sistema de Log: Logs estruturados para facilitar depuração

Adicionando Novos Recursos

Para adicionar um novo recurso:

1. Crie uma nova pasta em nodes/Hotmart/v1/actions/
2. Implemente a estrutura básica:
   • Resource.resource.ts com operações agrupadas
   • Arquivo para cada operação (ex: getAll.operation.ts)
   • Adicione tipos em types/newResource.types.ts
3. Atualize o router em actions/router.ts
4. Adicione à descrição em actions/versionDescription.ts

Solução de Problemas

Problemas Comuns

Erro de Autenticação

• Verifique se as credenciais Client ID e Client Secret estão corretas
• Confirme se o ambiente (produção ou sandbox) está configurado corretamente
• Verifique se as credenciais têm as permissões necessárias no painel Hotmart

Webhook não recebe eventos

• Verifique se a URL do webhook está configurada corretamente no painel Hotmart
• Certifique-se de que o n8n está acessível publicamente
• Verifique os logs de execução para possíveis erros

Logs de Depuração

Para ativar logs de depuração, adicione as seguintes variáveis de ambiente:

export N8N_LOG_LEVEL=debug
export HOTMART_LOG_LEVEL=debug

Isso habilitará logs detalhados para ajudar na solução de problemas.

Relatando Problemas

Se encontrar algum problema, abra uma issue no GitHub com:

• Versão do n8n
• Versão do nó Hotmart
• Logs de erro
• Passos para reproduzir o problema

Histórico de Versões

0.4.5 (20/05/2025)

• Versão Inicial Lançada para o Público

0.4.4 (20/05/2025)

• Correção de bugs

0.4.3 (20/05/2025)

Corrigido

• Resolvido problema de ícones definitivamente por conta de permissões faltantes.

0.4.2 (19/05/2025)

Corrigido

• Resolvido problema de ícones desaparecendo após publicação
• Corrigida resolução de caminhos para ícones em diferentes níveis de diretório
• Ajustado processo de build para incluir corretamente diretório de 'actions'
• Desativada compilação incremental para garantir aplicação consistente de alterações

Melhorado

• Otimizado processo de build para maior confiabilidade
• Atualizada documentação interna de código

0.4.1 (19/05/2025)

Correções

• Corrigido problema de ícones desaparecendo após publicação no npm
• Atualizado processo de build para incluir corretamente diretório de ações
• Padronizadas referências aos arquivos de ícones

0.4.0 (18/05/2025)

Nova Estrutura de Build

• Implementação da nova estrutura para organização do código
• Melhoria no processo de build com verificação de integridade
• Aprimoramento do gulpfile.js para cópia e verificação de arquivos
• Nova configuração de TypeScript com foco em melhor gerenciamento de código

Correções na Instalação

• Solução definitiva para problemas "Cannot find module"
• Verificação rigorosa de estrutura de arquivos na instalação
• Documentação detalhada sobre a nova estrutura

Documentação

• Adição da nova seção sobre estrutura de build ao README
• Atualização do guia de desenvolvimento com novas práticas

0.3.2 (15/05/2025)

Correções Críticas

• Correção do problema "Cannot find module" para HotmartTrigger.node.js
• Correção do erro "Cannot find module './v1/HotmartV1.node'" na inicialização
• Implementação da "abordagem de cópia dupla" para garantir compatibilidade

Modificações

• Atualização do diretório de instalação de ~/.n8n/custom/ para ~/.n8n/nodes/node_modules/
• Aprimoramento do gulpfile.js para copiar corretamente arquivos em subdiretórios

0.3.1 (10/05/2025)

Aprimoramentos nos Webhooks e Super Smart Mode

• Implementação de metadados enriquecidos para eventos em webhook
• Detecção avançada de pagamentos parcelados com número de parcelas e valor
• Melhoria no processamento de eventos de abandono de carrinhos

Melhorias na Usabilidade

• Interface mais intuitiva no modo Super Smart
• Documentação expandida com exemplos de uso dos novos metadados
• Atualização das saídas do trigger para incluir campos de metadados

Correções

• Ajuste na detecção de tipo de pagamento para maior precisão
• Otimização de desempenho no processamento de webhooks
• Correção de tipos TypeScript para compatibilidade total

0.3.0 (05/05/2025)

Grandes Mudanças

• Implementado o novo nó HotmartTrigger para receber webhooks da Hotmart
• Removido o antigo HotmartRouter, substituído pelo HotmartTrigger

Novas Funcionalidades

• Adicionado modo Smart Trigger para criar fluxos de trabalho complexos sem nós condicionais
• Implementado modo Super Smart com separação automática de:
  • Compras únicas/normais
  • Novas assinaturas
  • Renovações de assinaturas
• Adicionada detecção automática de método de pagamento, separando PIX de Boleto
• Personalização dos nomes de saída para melhorar a experiência visual

Melhorias

• Sistema avançado de detecção de assinaturas usando vários métodos:
  • Verificação de dados de subscription.subscriber.code
  • Verificação de atributo purchase.is_subscription
  • Reconhecimento automático de eventos específicos de assinatura
• Adicionadas informações extras de pagamento como metadados:
  • paymentMethod: método de pagamento (PIX, BILLET, CREDIT_CARD, etc.)
  • paymentInfo: informações estruturadas (isBillet, isPix, isCard, isDigital)

Segurança

• Suporte para verificação de token HOTTOK enviado pelo Hotmart no cabeçalho
• Validação de eventos para evitar processamento de dados não reconhecidos

0.2.0 (30/04/2025)

Melhorias

• Implementada solução definitiva para paginação com 500 itens por página
• Adicionados logs de depuração para solucionar problemas de paginação
• Corrigido erro de compilação no arquivo pagination.ts

0.1.0 (15/04/2025)

Versão Inicial

• Implementado nó Hotmart com autenticação OAuth2
• Suporte para operações básicas:
  • Assinaturas
  • Vendas
  • Produtos
  • Cupons
  • Área de Membros (Club)
  • Ingressos
  • Negociação de Parcelas
• Paginação automática para retornar todos os resultados
• Integração com Sandbox e ambiente de produção

Licença

Este projeto está licenciado sob a Licença MIT.

Contribuição

Contribuições são bem-vindas! Para contribuir com o projeto:

1. Faça um fork do repositório
2. Crie uma branch com sua feature (git checkout -b feature/nova-funcionalidade)
3. Faça commit das suas mudanças (git commit -m 'Adiciona nova funcionalidade')
4. Envie para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Autores e Mantenedores

• Autor Principal - Thales Laray
• Contribuidores - Veja a lista completa de contribuidores