Documentação

Integração, rastreamento e configuração

Webhook universal

Parte 1

Visão geral — como a venda chega

O GhostScale recebe vendas em 3 peças que trabalham juntas. O gateway só precisa implementar a peça 2; as demais já funcionam sozinhas:

Peça	O que faz	Quem instala
1 · Script do navegador	Salva UTMs e cliques por 90 dias, registra PageView, ViewContent e InitiateCheckout, e leva a atribuição até o checkout.	Dono da página de vendas (1 linha de código)
2 · Webhook do gateway	Avisa cada venda: aprovada, pendente, reembolsada, chargeback ou cancelada. É a fonte oficial da venda.	Você (dono do gateway) — esta documentação
3 · Conversions API	O GhostScale repassa a venda aprovada para a Meta com o mesmo identificador (sem duplicar).	Automático, sem código extra

Regra de ouro: compra aprovada só entra pelo webhook do gateway. O endpoint de eventos do navegador recusa Purchase de propósito, para o número oficial sempre bater com o dinheiro real.

Parte 2

Script na página de vendas

Cole antes do fechamento do </head> da página de vendas e do checkout. Troque SUA_PUBLIC_KEY pela chave do projeto (aba UTMs → Script de vendas):

<script async src="https://track-base-analytics.vercel.app/tracker.js?key=SUA_PUBLIC_KEY"></script>

O que ele faz sozinho: guarda utm_source, utm_medium, utm_campaign, utm_content, utm_term, fbclid por 90 dias, envia PageView e ViewContent, repassa os parâmetros nos links/botões até o checkout e dispara o Pixel da Meta se houver um conectado.

Botão de checkout (opcional, marca o início da compra):

<a href="/checkout" data-trackbase-event="InitiateCheckout" data-value="69.90" data-currency="BRL">Comprar agora</a>

Página de obrigado (opcional, reforça a atribuição — o webhook continua sendo obrigatório):

<script>TrackBase.purchase({value:69.90,currency:"BRL",externalId:"PEDIDO_ID"})</script>

Parte 3

Webhook de vendas

Envie um POST com JSON para:

POST https://track-base-analytics.vercel.app/api/webhooks/gateway

Autenticação — use UMA das 3 formas (o token é gerado na aba Gateways do SaaS, um por gateway):

Authorization: Bearer SEU_TOKEN
// ou
x-trackbase-key: SEU_TOKEN
// ou
POST https://track-base-analytics.vercel.app/api/webhooks/gateway?token=SEU_TOKEN

Exemplo mínimo (venda aprovada):

{
  "id": "PEDIDO_123",
  "status": "paid",
  "amount": 69.90,
  "currency": "BRL"
}

Exemplo completo (com atribuição e dados para a CAPI):

{
  "id": "PEDIDO_123",
  "status": "paid",
  "amount": 69.90,
  "currency": "BRL",
  "paid_at": "2026-09-08T12:00:00-03:00",
  "email": "cliente@email.com",
  "phone": "5511999999999",
  "fbclid": "ABC123...",
  "fbp": "fb.1.123...",
  "fbc": "fb.1.123...ABC123",
  "tb_vid": "visitante-xyz",
  "utm_source": "facebook",
  "utm_campaign": "CAMPANHA|123",
  "event_id": "meu-id-unico-123"
}

Dica: o script da página já anexa fbclid, fbp, fbc, tb_vid e UTMs nos formulários e links do checkout — basta o gateway repassar esses campos no webhook.

Parte 4

Campos aceitos

O GhostScale procura cada informação em vários nomes comuns. Basta enviar UM deles por linha:

Informação	Nomes aceitos
ID da venda	transaction_hash, transactionHash, reference, reference_id, order_number, id, transaction_id, transactionId, sale_id, saleId, data.id, data.transaction.id, order.id
Status	status, payment_status, transaction_status, event, type, data.status, data.payment_status, data.transaction.status, order.status
Valor em centavos	amount_cents, amountCents, total_cents, data.amount_cents, data.transaction.amount_cents, order.total_cents
Valor decimal	value, amount, total, price, data.value, data.amount, data.transaction.amount, order.total
Moeda	currency, data.currency, data.transaction.currency (padrão BRL)
ID do evento	event_id, eventId, tracking.event_id, metadata.event_id, data.event_id
Data do pagamento	paid_at, data.paid_at
E-mail do cliente	email, customer.email, data.customer.email, buyer.email
Telefone	phone, customer.phone, data.customer.phone, buyer.phone
Facebook (CAPI)	fbc, fbp, fbclid (também em tracking., metadata., data.tracking.*)
Visitante	tb_vid (também em tracking., metadata., data.tracking.*)
UTMs	utm_source, utm_medium, utm_campaign, utm_content, utm_term (também em tracking., metadata., data.tracking.*)

