Skip to content

API-REFERENCE.md

Latest commit

 

History

History
321 lines (252 loc) · 8.24 KB

API-REFERENCE.md

File metadata and controls

321 lines (252 loc) · 8.24 KB

🔌 Referência da API - n8n-nodes-hotmart

Documentação completa de todas as operações disponíveis nos nós Hotmart.

📋 Visão Geral

O n8n-nodes-hotmart oferece dois nós principais:

  • 🔧 Hotmart - Operações da API (GET, POST, etc.)
  • 📡 Hotmart Trigger - Webhooks para receber eventos

🔧 Nó Hotmart

💰 Vendas (Sales)

getHistoricoVendas - Histórico de Vendas

Obtenha o histórico completo de vendas com filtros avançados.

Parâmetros:

  • dateMode - Modo de filtro por data (all/list/manual)
  • startDate - Data inicial (formato: YYYY-MM-DD)
  • endDate - Data final (formato: YYYY-MM-DD)
  • quickPeriod - Períodos pré-definidos (today/yesterday/last7days/etc.)
  • statusMode - Filtro por status (all/list/manual)
  • productMode - Filtro por produto (all/list/manual)

Exemplo de Resposta:

{
  "transaction": "HP123456789",
  "status": "APPROVED",
  "buyer": {
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "product": {
    "name": "Curso de Python",
    "id": 123456
  },
  "purchase": {
    "price": {
      "value": 19900,
      "currency_value": "BRL"
    },
    "approved_date": "2024-01-15T10:30:00.000Z"
  }
}

getComissoesVendas - Comissões de Vendas

Relatório detalhado de comissões ganhas como produtor, afiliado ou co-produtor.

getResumoVendas - Sumário de Vendas

Métricas consolidadas e KPIs de vendas para análise de performance.

getParticipantesVendas - Participantes de Vendas

Identifica todos os envolvidos em cada venda (produtores, afiliados, co-produtores).

getDetalhamentoPrecos - Detalhamento de Preços

Breakdown completo de valores: preço bruto, taxas, impostos e valor líquido.

solicitarReembolso - Solicitar Reembolso

Processa reembolso de uma venda (ação irreversível - requer confirmação).

📋 Assinaturas (Subscriptions)

getAll - Obter Assinaturas

Lista todas as assinaturas com filtros avançados.

Parâmetros:

  • returnAll - Retornar todos os registros (true/false)
  • limit - Limite de registros (padrão: 50)
  • statusMode - Filtro por status (all/active/inactive/etc.)
  • dateMode - Filtro por período
  • subscriberMode - Filtro por assinante

getSummary - Sumário de Assinaturas

Dados sumarizados das assinaturas com métricas de retenção.

getTransactions - Transações de Assinatura

Lista transações detalhadas de assinaturas.

getPurchases - Compras de Assinantes

Lista compras específicas de uma assinatura.

cancel - Cancelar Assinatura

Cancela uma assinatura específica.

cancelList - Cancelar Lista de Assinaturas

Cancela múltiplas assinaturas em lote.

reactivate - Reativar e Cobrar Assinatura

Reativa e cobra uma assinatura cancelada.

reactivateList - Reativar Lista de Assinaturas

Reativa e cobra múltiplas assinaturas.

changeBillingDate - Alterar dia de Cobrança

Altera o dia de cobrança de uma assinatura.

🛒 Produtos (Products)

getAll - Listar Produtos

Lista todos os produtos disponíveis.

Exemplo de Resposta:

{
  "id": 123456,
  "name": "Curso de JavaScript",
  "status": "ACTIVE",
  "price": 29900,
  "currency": "BRL",
  "description": "Aprenda JavaScript do zero",
  "category": "programming"
}

🎫 Cupons (Coupons)

create - Criar Cupom

Cria um novo cupom de desconto.

Parâmetros:

  • code - Código do cupom
  • discount_percentage - Percentual de desconto
  • max_uses - Máximo de usos
  • valid_until - Data de validade

get - Obter Cupom

Obter informações de um cupom específico.

delete - Excluir Cupom

Remove um cupom existente.

👥 Área de Membros (Club)

getAll - Obter Alunos

Lista todos os alunos da área de membros.

getModules - Obter Módulos

Lista todos os módulos do curso.

getPages - Obter Páginas

Lista páginas de um módulo específico.

getProgress - Progresso do Aluno

Obtém o progresso de um aluno específico.

🎟️ Eventos (Tickets)

getAll - Lista de Ingressos e Participantes

Lista ingressos e participantes de um evento.

getInfo - Informações do Evento

Obter informações detalhadas de um evento.

💳 Negociação (Negotiate)

generateNegotiation - Gerar Negociação

Gera uma negociação para pagamento de parcelas.

📡 Nó Hotmart Trigger

Modos de Operação

🔗 Modo Padrão

Recebe todos os eventos em uma saída única.

🧠 Modo Smart

Separa automaticamente cada tipo de evento em saídas distintas (15 outputs).

🚀 Modo Super Smart

Separa compras únicas, novas assinaturas e renovações (18 outputs).

Tipos de Eventos Suportados

📦 Eventos de Compra

  • PURCHASE_APPROVED - Compra aprovada
  • PURCHASE_COMPLETE - Compra completa
  • PURCHASE_CANCELED - Compra cancelada
  • PURCHASE_REFUNDED - Compra reembolsada
  • PURCHASE_CHARGEBACK - Chargeback
  • PURCHASE_BILLET_PRINTED - Boleto/PIX gerado
  • PURCHASE_DELAYED - Compra atrasada
  • PURCHASE_PROTEST - Protesto
  • PURCHASE_OUT_OF_SHOPPING_CART - Saiu do carrinho
  • PURCHASE_EXPIRED - Compra expirada

📋 Eventos de Assinatura

  • SUBSCRIPTION_CANCELLATION - Cancelamento de assinatura
  • SWITCH_PLAN - Mudança de plano
  • UPDATE_SUBSCRIPTION_CHARGE_DATE - Alteração de data de cobrança

👥 Eventos de Área de Membros

  • CLUB_FIRST_ACCESS - Primeiro acesso
  • CLUB_MODULE_COMPLETED - Módulo completado

Estrutura de Dados do Webhook

{
  "id": "uuid-do-evento",
  "creation_date": "2024-01-15T10:30:00.000Z",
  "event": "PURCHASE_APPROVED",
  "version": "2.0.0",
  "data": {
    "product": {
      "id": 123456,
      "name": "Curso de Python",
      "ucode": "abc123"
    },
    "buyer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "12345678900"
    },
    "purchase": {
      "transaction": "HP123456789",
      "status": "APPROVED",
      "approved_date": "2024-01-15T10:30:00.000Z",
      "price": {
        "value": 19900,
        "currency_value": "BRL"
      }
    }
  }
}

