Skip to content

About

API de captação de leads em produção numa empresa real. Recebe formulários de landing pages, grava no CRM (Monday.com), envia conversões para a Meta (Conversions API) e processa vendas da Hotmart via webhook. Node.js + Express + MySQL, fila sem perda de leads, LGPD e 61 testes.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

lead-capture-api

API em Node.js que recebe os formulários das landing pages e entrega cada lead a três lugares:

  • o CRM (Monday.com);
  • a Meta, como evento de conversão (Conversions API);
  • um grupo da equipe no Telegram.

Ela também processa o webhook de pagamentos da Hotmart, atualizando a etapa do cliente no CRM a cada compra ou reembolso.

Node.js Express Testes Status

🏢 Usada em produção por uma empresa de consultoria e educação, recebendo as inscrições de várias landing pages e as vendas do produto digital. Marca, domínios e IDs foram trocados por valores genéricos.

📈 Impacto

  • Zero cadastro manual. O lead entra no CRM com nome, contato, faixa de faturamento, funil de origem e campanha.
  • Confirmação instantânea. Antes, quando o CRM ficava lento, o formulário levava 10 a 15 segundos para confirmar. Agora a resposta é imediata, e durante uma queda do Monday.com nenhuma inscrição foi perdida.
  • Anúncios mais eficientes. O evento de cadastro sai pelo servidor para a Meta, deduplicado com o pixel, e ajuda o algoritmo a achar leads parecidos.
  • Vendas rastreadas por campanha. Cada compra na Hotmart chega ao CRM e ao Telegram com a origem do anúncio, o que permite medir o retorno de cada canal.

🔌 Integrações

Serviço Uso
Monday.com (GraphQL + OAuth) Busca por e-mail ou telefone, criação e atualização do lead, etapas protegidas
Meta Conversions API CompleteRegistration com dados em hash e event_id; modo de teste com test_event_code
Hotmart Webhooks Compra aprovada ou completa, reembolso, chargeback e reclamação
Telegram Bot API Avisos de venda, de lead que não chegou ao CRM e de sistema fora do ar
MySQL Fila de leads, aceites (LGPD), rate limit, eventos da Hotmart e tokens OAuth
Landing pages (Squarespace) Formulários com origem, UTMs e aceites

O que ela faz

Captação (POST /api/workshop/lead)

  1. Valida e normaliza os dados: nome, e-mail, WhatsApp (com DDD), Instagram, faixa de faturamento e aceites de privacidade.
  2. Descobre a origem do lead pela página e pelo parâmetro ?origem= e escolhe o funil do CRM.
  3. Grava o lead numa fila no MySQL e responde 202 na hora.
  4. Em segundo plano:
    • procura a pessoa no CRM por e-mail ou telefone e atualiza o cadastro (ou cria um novo);
    • envia o CompleteRegistration para a Meta, com dados com hash e event_id para deduplicar com o pixel.
  5. Se o CRM estiver fora, o lead fica na fila e é reenviado com novas tentativas. Quando um lead não chega ao CRM, a equipe recebe um aviso no Telegram.

Pagamentos (POST /api/hotmart/webhook)

  • Autentica pelo header X-HOTMART-HOTTOK, com comparação em tempo constante.
  • Grava cada evento com uma chave única, então reenvios da Hotmart são ignorados.
  • Compra aprovada: o cliente vai para "Cliente Low Ticket" no CRM e a equipe recebe um aviso com a origem da venda, lida do parâmetro sck.
  • Reembolso ou chargeback: muda a etapa no CRM, mas só se o cliente ainda estava na etapa da compra. Etapas protegidas, como clientes de consultoria, nunca são sobrescritas.

LGPD

  • Cada aceite fica registrado com data, página e versão do texto. A exportação em CSV fica atrás de autenticação.
  • Uma limpeza automática apaga dados pessoais antigos da fila.
  • A resposta do formulário é sempre a mesma, para não revelar se a pessoa já existe no CRM.

Operação

  • GET /health: versão e estado do banco.
  • Um vigia confere outro sistema e avisa no Telegram quando ele cai ou volta.
  • Rate limit por IP, guardado no MySQL.
  • CORS liberado só para as origens permitidas.

Estrutura

src/
  routes/        rotas Express (workshop, hotmart, meta, monday, health)
  services/      regras: entrega do lead, fila, Monday GraphQL, Meta CAPI, Hotmart, Telegram, vigia
  repositories/  acesso ao MySQL (fila, aceites, rate limit, eventos da Hotmart, OAuth)
  middleware/    CORS, rate limit, basic auth
  utils/         normalização do lead, origem, CSV, criptografia
sql/             migrações das tabelas
test/            61 testes com node --test (fetch e banco simulados)

Rodando

npm ci
npm test
cp .env.example .env   # preencha banco, token do CRM e pixel
npm start

As tabelas estão em sql/. Todas as variáveis estão comentadas no .env.example.

🧩 Faz parte de um conjunto de 3 sistemas

Os três rodam juntos em produção, e esta API recebe os leads:

Repositório Papel
lead-capture-api Capta os leads das landing pages, CRM, Meta Conversions API e Hotmart
whatsapp-assistant Atendimento no WhatsApp, agendamento, lembretes e sorteios
admin-dashboard Painel da equipe: leads, reuniões, sorteios e saúde das integrações

Stack

Node.js 22 · Express 5 · MySQL (mysql2) · Monday.com GraphQL API · Meta Conversions API · Hotmart Webhooks · Telegram Bot API.

About

API de captação de leads em produção numa empresa real. Recebe formulários de landing pages, grava no CRM (Monday.com), envia conversões para a Meta (Conversions API) e processa vendas da Hotmart via webhook. Node.js + Express + MySQL, fila sem perda de leads, LGPD e 61 testes.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages