> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtracky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Como funciona

> Do primeiro clique ao evento de conversão enviado pra rede — o caminho que uma venda percorre dentro da xTracky.

A xTracky é composta por três camadas independentes que trabalham em conjunto:

<CardGroup cols={3}>
  <Card title="Script no funil" icon="browser">
    Captura o clique, gera `LeadId` e reporta os passos do funil.
  </Card>

  <Card title="API de ingestão" icon="cloud-arrow-up">
    Recebe vendas via webhook (90+ gateways) ou via API pública.
  </Card>

  <Card title="Dispatcher" icon="bullseye-arrow">
    Envia eventos de conversão pra Meta, TikTok, Kwai e Google.
  </Card>
</CardGroup>

## Fluxo de uma venda

<Steps>
  <Step title="Anúncio → Landing">
    Usuário clica no anúncio no TikTok. A URL de destino tem `?ttclid=xxxxxx`. Ao carregar a landing, o script V2 lê o `ttclid` e gera um `LeadId`:\
    `TT-1763007625226-yn4xita3qylwh`

    Esse `LeadId` é persistido no cookie/localStorage. Todas as navegações posteriores dentro do funil compartilham o mesmo Lead.
  </Step>

  <Step title="Checkout iniciado">
    Quando o usuário clica em "Comprar", o script dispara um evento `initiate_checkout` (se o botão tiver `data-xtracky-checkout` ou se você chamar a API manualmente). A xTracky repassa isso pra rede correspondente como `InitiateCheckout` (Meta) / `Add to Cart` (TikTok/Kwai).
  </Step>

  <Step title="Venda gerada (aguardando)">
    Gateway retorna o PIX/boleto. Você (ou o webhook do gateway) chama a xTracky com `status=waiting_payment`. Evento `Add to Cart` é disparado.
  </Step>

  <Step title="Pagamento confirmado">
    Gateway confirma o pagamento. Novo `POST` com `status=paid` chega à xTracky. Ela:

    1. Deduplica pelo `orderId` + `utm_source`
    2. Identifica a plataforma pelo prefixo `TT-`
    3. Dispara `Purchase` na API de conversão do TikTok
    4. Atualiza o painel em tempo real
  </Step>
</Steps>

## Ingestão: webhook automático vs API

<Tabs>
  <Tab title="Webhook automático">
    Se o seu gateway está na [lista de plataformas integradas](/plataformas/lista), você **não precisa escrever código**. Basta apontar o webhook do gateway pra:

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

    A xTracky normaliza o payload da plataforma pra um formato canônico (currency, status, amount, UTM, lead) e dispara os eventos de conversão automaticamente.
  </Tab>

  <Tab title="API pública">
    Se você tem checkout próprio, backend customizado ou usa um gateway sem integração pronta, envie via `POST /api/integrations/api`. Você controla o payload e decide quando disparar.

    Ver [Enviar Conversão](/api-reference/enviar-conversao).
  </Tab>
</Tabs>

## Componentes que você não precisa saber (mas que rodam por baixo)

* **Ingestion** — recebe webhooks e valida
* **Normalizer** — aplica transformer DB-driven por gateway
* **Enricher** — enriquece com tenant/produto/pixels ativos
* **Router** — 1 evento → N mensagens (uma por pixel configurado)
* **Dispatcher** — plugin por rede: Facebook v19, TikTok v1.3, Kwai adsnebula, Google Ads

Você configura os pixels no painel (`Produto → Integrações`) e a xTracky faz o fan-out.