Documentação de Integração

1

Instalação do Script de Rastreamento

Insira o script em todas as páginas do seu funil, logo após a tag <head>. O script detecta automaticamente a plataforma de anúncios (Kwai, TikTok, Facebook, Google) pelo parâmetro de click na URL.

<script
    src="https://cdn.xtracky.com/scripts/experimental.js"
    data-token="SEU_PRODUCT_ID"
    data-step-id="checkout"
    async>
</script>

V2 - Sistema de Leads Detecção automática de plataforma, tracking multi-step, suporte a SPA e deduplicação inteligente. Gera um LeadId único por visitante (ex: TT-1763007625226-yn4xita3qylwh).

<script
    src="https://cdn.xtracky.com/scripts/utm-handler.js"
    data-token="SEU_PRODUCT_ID"
    data-click-id-param="click_id">
</script>

<script
    src="https://cdn.jsdelivr.net/gh/xTracky/static/utm-handler.js"
    data-token="SEU_PRODUCT_ID"
    data-click-id-param="click_id">
</script>

CDN Alternativo Use esta opção se a URL principal estiver sendo bloqueada por ferramentas de URL scan.

Atributos do Script

data-token* ID do seu produto na XTracky (UUID). Encontrado no painel em Produtos.

data-step-id Identificador da etapa do funil (ex: checkout, upsell). Usado no V2 para tracking multi-step.

data-click-id-param Nome do parâmetro de click ID na URL (padrão: click_id). Usado no V1.

Detecção Automática de Plataforma (V2)

Parâmetro na URL	Plataforma	Prefixo do Lead
`click_id`	Kwai	KW-
`ttclid`	TikTok	TT-
`fbclid`	Facebook / Meta	FB-
`gclid`	Google Ads	GG-

2

Envio de Conversões via API

Envie os dados de venda para a XTracky sempre que uma transação ocorrer. Se você usa uma plataforma de pagamento integrada, os webhooks são processados automaticamente (ver plataformas).

POST https://api.xtracky.com/api/integrations/api

Corpo da Requisição (JSON)

{
  "orderId": "ORDER_123",
  "amount": 9990,
  "status": "paid",
  "platform": "CUSTOM",
  "utm_source": "TT-1763007625226-yn4xita3qylwh",
  "leadName": "João Silva",
  "leadEmail": "[email protected]",
  "leadPhone": "+5511999999999",
  "leadDocument": "123.456.789-00"
}

Parâmetros

orderId* Identificador único da venda/pedido.

amount* Valor da venda em centavos (ex: R$ 99,90 = 9990).

status* Status do pagamento. Valores aceitos: waiting_payment, paid, initiate_checkout, failed, refunded. Ver detalhes.

utm_source* O LeadId gerado pelo script (V2, ex: TT-1763007625226-yn4xita3qylwh) ou o valor do parâmetro utm_source capturado da URL (V1).

platform Nome da plataforma de origem (ex: CUSTOM, VEGA). Detectado automaticamente no V2.

leadName Nome completo do comprador.

leadEmail E-mail do comprador.

leadPhone Telefone do comprador.

leadDocument CPF/CNPJ do comprador.

Proteção contra Duplicatas Requisições com o mesmo orderId + utm_source são processadas apenas uma vez. Eventos duplicados são ignorados automaticamente.

3

Exemplos de Implementação

Copie e adapte o exemplo na linguagem do seu backend.

// Capturar utm_source da URL (V1) ou leadId do cookie (V2)
const urlParams = new URLSearchParams(window.location.search);
const utmSource = urlParams.get('utm_source') || '';

// Enviar conversão
fetch('https://api.xtracky.com/api/integrations/api', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    orderId: 'ORDER_123',
    amount: 9990,
    status: 'paid',
    utm_source: utmSource,
    leadName: 'João Silva',
    leadEmail: '[email protected]'
  })
})
.then(res => res.json())
.then(data => console.log('Conversão enviada:', data))
.catch(err => console.error('Erro:', err));

curl -X POST https://api.xtracky.com/api/integrations/api \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORDER_123",
    "amount": 9990,
    "status": "paid",
    "utm_source": "TT-1763007625226-yn4xita3qylwh",
    "leadName": "João Silva",
    "leadEmail": "[email protected]",
    "leadPhone": "+5511999999999"
  }'

<?php
// Capturar utm_source da URL
$utmSource = isset($_GET['utm_source']) ? $_GET['utm_source'] : '';

