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

# Primeira conversão

> Envie sua primeira venda à xTracky em minutos — do payload ao evento na Meta.

Com o [script instalado](/comece-aqui/instalacao), o próximo passo é reportar as vendas à xTracky. Você tem duas opções:

<CardGroup cols={2}>
  <Card title="Webhook automático" icon="bolt" href="/plataformas/configurar-webhook">
    Aponte o webhook do seu gateway pra xTracky. Sem código.
  </Card>

  <Card title="API pública" icon="code" href="/api-reference/enviar-conversao">
    Envie via `POST` sempre que uma venda for confirmada.
  </Card>
</CardGroup>

Este guia cobre a **API pública** — a rota recomendada quando você mantém o próprio backend ou quando sua plataforma de pagamento ainda não está na [lista de integrações prontas](/plataformas/lista).

## Endpoint

<Card icon="bolt">
  **POST** `https://api.xtracky.com/api/integrations/api`
</Card>

## Payload mínimo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.xtracky.com/api/integrations/api \
    -H "Content-Type: application/json" \
    -d '{
      "orderId": "ORDER_123",
      "amount": 9990,
      "status": "paid",
      "utm_source": "TT-1763007625226-yn4xita3qylwh",
      "leadName": "João Silva",
      "leadEmail": "joao@email.com",
      "leadPhone": "+5511999999999"
    }'
  ```

  ```javascript JavaScript theme={null}
  // Capturar utm_source da URL (V1) ou LeadId do cookie (V2)
  const urlParams = new URLSearchParams(window.location.search);
  const utmSource = urlParams.get('utm_source') || '';

  await fetch('https://api.xtracky.com/api/integrations/api', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      orderId: 'ORDER_123',
      amount: 9990,
      status: 'paid',
      utm_source: utmSource,
      leadName: 'João Silva',
      leadEmail: 'joao@email.com',
    }),
  });
  ```

  ```php PHP theme={null}
  <?php
  $utmSource = $_GET['utm_source'] ?? '';

  $data = [
    'orderId'    => 'ORDER_123',
    'amount'     => 9990,
    'status'     => 'paid',
    'utm_source' => $utmSource,
    'leadName'   => 'João Silva',
    'leadEmail'  => 'joao@email.com',
    'leadPhone'  => '+5511999999999',
  ];

  $ch = curl_init('https://api.xtracky.com/api/integrations/api');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_exec($ch);
  curl_close($ch);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.xtracky.com/api/integrations/api',
      json={
          'orderId': 'ORDER_123',
          'amount': 9990,
          'status': 'paid',
          'utm_source': 'TT-1763007625226-yn4xita3qylwh',
          'leadName': 'João Silva',
          'leadEmail': 'joao@email.com',
          'leadPhone': '+5511999999999',
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

## Campos essenciais

<ParamField path="orderId" type="string" required>
  Identificador único da venda no seu sistema.
</ParamField>

<ParamField path="amount" type="integer" required>
  Valor da venda **em centavos** (ex: R\$ 99,90 → `9990`).
</ParamField>

<ParamField path="status" type="string" required>
  Status atual da transação. Um de: `waiting_payment`, `paid`, `initiate_checkout`, `failed`, `refunded`. Ver [Status de Pagamento](/conceitos/status-pagamento).
</ParamField>

<ParamField path="utm_source" type="string" required>
  O `LeadId` gerado pelo script V2 (ex: `TT-1763007625226-yn4xita3qylwh`) ou o valor do parâmetro `utm_source` capturado da URL (V1).
</ParamField>

Todos os campos opcionais e detalhes de resposta estão na [referência do endpoint](/api-reference/enviar-conversao).

## E depois?

Assim que a xTracky recebe o `POST` com `status=paid`, ela:

1. Deduplica o evento (mesmo `orderId` + `utm_source` = ignorado)
2. Identifica a plataforma de origem pelo prefixo do `LeadId`
3. Dispara o evento correspondente (`Purchase`, `Add to Cart`, etc.) pra API de conversão da rede (Meta, TikTok, Kwai ou Google)
4. Atualiza o painel em tempo real

<Card title="Ver como cada status vira evento" icon="right-left" href="/conceitos/status-pagamento">
  Tabela completa de mapeamento status → evento
</Card>