n8n-nodes-conversor-plataformas

Community node Kokopelli ADTK Convert — um node, duas actions:

1. Converter Gateway — normaliza webhooks de plataformas de venda
   (Hotmart, Guru, Eduzz, Virtu, Greenn, TMB, Kiwify) para um schema canonico de compra, pronto para
   alimentar upsert_purchase_data() sem remapear campos a cada plataforma.
2. 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

🟢 7 plataformas implementadas e testadas: Hotmart, Guru, Eduzz, Virtu, Greenn, TMB
e Kiwify — 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;
Greenn/pagar.me; Virtu; docs.kiwify.com.br). PagTrust entra quando houver payload real.

Convencao de status: reembolso/chargeback consumado -> rejected; contestacao
ainda em aberto (Hotmart DISPUTE/protesto, Guru dispute/"Reembolso Sol.",
Kiwify pending_refund/refund_requested) -> pending.

Eduzz — dois formatos, ambos suportados (desde 0.9.5, nas DUAS superficies: node
n8n e variavel sGTM conversor-plataformas-gateway.tpl):

O legado dispara com user-agent generico (node) e sem o prefixo myeduzz., entao
nao era detectado ate a 0.9.4 — toda venda aprovada saia com "Nao foi possivel
auto-detectar a plataforma". Do trans_status numerico so o 3 (paga) e mapeado:
e o unico codigo com evidencia no payload real, e status errado no banco e pior que
coluna vazia.

Action: Converter Gateway — schema canonico (saida)

ItemCompra: { nome, id, valor, quantidade, tipo }, onde tipo ∈ principal |
order_bump | upsell | downsell | desconhecido. A matriz carrega todos os
produtos do payload (inclusive bump/downsell); nome_produto/id_produto apontam
pro primeiro item principal (fallback: primeiro item, ex.: transacao 100% bump).

Classificacao do tipo, em ordem de precedencia:

1. Rotulo nativo do item quando presente e reconhecido (bump/upsell/downsell/
   main, ignorando caixa e os separadores espaco/tab/quebra de linha, _ e -;
   token exato pos-normalizacao). Rotulos genericos de catalogo (product, plan)
   NAO classificam. Nenhuma plataforma suportada documenta upsell/downsell no payload
   hoje (pesquisa 2026-07-16) — chegam como compra normal separada; o reconhecimento
   e defensivo/futuro.
2. Flag de bump da transacao — classifica todos os itens sem rotulo nativo
   reconhecido (rotulo explicito prevalece) nos mappers multi-item: Guru is_order_bump na raiz (bump = transacao separada), Eduzz
   data.orderBump.isMainSale === false (bump = fatura separada), Virtu
   products[].isOrderBump por produto (defensivo, sem doc publica). Hotmart
   (purchase.order_bump.is_order_bump) e Greenn (sale.bump_id preenchido)
   entregam 1 produto por evento — a flag classifica esse unico item.
3. Heuristica de posicao (duas etapas): o 1º item sem tipo explicito =
   principal (a menos que outro item ja seja principal por rotulo), demais =
   order_bump. Item rotulado bump/downsell na posicao 0 nao rouba o posto do
   item nao rotulado. Rotulos sao comparados por token exato pos-normalizacao
   (non-bump/upsell-disabled nao classificam).

Atribuicao por plataforma — nao ha regra "ou UTM ou codigo"; cada uma manda
o que o payload dela tem (fonte entre parenteses):

Semantica: xcod e sck sao campos SEPARADOS e independentes — na Hotmart
moram no mesmo bloco origin e qualquer um pode vir sozinho (venda de funil
costuma trazer so o sck); o xcod pode encodar varios valores separados por
_. O irmao src da Kiwify nao tem campo canonico e fica de fora.

Ausencia, camada a camada (vale pra sck e pra qualquer campo vazio):

• schema canonico (PurchaseData): a chave existe SEMPRE — emptyPurchase
  inicializa em null.
