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

# Enviar atribuição pela API

> Crie uma Checkout Session já vinculada à campanha quando seu backend conhece a origem da compra.

Use este caminho quando seu backend cria a Checkout Session diretamente pela
API, sem enviar o comprador para um Payment Link. No momento da criação, envie
o objeto `marketing_attribution` para registrar a origem da campanha desde o
início e recebê-la no primeiro webhook.

```json theme={"theme":"css-variables"}
{
  "line_items": [
    {
      "price_id": "price_QW2nSe8M5UjR3xKP"
    }
  ],
  "marketing_attribution": {
    "click_ids": {
      "fbclid": "IwAR3G7kQ9mN2pT5vX8zR4wY7cA1sD6eF9hJ2kL5mP8q"
    },
    "landing_page_url": "https://meusite.com/oferta",
    "utm": {
      "campaign": "lancamento",
      "content": "video_a",
      "medium": "paid_social",
      "source": "meta"
    }
  },
  "metadata": {}
}
```

Você não envia `model`, `capture_point`, `captured_at`, IP, país ou user agent.
Esses campos pertencem à Chargefy e são preenchidos conforme a origem da
captura.

## Quando usar este caminho

Use `marketing_attribution` quando:

* seu sistema já recebeu as UTMs antes de criar o pedido;
* a Checkout Session é criada antes do redirect do comprador;
* você quer que `checkout.session.created` já carregue a atribuição;
* o checkout começa dentro de um app, SaaS, carrinho ou fluxo autenticado;
* a campanha foi resolvida server-side e não depende da URL hospedada.

## O que acontece se você não enviar

A sessão nasce com `marketing_attribution: null`. Na primeira abertura da URL
hospedada, a Chargefy ainda pode registrar os parâmetros presentes na URL.

Isso cria uma diferença importante nos webhooks:

| Momento                    | Sem atribuição no create                        | Com atribuição no create           |
| -------------------------- | ----------------------------------------------- | ---------------------------------- |
| `checkout.session.created` | Pode carregar `marketing_attribution: null`     | Já carrega o snapshot da campanha  |
| Primeira abertura          | Pode registrar a atribuição recebida pela URL   | Não substitui o snapshot existente |
| Eventos posteriores        | Carregam a atribuição que tiver sido registrada | Mantêm a atribuição do create      |

Se outro sistema precisa tomar decisão de campanha já no evento de criação,
envie o objeto no backend.

## Validação

O body da API é estrito. Campo desconhecido, tipo incorreto, URL inválida ou
valor acima do limite retorna `400` e aponta o parâmetro com problema.

| Grupo                               | Limite por valor                              |
| ----------------------------------- | --------------------------------------------- |
| `utm.*`                             | 150 caracteres                                |
| `click_ids.*` e `meta.*`            | 500 caracteres                                |
| `landing_page_url` e `referrer_url` | URL HTTP(S) absoluta com até 2.048 caracteres |

Na captura pela URL, valores inválidos são ignorados para não impedir o checkout.
Na API, o erro é explícito porque seu backend pode corrigi-lo antes de enviar o
comprador.

## Atribuição não é metadata

`marketing_attribution` alimenta relatórios e integrações de marketing.
`metadata` guarda pares livres controlados pelo seu sistema e é apenas ecoado
nos objetos e webhooks.

Não coloque `utm_source`, `utm_campaign` ou `fbclid` dentro de `metadata` se
espera vê-los no relatório de aquisição.

## Referência completa

Veja todos os campos, variantes de `line_items`, respostas e erros em [Criar
uma Checkout Session](/api-reference/checkout-sessions/create).