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

# Introdução à API

> Formato das requisições, autenticação, códigos de status e boas práticas.

A API da xTracky é REST + JSON. Existem dois endpoints públicos principais:

<CardGroup cols={2}>
  <Card title="POST /api/integrations/api" href="/api-reference/enviar-conversao" icon="paper-plane">
    Envio manual de conversão — para checkouts próprios ou gateways sem integração pronta.
  </Card>

  <Card title="POST /api/integrations/{plataforma}" href="/api-reference/webhooks-plataforma" icon="webhook">
    Webhook automático — 90+ gateways integrados sem código.
  </Card>
</CardGroup>

## URL base

```
https://api.xtracky.com/api/integrations/
```

## Autenticação

A xTracky autentica requisições pelo **`data-token`** (Product ID / UUID) que você inclui no payload como `utm_source` (indiretamente) e/ou como parte do webhook do gateway.

Não existe API key global neste momento — cada produto tem seu próprio ID e a atribuição é feita implicitamente via `LeadId`. Se você precisa de API key headerizada pra CI/backend, isso está no roadmap; fale com [suporte@xtracky.com](mailto:suporte@xtracky.com).

## Formato

Todas as requisições usam:

```http theme={null}
Content-Type: application/json
```

O corpo é JSON. Não há paginação nem cursor — a API é write-only nos endpoints de integração (a leitura acontece no painel).

## Códigos de status HTTP

| Código | Significado                                                            |
| ------ | ---------------------------------------------------------------------- |
| `200`  | Sucesso — evento aceito (mesmo que dedupado)                           |
| `201`  | Sucesso — evento criado pela primeira vez                              |
| `202`  | Aceito assincronamente — vai processar em fila                         |
| `400`  | Corpo inválido (campo obrigatório faltando, status desconhecido, etc.) |
| `401`  | Product ID / token não encontrado ou inativo                           |
| `409`  | Duplicata detectada (`orderId` + `utm_source` já processado)           |
| `429`  | Rate limit — reduza a frequência                                       |
| `5xx`  | Erro interno — retry recomendado com backoff exponencial               |

## Rate limits

* **Por Product ID:** 300 req/min sustentado, burst de 100 req/s
* **Por IP de origem:** 1000 req/min

Se você previa disparar mais que isso (integração em massa, replay de backup), abra ticket antes.

## Boas práticas

<CardGroup cols={2}>
  <Card title="Reutilize orderId" icon="fingerprint">
    Sempre o mesmo `orderId` pra mesma venda (do `waiting_payment` até o `paid`).
  </Card>

  <Card title="Retry com backoff" icon="rotate">
    Em `5xx`/`429`, retry com backoff (2s, 4s, 8s). A dedup evita duplicata.
  </Card>

  <Card title="Amount em centavos" icon="brazilian-real-sign">
    R\$ 99,90 → `9990`. Sempre inteiro, nunca float.
  </Card>

  <Card title="Não bloqueie o cliente" icon="rocket">
    Se o `POST` demorar, não segure a UX — dispare async.
  </Card>
</CardGroup>