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

# Entender a atribuição first-touch

> Saiba qual origem vence quando a Checkout Session pode receber campanha no create, no Payment Link ou na abertura direta.

Cada Checkout Session guarda **um único snapshot de aquisição**. O modelo é
`first_touch`: o primeiro ponto que registra a sessão vence, e uma abertura
posterior não reescreve sua origem.

Essa regra impede que reloads, compartilhamentos e novos redirects troquem a
campanha depois que a tentativa de compra começou.

## Pontos de captura

| `capture_point`           | Quando acontece                                               | Exemplo                                                     |
| ------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
| `checkout_session_create` | Seu backend envia `marketing_attribution` ao criar a sessão.  | Carrinho ou pedido criado pela API.                         |
| `payment_link_redirect`   | O comprador abre um Payment Link.                             | Anúncio aponta direto para uma oferta reutilizável.         |
| `checkout_session_open`   | Uma sessão criada sem atribuição é aberta pela URL hospedada. | Backend cria a sessão e acrescenta UTMs apenas no redirect. |

O primeiro registro é protegido contra concorrência. Se duas requests tentarem
capturar a mesma sessão quase ao mesmo tempo, apenas uma ocupa o snapshot.

## Exemplos práticos

### Payment Link com UTMs

O clique no link cria a sessão e registra `payment_link_redirect`. Quando a
página hospedada abre segundos depois, `checkout_session_open` não substitui a
campanha.

### Sessão criada com atribuição no backend

O create registra `checkout_session_create`. Mesmo que a URL aberta depois
contenha outra `utm_source`, o snapshot enviado pelo backend continua valendo.

### Sessão criada sem atribuição

A primeira abertura registra `checkout_session_open`. Se essa URL não tiver
UTMs ou identificadores de clique, a origem pública pode ser `direct`. Uma nova
abertura com campanha não reclassifica a sessão.

<Warning>
  Não crie a sessão cedo demais e só depois tente decidir a campanha. Quando seu
  backend conhece a origem, envie `marketing_attribution` no create. Quando não
  conhece, preserve os parâmetros na primeira URL que o comprador abrir.
</Warning>

## Como a origem pública é calculada

O campo `source` segue esta ordem:

1. `utm_source`, normalizada em minúsculas;
2. `meta`, quando existem `fbclid`, `fbc` ou `fbp`;
3. `google`, quando existem `gclid`, `gbraid` ou `wbraid`;
4. `tiktok`, quando existe `ttclid`;
5. `microsoft`, quando existe `msclkid`;
6. `direct`, quando nenhum sinal anterior existe.

As UTMs originais continuam disponíveis dentro de `marketing_attribution.utm`.
O campo `source` é uma classificação pronta para leitura e agrupamento.

## O que permanece imutável

Depois da captura, a sessão mantém:

* o ponto e o horário da captura;
* UTMs e identificadores de clique;
* `fbc` e `fbp`, quando disponíveis;
* landing page e referrer sanitizados;
* a origem calculada.

O resultado financeiro pode mudar de `unpaid` para `paid`, inclusive dias
depois em Pix e boleto. A aquisição não muda com ele: o pagamento continua
atribuído ao primeiro contexto daquela sessão.

## First-touch da landing page e da sessão

Chargefy.js também preserva um primeiro contexto no seu domínio. Esse snapshot
serve para montar a URL do checkout. Ao chegar à Chargefy, a Checkout Session
cria seu próprio registro imutável.

São duas proteções em sequência:

```text theme={"theme":"css-variables"}
Primeiro contexto salvo no seu site → primeira captura da Checkout Session
```

Um parâmetro escrito diretamente na URL de destino pode vencer uma chave salva
pelo SDK, mas nunca substitui uma sessão que já tenha sido capturada.