• saida do node: o null cai junto com os demais vazios (regra "chaves
  vazias omitidas", mais abaixo) — a chave nao aparece no item.
• destino: insert que hoje nao tem coluna sck segue funcionando sem
  mudanca; pra PERSISTIR o valor, o destino precisa da coluna correspondente.

Formatos de entrada: o node desembrulha o item do Webhook node
({ headers, body }) e o de fila RabbitMQ/AMQP em qualquer forma — content
com envelope ({ content: { body } }) ou body cru ({ content: <body> }), e
content/body como objeto, array ou string JSON. Fila e webhook produzem a
mesma saida. Obs: em fila com body cru no content nao ha headers HTTP — e, desde 0.9.3, o
header nao e fonte de IP nem no webhook (a menos que Usar IP Do Header seja ligado), entao
o ip vem do payload: o produtor precisa injetar ip_override no body.

Moeda: o valor permanece na moeda original da transacao; quem soma receita
downstream deve agrupar/converter por moeda. Sem alteracao de banco.

Kiwify — valores em CENTAVOS: Commissions.charge_amount: 6277 = R$ 62,77.
E a unica plataforma suportada com essa escala; o mapper divide por 100
(centavosParaReais), entao valor sai em reais como o das outras. O contrato
e ESTRITO: centavo e inteiro ou string de digitos — formato monetario
(1.234,56) e fracao de centavo (6277.5) viram null, nao valor convertido
(pelo parser generico 1.234,56 daria 12.3456, 100x menor). Campo vazio e
visivel; valor errado e silencioso. A base do valor e charge_amount (total cobrado do cliente), com
fallback product_base_price — settlement_amount/my_commission sao repasse
ao produtor e ficam de fora. A deteccao e so por body (order_id + objetos
capitalizados Customer + Product/Commissions): o user-agent da Kiwify e
axios/<versao>, generico demais pra ser assinatura. A Kiwify entrega 1
produto por evento (webhook configurado POR produto), entao o order bump vem
em evento proprio e commissioned_stores (split produtor/coprodutor/afiliado)
NAO vira item.

Valores financeiros (0.10.0, sanidade em 0.10.x)

Tres valores distintos, todos na moeda de moeda. valor nao mudou de nome nem de fonte; na sanidade
0.10.x o parser passou a ler "1,234.56" (US) como 1234.56 e numero nao finito como ausente.

Mudancas de comportamento da sanidade 0.10.x: parcela e liquido EXPLICITOS passaram a sair
arredondados a centavo (em 0.10.0 saiam como vieram). Os operandos das contas — taxas, entradas e as
explicitas lidas por Eduzz legado e TMB — passam por um parser ESTRITO: number finito ou texto so com
sinal, prefixo de moeda (R$, US$ ou $), digitos e separadores; "0abc", [1] ou true deixam o
campo derivado ausente em vez de virar 0 ou 1. Limitacao conhecida: notacao cientifica em texto
("1e2") nao e lida — em valor o parser tira a letra e le 12 (o template sGTM faz igual); nos
operandos das contas o campo derivado fica ausente.

Mudanca apos a 0.10.5 — valor_parcela e a parcela RECEBIDA: a parcela que o comprador paga
carrega os juros do parcelamento, que nao chegam ao vendedor. Guru 12x real: installments.value
120.1 (x 12 = 1441.2, com 244.19 de juros), valor 1441.19, valor_total_liquido 1197 ->
valor_parcela 1197 / 12 = 99.75 (antes 120.1). Com taxa, ela sai antes: Guru 1x de 797 com
marketplace_value 41.05 -> parcela 755.95. valor e valor_total_liquido nao mudaram.

Campo rotulado comissao (Kiwify my_commission, Eduzz pro_value, Hotmart PRODUCER) e a
fatia de UMA conta no rateio com coprodutor/afiliado — nao e o liquido da venda e nao e usado.
Contas saem arredondadas a centavo; operando ausente deixa o campo ausente (nunca NaN).

Na coluna valor_parcela, "recebida" = valor_total_liquido / parcelas (regra acima); o que vem
depois de "sem liquido" e a parcela da origem, usada quando falta o liquido ou a quantidade.

Destino com insert automatico: as duas chaves entram na saida sempre que ha dado. Node
Postgres em Map Automatically recusa chave sem coluna — antes de atualizar o pacote numa
instancia assim, crie as colunas (valor_parcela numeric, valor_total_liquido numeric) ou
mapeie as colunas explicitamente. O n8n nao atualiza community node sozinho.

Parametros da action Converter Gateway:

• Plataforma — Auto-detectar (pela estrutura do JSON) ou plataforma fixa.
  Fila com plataformas misturadas (ex: purchase_data) exige Auto-detectar —
  plataforma fixa aplica SEMPRE aquele mapper. Desde 0.8.1, payload cuja assinatura
  casa com OUTRA plataforma gera erro acionavel em vez de linha lixo silenciosa no
  banco; payload que nenhuma assinatura reconhece segue processando (o override
  manual existe pra isso).
• Itens Como JSON — serializa itens como string JSON em vez de array.
  Ligue quando o destino for uma coluna json/jsonb no node Postgres nativo:
  com array JS o driver envia text[] e o insert falha
  (column "itens" is of type jsonb but expression is of type text[]); com a
  string JSON o Postgres faz o cast automatico text -> jsonb. Dispensa o node
  Edit Fields intermediario. Desligado (default), itens segue array de objetos
  (consumo em fluxo n8n, ex: Split Out).
• Campos A Excluir — campos a remover da saida (lista = campos do schema de
  compra). Aplica depois de "Itens Como JSON". Vazio (default, e workflow antigo sem o
  parametro) = nao remove nada. Use quando a tabela destino nao tem a coluna: com o node
  Postgres em Map Automatically, toda chave da saida precisa de coluna, e desde 0.10.0 a
  saida traz valor_parcela e valor_total_liquido — sem essas colunas o upsert falha por
  coluna inexistente. Marque as duas aqui (ou crie as colunas). Parametro separado do
  "Campos A Excluir" do GTM: a selecao feita numa action nao vale na outra.
• 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_name separada por virgula. Vazio = todos
  os eventos passam (inclusive sem nome). Use para restringir aos eventos de negocio.
• Eventos Excluidos — blocklist de event_name separada por virgula. Vazio = nenhum
  excluido. Tem prioridade sobre "Eventos Permitidos" (um evento que esteja nas duas
  listas e excluido). Use quando for mais facil listar os poucos eventos a descartar
  (ex: internos do GTM gtm.dom, gtm.load, gtm.js) do que escolher todos os permitidos.
• Campos De Saida — escolha quais campos manter no output. Vazio = todos.
• Campos A Excluir — campos a remover do output. Aplica depois de "Campos De
  Saida". Vazio = nao remove nada. Use para descartar os poucos campos que a tabela destino
  nao tem (ex: event_name) sem precisar escolher manualmente todos os que ficam — evita o
  erro Column 'event_name' does not exist in selected table no insert downstream.
• Usar IP Do Header (desde 0.9.3, default desligado) — le x-real-ip/x-forwarded-for
  como ultima fonte da coluna ip, so quando nenhuma das quatro fontes do payload
  (ip_override, ip, user_data.ip_override, user_data.ip) trouxe valor. Ligue apenas se o
  n8n recebe o webhook DIRETO, sem proxy na frente. Atras de proxy (sGTM/Cloud Run, Traefik,
  Cloudflare) esses headers carregam o endereco da infraestrutura, nao o do lead: gravar isso
  contamina geo e atribuicao de todo evento com um IP unico. Desligado, sem IP no payload a
  coluna sai vazia (NULL no banco — melhor que IP errado).
• IPs/Faixas De Proxy a Ignorar (desde 0.9.2; subordinado a "Usar IP Do Header" desde
  0.9.3) — IPs ou faixas CIDR separados por virgula (35.191.0.0/16, 130.211.0.0/22). Aparece
  na UI somente com o toggle ligado, porque atua exclusivamente no caminho do header. Faixas
  listadas sao puladas na cadeia do x-forwarded-for; se nada sobrar, ip sai vazio.

  Preferir o toggle desligado a manter esta lista. Foi a tentativa de 0.9.2 de salvar o
  caminho do header, mas lista de faixa de nuvem drifta: o provedor troca de bloco e o IP de
  proxy volta a entrar em silencio. Se ha proxy na frente do n8n, o caminho duravel e deixar
  Usar IP Do Header desligado e mandar o IP do lead no payload via ip_override.
  Escopo (desde 0.9.4): SO esta lista e exclusiva do header. A checagem de endereco valido
  e o descarte de faixa privada/reservada (10.x, 127.x, 192.168.x, 169.254.x,
  100.64/10, fe80::) valem para as duas origens — header e payload. Ja o ipsProxy
  continua so no header, porque nomeia a infra de transporte, que nao tem equivalente do
  lado do payload: o mesmo 203.0.113.9 sobrevive vindo em ip_override e e descartado vindo
  em x-real-ip.
  Ate 0.9.3 o payload passava sem filtro, sob o argumento de que ip_override era uma
  declaracao EXPLICITA do produtor. O argumento caiu: o produtor e um script do GTM que
  interpola variavel e ja mandou undefined (dai o tratamento de placeholder da 0.9.2) e
  10.0.0.1. Agora um candidato invalido cede a vez ao proximo da cadeia em vez de virar
  coluna — mesmo padrao ja usado em genero. A precedencia entre candidatos validos nao
  mudou.

• Manter Payload Original — anexa o body bruto em _original.

Allowlist x blocklist (eventos) e Saida x Excluir (campos): os dois pares sao
complementares e combinaveis. Eventos: passa se (permitidos vazio OU nome ∈ permitidos)
e nome ∉ excluidos. Campos: parte de todos → mantem so os de "Campos De Saida" (se
preenchido) → remove os de "Campos A Excluir". Tudo vazio = comportamento original.

Cadeia de fontes (desde 0.9.2): topo do body → user_data →
user_data.address / url_parameters → query da page_location. O sGTM entrega o bloco
de usuario aninhado em user_data, e ate 0.9.1 o node lia so o topo do body — id, geo,
user agent, data de nascimento e o IP real eram descartados em silencio. Cada fonte nova
entra depois da que ja existia, entao nenhum payload que ja funcionava muda de resultado.
Um alias presente-porem-vazio deixou de mascarar um preenchido mais adiante na cadeia.

Placeholder do produtor vira NULL (desde 0.9.2): quando a camada de tracking nao resolve
uma variavel, o JavaScript do GTM interpola o texto undefined/null/NaN e ele chega como
valor do campo (payload real: sete colunas de UTM com a palavra "undefined"). Um campo
cujo valor INTEIRO seja um desses (em qualquer caixa) e tratado como ausente → chave omitida
→ NULL no banco, em vez de sujeira que mente no relatorio e escapa de um IS NULL.

Mapeamento principal: event_name ← event_name;
senha_atendimento ← senha_de_atendimento;
st_user_id ← st_user_id e user_id ← user_id (id de tracking vs. id do usuario no
sistema — campos distintos desde 0.6.8; fallback user_data.* desde 0.9.2);
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.*);
cidade/estado/pais ← campo homonimo em pt-BR no topo, fallback
user_data.address.city/.region/.state/.country (desde 0.9.2);
zipcode ← zipcode/cep ou user_data.address.postal_code/.zip/.zp (normalizado:
CEP brasileiro fica so com digitos, 26255-000 → 26255000; codigo estrangeiro alfanumerico
e preservado em UPPERCASE);
data_nascimento ← data_nascimento/birth ou user_data.birth/.birthdate/.db
(normalizado para ISO YYYY-MM-DD; aceita YYYYMMDD do sGTM, ISO e DD/MM/YYYY como
padrao BR; data impossivel e hash SHA-256 — o db do Meta CAPI chega hasheado — sao
descartados, nunca "corrigidos");
user_agent ← user_agent (fallback user_data.user_agent);
language ← language;
genero ← gender/genero (topo ou user_data.gender/user_data.ge — ge e o
campo do Meta Conversions API), decodificado (desde 0.6.9): as plataformas de
tracking enviam o genero hasheado em SHA-256 (lowercase+trim), entao os dois hashes
conhecidos sao revertidos pra letra canonica — sha256("f") → f, sha256("m") → m.
Tambem aceita o valor ja em claro (f/m/female/male/feminino/masculino);
desconhecido/vazio → chave omitida;
xcod ← xcod e sck ← sck (mesma hierarquia das UTMs no payload do GTM);
utm_*/ad_id/utm_id ← campo homonimo no topo, fallback url_parameters.* (desde 0.9.2);
fbc/fbp/ttp ← common_cookie._fbc/._fbp/._ttp (o common_cookie bruto nao vai pro
output — so serve de fonte; ttp e o cookie do TikTok Pixel, irmao do fbp, desde 0.9.2);
fbclid/gclid/gbraid/wbraid/ttclid/click_id ← campo direto, url_parameters ou query
da page_location. O fbclid e guardado cru: derivar fbc dele (fb.1.<ts>.<fbclid>)
produziria um valor que nao casa com o cookie que o pixel gravou no browser — pior que nao ter;
pagina_origem ← page_location.