Parte 5

Status — o que cada valor vira

Você envia (exemplos)	Vira no painel	Evento gerado
approved, authorized, paid, completed, succeeded, settled, captured, aprovado, pago, liquidado	Aprovada	Purchase
pending, waiting, processing, created, initiated, in_review, awaiting, aguardando, criado	Pendente	PaymentPending
refund, reembols*	Reembolsada	Refund
chargeback, contestad*	Chargeback	Chargeback
cancel, failed, recusad*, expired	Cancelada	PaymentCancelled

Valores fora dessa lista retornam HTTP 400 com {"error": "Status de pagamento não reconhecido"} e nada é salvo. Reenviar o mesmo ID atualiza a venda (mudança de pendente → aprovada funciona sozinha).

Parte 6

Caso especial: FortPay

A FortPay envia o pedido aninhado: ID em transaction.id, valor em transaction.amount em centavos (777 = R$ 7,77), produto em items[0].title e UTMs em tracking.*:

{
  "event": "transaction",
  "status": "waiting_payment",
  "platform": "FortPay",
  "method": "pix",
  "customer": {"name": "...", "email": "...", "phone": "..."},
  "transaction": {"id": "abc123", "amount": 777},
  "items": [{"title": "NOME DO PRODUTO", "price": "777"}],
  "tracking": {"utm_source": "...", "utm_campaign": "NOME|ID"}
}

O GhostScale usa transaction.id para atualizar a venda (pendente → aprovada) sem duplicar, converte centavos sozinho e mostra só o nome da campanha (antes do |). Sem UTMs, a campanha fica vazia.

Parte 7

Valores e moeda

Se enviar valor em centavos (amount_cents: 6990), o GhostScale divide por 100. Se enviar decimal (amount: 69.90), usa direto. Valores negativos ou inválidos retornam HTTP 400. Moeda padrão: BRL.

Parte 8

Deduplicação (evitar venda dobrada)

Cada venda tem um event_id: se você não enviar, o GhostScale gera purchase_ID-DA-VENDA para aprovadas. O mesmo event_id é usado no navegador (Pixel) e no servidor (CAPI), então a Meta conta uma vez só. Reenvios com o mesmo ID da venda apenas atualizam o registro.

Parte 9

Respostas e erros

Código	Quando	Corpo
200	Venda registrada/atualizada	{"{"}"received": true, "orderId": "...", "status": "approved", "event": "Purchase"{"}"}
400	JSON inválido, status desconhecido ou valor inválido	{"{"}"error": "motivo"{"}"}
401	Sem token ou token inválido/revogado	{"{"}"error": "Credencial inválida"{"}"}

Qualquer origem pode chamar (CORS liberado). Em caso de instabilidade, reenvie: o processamento é idempotente pelo ID da venda.

Parte 10

Testando a integração

1. Crie a credencial na aba Gateways e copie o token. 2. Envie uma venda de teste com status pendente e depois aprovada usando o mesmo ID. 3. Confira em Vendas (painel) e na lista de credenciais (coluna de último uso). 4. Para apagar o teste, exclua o projeto de teste na aba UTMs — eventos, vendas e credenciais dele são removidos juntos.

Parte 11

Segurança

Um token por gateway (nunca reutilize entre plataformas). O token aparece uma única vez na criação — guarde em segredo. Para revogar, apague a credencial na aba Gateways: o webhook passa a responder 401 na hora. E-mail e telefone são gravados com hash SHA-256 antes de ir à Meta.

Parte 12

Perguntas frequentes

Preciso enviar todos os campos? Não — só ID, status e valor. O resto melhora atribuição e CAPI.
E se meu gateway usa outros nomes? A tabela da parte 4 cobre os mais comuns, incluindo objetos aninhados (data.*). Faltou algum? Fale com a equipe GhostScale que adicionamos.
O Purchase do navegador basta? Não — a venda oficial sempre vem do webhook. O navegador é apoio de atribuição.
Quem cria o Pixel da Meta? O dono da operação, dentro do SaaS (aba Pixel & CAPI) — não é tarefa do gateway.

Carregando seu workspace…

→Voltar ao dashboard