Skip to main content
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.

​
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

Cada valor UTM aceita até 150 caracteres.

​
Identificadores de clique

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

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

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:
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.
Um Payment Link é reutilizável. Nunca use o ID do link para identificar uma compra individual; várias Checkout Sessions podem nascer dele.
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.

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