ip — so o payload e fonte por padrao (desde 0.9.3). Ordem exata: ip_override (topo) →
ip (topo) → user_data.ip_override → user_data.ip. As duas fontes que ja existiam ficam na
frente das aninhadas, pra que um payload que ja resolvia por ip nao mude de resultado. Nenhuma
das quatro trouxe valor → ip vazio → NULL, que e melhor que um IP errado.

Desde 0.9.4 cada candidato do payload precisa ser utilizavel — endereco valido e fora de
faixa privada/reservada. Um candidato reprovado cede a vez ao proximo da cadeia (mesmo
padrao do genero), entao ip_override: "10.0.0.1" + ip: "189.4.20.7" grava 189.4.20.7,
e nao mais o endereco privado. Reprovados todos → NULL. A precedencia entre candidatos
validos e exatamente a de antes.

O header x-real-ip/x-forwarded-for e opt-in pelo parametro Usar IP Do Header
(desligado por padrao). Atras de sGTM/Cloud Run/Traefik ele carrega o IP do proxy, nao o do
usuario: ate 0.9.1 todos os eventos desse arranjo gravavam o mesmo endereco de datacenter,
contaminando geo e atribuicao; 0.9.2 tentou corrigir filtrando faixas, mas manter lista de bloco
de nuvem drifta. Com o toggle ligado, o node percorre a cadeia cliente, proxy1, proxy2 da
esquerda pra direita e usa o primeiro endereco valido que nao seja privado/reservado nem
casar as faixas de "IPs/Faixas De Proxy a Ignorar".