🤖 IA Conversacional

Comandos Suportados

Análise de Vendas

"Vendas de hoje com análise de performance"
"Compare receita deste mês com o anterior"
"Produtos com maior ticket médio"
"Vendas por afiliado dos últimos 7 dias"
"Qual horário do dia vende mais?"

Gestão de Assinaturas

"Assinaturas que vencem esta semana"
"Clientes em risco de churn"
"Taxa de renovação do último trimestre"
"Assinaturas canceladas hoje"
"Renovações automáticas pendentes"

Análises Avançadas

"ROI por canal de marketing"
"Produtos com menor taxa de conversão"
"Afiliados top performers este mês"
"Análise de sazonalidade de vendas"
"Lifetime value por segmento"

Formato de Resposta da IA

{
  "data": [...], // Dados brutos da API
  "insights": {
    "summary": "Resumo em português",
    "metrics": {
      "total_sales": 1250,
      "revenue": "R$ 156.750,00",
      "conversion_rate": "12.3%"
    },
    "recommendations": [
      "Foque em produtos com maior LTV",
      "Otimize campanhas para horário de pico (14h-16h)"
    ]
  },
  "ai_context": {
    "query_processed": "vendas dos últimos 30 dias",
    "confidence": 0.95,
    "processing_time": "1.2s"
  }
}

📊 Metadados de Paginação

Todos os endpoints paginados incluem metadados automáticos:

{
  "data": [...],
  "pagination": {
    "total_results": 1500,
    "items_returned": 50,
    "has_more": true,
    "status": "DADOS_PARCIAIS",
    "warning": "Considere usar filtros para otimizar a consulta"
  }
}

🚨 Códigos de Erro

Código Descrição Solução
401 Não autorizado Verificar credenciais
403 Acesso negado Verificar permissões da aplicação
429 Rate limit Aguardar ou implementar retry
500 Erro interno Tentar novamente em alguns minutos

🔗 Links Úteis

📝 Nota: Esta documentação refere-se à versão 0.9.5 do n8n-nodes-hotmart.