n8n-nodes-conversor-plataformas
v0.6.5
Published
Community node n8n que normaliza payloads de webhooks de plataformas de venda (Hotmart, Guru, Eduzz, TMB) para um schema canonico de compra.
Maintainers
kokopelliadvancedtrackingReadme
n8n-nodes-conversor-plataformas
Community node Kokopelli ADTK Convert — um node, duas actions:
- Converter Gateway — normaliza webhooks de plataformas de venda
(Hotmart, Guru, Eduzz, TMB) para um schema canonico de compra, pronto para
alimentar
upsert_purchase_data()sem remapear campos a cada plataforma. - Converter GTM — filtra eventos internos do GTM e normaliza os eventos de negocio para o schema de eventos (todos os campos em string).
Ambas aceitam o item do Webhook node ({ headers, body }) e o de fila
RabbitMQ/AMQP em qualquer forma: { content: { body } } (envelope), { content: <body> }
(body cru direto no content), com content/body como objeto, array ou string JSON
nao-parseada (RabbitMQ sem "JSON Parse Body"). Em todos os casos o body real e
desembrulhado antes do mapeamento.
Status
🟢 4 plataformas implementadas e testadas: Hotmart, Guru, Eduzz e TMB —
todas com compra aprovada e reembolso/estorno cobertos. Auto-deteccao por
user-agent + assinatura do body. Os mapas de status seguem o enum oficial de
cada plataforma (developers.hotmart.com Webhook 2.0.0; docs.digitalmanager.guru).
Kiwify e PagTrust entram quando houver payload real.
Convencao de status: reembolso/chargeback consumado -> rejected; contestacao
ainda em aberto (Hotmart DISPUTE/protesto, Guru dispute/"Reembolso Sol.") -> pending.
Action: Converter Gateway — schema canonico (saida)
| campo | tipo | observacao |
|---|---|---|
| nome | string | null | |
| email | string | null | lowercase/trim |
| telefone | string | null | so digitos |
| valor | number | null | total da compra, na moeda de moeda |
| moeda | string | null | BRL/EUR/USD (Hotmart internacional pode vir EUR/USD) |
| id_transacao | string | null | id de dedup/upsert |
| status | pending | approved | rejected | null | |
| nome_produto | string | null | produto principal |
| id_produto | string | null | id do produto principal |
| plataforma | enum | hotmart|guru|eduzz|tmb |
| utm_source | string | null | Guru source.utm_*, Eduzz data.utm.*, TMB utm_* |
| utm_medium | string | null | |
| utm_campaign | string | null | |
| utm_content | string | null | |
| utm_term | string | null | so Guru envia |
| xcod | string | null | rastreamento Hotmart (data.purchase.origin.xcod) |
| itens | ItemCompra[] | detalhamento por produto |
ItemCompra: { nome, id, valor, quantidade, tipo }, onde tipo ∈ principal |
order_bump | desconhecido. Heuristica atual: 1º item = principal, demais =
order_bump (calibravel com payload real rotulado).
UTM x xcod: Hotmart nao envia
utm_*no webhook — rastreia viaxcod(que pode encodar varios valores separados por_). As outras plataformas mandam UTMs. Logo, Hotmart preenchexcode deixautm_*nulo; as demais o inverso.
Formatos de entrada: o node desembrulha o item do Webhook node (
{ headers, body }) e o de fila RabbitMQ/AMQP em qualquer forma —contentcom envelope ({ content: { body } }) ou body cru ({ content: <body> }), econtent/bodycomo objeto, array ou string JSON. Fila e webhook produzem a mesma saida. Obs: em fila com body cru nocontentnao ha headers HTTP, entao campos derivados de header (ex: IP viax-real-ip) so vem se o produtor injetarip_overrideno body.
Moeda: o
valorpermanece na moeda original da transacao; quem soma receita downstream deve agrupar/converter pormoeda. Sem alteracao de banco.
Parametros da action Converter Gateway:
- Plataforma —
Auto-detectar(pela estrutura do JSON) ou plataforma fixa. - Manter Payload Original — anexa o JSON bruto em
_original.
Action: Converter GTM
Processa eventos vindos do GTM (server-side). Filtra os eventos internos do
GTM (sem event_name) e normaliza os de negocio para a linha de eventos, com
todos os campos em string (numero -> string, objeto -> JSON, ausente -> "").
Parametros:
- Eventos Permitidos — allowlist de
event_nameseparada por virgula. Vazio = todos os eventos passam (inclusive sem nome). Use para restringir aos eventos de negocio. - Campos De Saida — escolha quais campos sair no output. Vazio = todos.
- Manter Payload Original — anexa o body bruto em
_original.
Mapeamento principal: event_name ← event_name;
senha_atendimento ← senha_de_atendimento;
email ← email/email_address/user_data.email_address (normalizado: lowercase + trim);
telefone ← telefone/phone/phone_number/user_data.phone_number (normalizado: so digitos);
nome/sobrenome ← first_name/last_name (fallback user_data.address.*);
xcod ← xcod (mesma hierarquia das UTMs no payload do GTM);
fbc/fbp ← common_cookie._fbc/_fbp (o common_cookie bruto nao vai pro output —
so serve de fonte do fbc/fbp); gclid/gbraid/wbraid/ttclid ← campo direto
ou query da page_location; ip ← ip_override
(fallback header x-real-ip/x-forwarded-for); pagina_origem ← page_location.
Os campos *_entrada sao parseados da query
string da page_location (UTMs como vieram na URL de primeiro toque). id e
data_criacao ficam de fora (gerados pelo banco).
Saida tudo em texto + chaves vazias omitidas: todo campo sai como string ("para facilitar manipulacao") — numero/boolean viram texto, recursivamente (incl.
valor,quantidadee os campos deitensdos gateways). Campo ausente na entrada nao aparece no output (sem a chave, em vez de""/null), em qualquer nivel. Vale para GTM e para os 4 gateways. Quando o banco precisar do campo sempre presente, use COALESCE/?? ''no insert.
Desenvolvimento
npm install
npm run dev # n8n-node dev: sobe n8n com o node + hot-reload
npm test # vitest (fixtures sanitizadas)
npm run smoke -- caminho.json # roda os mappers contra um export real do n8n
npm run lint
npm run build
npm run release # publica no npmInstalacao (instancia unica self-hosted)
Settings→Community Nodes→Install- Digitar
n8n-nodes-conversor-plataformas - Aceitar o aviso de risco →
Install
Licenca
MIT