Mudanca de comportamento em 0.9.3 (maior que a de 0.9.2): workflow que dependia do header
para preencher ip passa a gravar NULL — a chave e omitida do output. Quem recebe o webhook
direto, sem proxy, deve ligar "Usar IP Do Header" ao atualizar; quem esta atras de
proxy deve mandar o IP do lead no payload via ip_override (e o que a camada de tracking
captura do usuario). Uma lista ipsProxy herdada de 0.9.2 fica inerte enquanto o toggle
estiver desligado — ela nao reativa o header.

O x-forwarded-for e um header controlado pelo cliente e o ip_override vem do mesmo
payload — a coluna ip e dado de atribuicao best-effort, nunca controle de seguranca.
Desde 0.9.3 isso vale ainda mais forte: com o header fora da jogada por padrao, a coluna
passa a ser 100% auto-declarada por quem POSTa o evento (o header ao menos era atribuido
pela infra). Quem alcancar a URL do Webhook node escolhe o valor — logo, autenticacao/validacao
de origem no webhook e responsabilidade da configuracao do n8n, e ip nunca deve alimentar
decisao de acesso, antifraude ou rate-limit. O crivo da 0.9.4 melhora a qualidade do dado
(lixo e faixa privada param de entrar); ele nao e controle de seguranca e nao autentica
nada — um endereco publico qualquer, forjado, continua passando por definicao.
Os campos *_entrada (primeiro toque) vem dos campos homonimos do payload
(utm_source_entrada, utm_medium_entrada, utm_campaign_entrada,
utm_content_entrada, utm_term_entrada, utm_id_entrada, ad_id_entrada),
persistidos pela camada de tracking (GTM/sGTM). Ficam vazios quando o payload
nao os envia — desde 0.6.10 nao sao mais derivados da query da page_location
(que carrega o toque ATUAL/last-click, nao o primeiro toque; derivar de la duplicava
os UTMs atuais nas colunas _entrada).

