> ## 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.

# Consultar parâmetros de rastreamento

> Use UTMs, identificadores de clique, client_reference_id e metadata no campo certo para medir campanhas e conciliar pedidos.

UTMs, `client_reference_id` e `metadata` podem estar na mesma compra, mas cada
um resolve uma necessidade diferente. Use os campos de campanha para medir a
origem da venda, a referência para localizar o pedido no seu sistema e
`metadata` apenas para contexto livre que precisa voltar nos webhooks.

| Dado                       | Quando usar                                                      | Alimenta aquisição |
| -------------------------- | ---------------------------------------------------------------- | ------------------ |
| UTMs e identificadores     | Identificar campanha, canal, criativo e clique                   | Sim                |
| `client_reference_id`      | Relacionar a Checkout Session a um pedido ou carrinho            | Não                |
| `metadata` da sessão       | Devolver contexto livre do seu backend                           | Não                |
| `metadata` do Payment Link | Copiar um contexto comum da oferta para as sessões que ela criar | Não                |

## Parâmetros de campanha

A Chargefy aceita parâmetros de campanha conhecidos e ignora o restante. Isso
evita copiar a query string inteira para a sessão e reduz o risco de armazenar
dados que não pertencem à atribuição.

## UTMs

| Parâmetro na URL       | Campo público em `marketing_attribution.utm` | Uso comum                                        |
| ---------------------- | -------------------------------------------- | ------------------------------------------------ |
| `utm_id`               | `id`                                         | Identificador da campanha na ferramenta de mídia |
| `utm_source`           | `source`                                     | Origem do tráfego                                |
| `utm_medium`           | `medium`                                     | Tipo de canal ou distribuição                    |
| `utm_campaign`         | `campaign`                                   | Nome da campanha                                 |
| `utm_term`             | `term`                                       | Palavra-chave ou audiência                       |
| `utm_content`          | `content`                                    | Criativo, variação ou posicionamento             |
| `utm_source_platform`  | `source_platform`                            | Plataforma de origem detalhada                   |
| `utm_creative_format`  | `creative_format`                            | Formato do anúncio                               |
| `utm_marketing_tactic` | `marketing_tactic`                           | Tática, como prospecção ou remarketing           |

Cada valor UTM aceita até 150 caracteres.

## Identificadores de clique

| Parâmetro | Origem usual                                               |
| --------- | ---------------------------------------------------------- |
| `fbclid`  | Clique de anúncio da Meta                                  |
| `gclid`   | Clique de anúncio de busca ou display                      |
| `gbraid`  | Campanha de app ou ambiente com restrição de identificação |
| `wbraid`  | Campanha web em ambiente com restrição de identificação    |
| `ttclid`  | Clique de anúncio do TikTok                                |
| `msclkid` | Clique de anúncio da Microsoft                             |

Cada identificador aceita até 500 caracteres. Normalmente a própria plataforma
de mídia acrescenta esse valor no clique. Preserve-o; não fabrique um ID.

## Identificadores de navegador da Meta

| Campo | O que representa                             |
| ----- | -------------------------------------------- |
| `fbc` | Relação do navegador com o clique de anúncio |
| `fbp` | Identificador do navegador criado pelo Pixel |

Esses valores podem chegar pela URL, pelo objeto `marketing_attribution.meta`
ou pelo navegador durante o checkout. Quando existe `fbclid` e ainda não existe
`fbc`, a Chargefy pode compor o formato esperado a partir do clique e do horário
de captura.

## Landing page, referrer e correlação

| Campo na API ou no SDK | Limite           | Tratamento                                   |
| ---------------------- | ---------------- | -------------------------------------------- |
| `landing_page_url`     | 2.048 caracteres | Aceita apenas HTTP(S) e guarda origem + path |
| `referrer_url`         | 2.048 caracteres | Aceita apenas HTTP(S) e guarda origem + path |

Query string e fragmento são removidos das URLs de contexto. Se o path contiver
um segredo de checkout, ele é ocultado antes do armazenamento.

## Referência do pedido e metadata

Use `client_reference_id` para relacionar a sessão a um carrinho, pedido,
orçamento ou usuário no seu sistema. Em um Payment Link, acrescente a referência
na URL distribuída para aquela pessoa:

```text theme={"theme":"css-variables"}
https://pay.chargefy.io/link/seu_link?client_reference_id=pedido-8472
```

Em uma Checkout Session criada pela API, envie o campo no body. Ele volta nos
webhooks da sessão e facilita a conciliação sem transformar o Payment Link em
um identificador de pedido.

<Warning>
  Um Payment Link é reutilizável. Nunca use o ID do link para identificar uma
  compra individual; várias Checkout Sessions podem nascer dele.
</Warning>

`metadata` é um objeto livre controlado pelo seu sistema. A Chargefy armazena e
ecoa os pares enviados, mas não interpreta chaves específicas para decidir
atribuição, desconto, customer ou comportamento do checkout. Use-o para dados
operacionais como uma versão de oferta, uma chave de integração ou contexto que
apenas o seu backend precisa ler.

Quando um clique cria uma Checkout Session, o `metadata` atual do Payment Link
é copiado para a nova sessão. Alterações posteriores no link valem apenas para
sessões futuras. Para um contexto único do comprador, use
`client_reference_id` ou crie a sessão pelo backend.

| Não faça                                     | Por quê                                                  | Use no lugar                    |
| -------------------------------------------- | -------------------------------------------------------- | ------------------------------- |
| Guardar `utm_campaign` em `metadata`         | O relatório de aquisição não lê metadata                 | UTMs ou `marketing_attribution` |
| Criar um Payment Link por comprador          | Mistura uma oferta reutilizável com um pedido individual | `client_reference_id` na URL    |
| Colocar CPF ou e-mail em UTM                 | Expõe dado pessoal na URL                                | Campos do checkout              |
| Usar `client_reference_id` como campanha     | Concilia o pedido, mas não agrupa a aquisição            | `utm_campaign`                  |
| Esperar que metadata mude regras da Chargefy | Metadata é opaca                                         | Campo tipado correspondente     |

## Regras da captura por URL

* o nome do parâmetro é comparado sem diferenciar maiúsculas de minúsculas;
* se a mesma chave aparecer mais de uma vez, o primeiro valor vence;
* espaços nas extremidades são removidos;
* valor vazio, acima do limite ou com caractere de controle é ignorado;
* URL de contexto inválida é ignorada;
* parâmetro desconhecido não é armazenado;
* um problema de atribuição nunca impede o comprador de abrir o checkout.

Exemplo: `UTM_SOURCE=meta&utm_source=email` resulta em `meta`, porque a primeira
ocorrência válida vence.

## Regras do objeto enviado pela API

O objeto `marketing_attribution` é estrito. A Chargefy retorna `400` quando:

* o objeto ou um grupo interno tem tipo incorreto;
* existe um campo desconhecido;
* um texto está vazio ou acima do limite;
* landing page ou referrer não é uma URL HTTP(S) absoluta.

Essa diferença é intencional. A URL pública precisa continuar abrindo mesmo com
uma campanha malformada. O backend, por outro lado, deve receber um erro claro e
corrigir o payload antes do redirect.

## Campos internos

IP, país, idioma do navegador e user agent podem ser registrados para segurança
e qualidade de correspondência. Eles não fazem parte do objeto público
`marketing_attribution` retornado pela API.

<Warning>
  Não use parâmetros internos com prefixo `cfy_`. Eles pertencem ao runtime da
  Chargefy e podem mudar sem fazer parte do contrato de campanha.
</Warning>