// Dados da conversão
$data = [
    'orderId'    => 'ORDER_123',
    'amount'     => 9990,
    'status'     => 'paid',
    'utm_source' => $utmSource,
    'leadName'   => 'João Silva',
    'leadEmail'  => '[email protected]',
    'leadPhone'  => '+5511999999999',
];

// Enviar requisição
$ch = curl_init('https://api.xtracky.com/api/integrations/api');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    echo 'Conversão enviada com sucesso';
} else {
    echo 'Erro ao enviar: ' . $response;
}
?>

import requests

# Dados da conversão
payload = {
    "orderId": "ORDER_123",
    "amount": 9990,
    "status": "paid",
    "utm_source": "TT-1763007625226-yn4xita3qylwh",
    "leadName": "João Silva",
    "leadEmail": "[email protected]",
    "leadPhone": "+5511999999999",
}

response = requests.post(
    "https://api.xtracky.com/api/integrations/api",
    json=payload,
)

if response.status_code == 200:
    print("Conversão enviada:", response.json())
else:
    print("Erro:", response.status_code, response.text)

Referência

Status de Pagamento

Utilize os status abaixo para indicar o estado atual da transação. Cada status dispara eventos diferentes nas plataformas de anúncios.

Status	Descrição	Evento Disparado
waiting_payment	Venda gerada, aguardando pagamento (PIX, boleto)	Add to Cart
paid	Pagamento confirmado	Purchase
initiate_checkout	Usuário iniciou o checkout (preencheu dados)	Initiate Checkout
failed	Pagamento falhou ou foi recusado	-
refunded	Venda reembolsada	-

Mapeamento de Eventos Os eventos são automaticamente enviados para Kwai, TikTok, Facebook e Google conforme a plataforma detectada pelo script de rastreamento.

Plataformas de Pagamento Integradas

A XTracky processa webhooks automaticamente de 90+ plataformas de pagamento. Se sua plataforma está na lista abaixo, basta configurar o webhook no painel da sua plataforma apontando para:

POST https://api.xtracky.com/api/integrations/{plataforma}

Substitua {plataforma} pelo nome da sua plataforma em minúsculo (ex: /api/integrations/vega).

Vega

Diamond

Tribopay

Mangofy

Braip

Sunize

Vycon

Paradise

BlackPay

Cakto

LastLink

NinjaPay

Adoorei

EExclusive

NivoPay

AllowPayments

Kirvano

Urus

Wegate

CinqPay

AgillePay

NitroPag

RisePay

WolfPayment

FortPay

VittaPay

Frendz

Pantherfy

Hebreus

FluxionPay

InovaPag

MundPay

Disrupty

Cloudfy

PerfectPay

ZeroOne

BullsPay

RushPay

PaySpectra

RoiPay

Payt

PagFly

DarkCoder

StrikeCash

Monetizze

Doppus

Checkoutinho

OrbitaPay

BlackoutPayments

Duckfy

PixDoMilhao

BelliPay

Não encontrou sua plataforma? Use a integração genérica via API (Passo 2) para enviar as conversões manualmente.

Recursos Avançados

Tracking de Initiate Checkout (V2)

Adicione o atributo data-xtracky-checkout ao botão de checkout para rastrear automaticamente o início do checkout sem código adicional.

<button data-xtracky-checkout>
  Finalizar Compra
</button>

Suporte a SPA (Single Page Applications)

O script V2 intercepta automaticamente navegações via Navigation API e History API, garantindo tracking correto em SPAs sem configuração adicional.

Deduplicação

Todas as requisições são verificadas contra duplicatas. No V2, a deduplicação usa a combinação de LeadId + orderId. No V1, um hash SHA-256 do payload é gerado para prevenir processamento duplicado.

Scripts Especializados

Script	URL	Uso
Padrão (V1)	`cdn.xtracky.com/scripts/utm-handler.js`	Tracking UTM clássico
Lead System (V2)	`cdn.xtracky.com/scripts/experimental.js`	Multi-plataforma com leads
Shopify	`cdn.xtracky.com/scripts/utm-handler-shopify.js`	Integração com Shopify
WhatsApp	`cdn.xtracky.com/scripts/whatsapp.js`	Tracking de WhatsApp

Pronto para integrar?

Após instalar o script e configurar o envio de conversões, acompanhe tudo em tempo real no seu painel XTracky.