data_criacao ← timestamp (desde 0.6.7; fuso de Sao Paulo desde 0.6.11): o
timestamp do evento (epoch em segundos, ms ou microssegundos — detectado pela
magnitude; ou uma string de data ISO com fuso explicito) e convertido para ISO 8601
no fuso America/Sao_Paulo, com offset explicito (YYYY-MM-DDTHH:MM:SS.sss-03:00),
pronto para inserir numa coluna timestamp/timestamptz do Postgres. Numa coluna
timestamp (sem tz) o Postgres grava a hora local de Sao Paulo; numa timestamptz
grava o instante correto — nos dois casos o valor deixa de aparecer 3h adiantado
(antes saia em UTC). Assim o registro guarda a data do evento, nao a do insert. Se
nao houver timestamp valido, data_criacao sai vazio → a chave e omitida → o
DEFAULT da coluna no banco assume. O id continua gerado pelo banco (auto-id). O
campo timestamp cru permanece no output (use Campos A Excluir se quiser so o
data_criacao).

Colunas novas em 0.9.2 — o banco precisa acompanhar. data_nascimento, zipcode,
ttp, fbclid, click_id e language sao chaves novas no output. No modo
"Map Automatically" do node Postgres, chave sem coluna correspondente derruba o insert
inteiro. DDL pronto em docs/sql/eventos-alter-0.9.2.sql;
enquanto o ALTER TABLE nao for aplicado, liste os campos em "Campos A Excluir".

LGPD — minimizacao na origem. A partir de 0.9.2 o node persiste dado pessoal que antes se
perdia: data de nascimento, CEP, IP real e user agent, alem de geo e ids. Colete so o que tiver
finalidade e base legal — o que nao for usar deve ser cortado em "Campos A Excluir"
(descartar na origem sai mais barato que expurgar depois). A saida carrega PII em claro,
apropriada pro banco analitico do proprio cliente; nao ligue esta saida direto em Meta CAPI /
Google EC / TikTok Events / Stape sem aplicar SHA-256 nos campos de identificacao.

Saida tudo em texto + chaves vazias omitidas: todo campo sai como string
("para facilitar manipulacao") — numero/boolean viram texto, recursivamente
(incl. valor, quantidade e os campos de itens dos 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 smoke:gtm -- evento.json  # linha de evento GTM ja na forma final do output
                                  # (IPS_PROXY="35.191.0.0/16" espelha o param do node)
npm run lint
npm run build
npm run release                   # publica no npm

Instalacao (instancia unica self-hosted)

1. Settings → Community Nodes → Install
2. Digitar n8n-nodes-conversor-plataformas
3. Aceitar o aviso de risco → Install

Licenca

MIT