# API: links de rastreamento, domínios, pixels e estatísticas

_API · Leitura de 9 min · Atualizado 2026-10-22 · https://lanachat.ai/guides/pt/api-tracking/_

Um **link de rastreamento** envia um visitante para uma criadora no Telegram e conta o que acontece depois: cliques, conversas, primeiras mensagens, compradores e receita. Os links podem estar no seu próprio **domínio**, disparar **pixels** de anúncios (Meta, TikTok, Snap) e enviar **eventos** ao servidor. Esses endpoints correspondem à página **Tracking**.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/links` | Lista links (`creator_id=`, `archived=false`) com seus contadores | `can_tracking` ou `can_sales_read` | Planned |
| POST | `/links` | Cria um link | `can_tracking` | Planned |
| GET | `/links/{id}` | Um link | `can_tracking` ou `can_sales_read` | Planned |
| PUT | `/links/{id}` | Substitui um link (nome, slug, domínio, destino, UTM, pixels) | `can_tracking` | Planned |
| DELETE | `/links/{id}` | Arquiva um link (`permanent=1` o exclui) | `can_tracking` | Planned |
| GET | `/domains` | Seus domínios (`status=active,inactive`, `q=`) | `can_tracking` | Planned |
| POST | `/domains` | Adiciona um domínio (status `pending`) | `can_tracking` | Planned |
| POST | `/domains/{host}/verify` | Verifica seus registros DNS agora | `can_tracking` | Planned |
| PATCH | `/domains/{host}` | Define um domínio verificado como padrão, ou altera seu rótulo | `can_tracking` | Planned |
| DELETE | `/domains/{host}` | Remove um domínio que nenhum link ativo usa | `can_tracking` | Planned |
| GET | `/pixels` | As conexões Meta, TikTok e Snap e o modo de consentimento | `can_tracking` | Planned |
| PUT | `/pixels/{provider}` | Conecta ou substitui um pixel (`meta`, `tiktok`, `snap`) | `owner` | Planned |
| DELETE | `/pixels/{provider}` | Desconecta um pixel | `owner` | Planned |
| POST | `/pixels/{provider}/test` | Envia um evento de teste e retorna a resposta da plataforma | `can_tracking` | Planned |
| PUT | `/pixels/consent` | Modo de consentimento: `page` ou `implicit_by_country` | `owner` | Planned |
| GET | `/events` | Eventos embutidos e personalizados, com contagem de entregas em 7 dias | `can_tracking` | Planned |
| POST | `/events` | Cria um evento personalizado | `owner` | Planned |
| PATCH | `/events/{id}` | Liga ou desliga um evento por rede | `owner` | Planned |
| DELETE | `/events/{id}` | Exclui um evento personalizado | `owner` | Planned |
| GET | `/stats` | Totais diários, por link e por fonte (`from=`, `to=`, `creator_id=`) | `can_sales_read` | Planned |
| GET | `/stats/export.csv` | Os mesmos números em CSV | `can_sales_read` | Planned |

## O objeto link

```json
{
  "id": "lnk_3",
  "name": "TikTok · Lea night",
  "slug": "lea-tiktok-night",
  "creator_id": "cr_lea",
  "source": "tiktok",
  "campaign": "Autumn",
  "domain": "go.mia-links.com",
  "public_url": "https://go.mia-links.com/r/lea-tiktok-night",
  "destination": "pool",
  "account_id": null,
  "utm": { "source": "tiktok", "medium": "social", "campaign": "autumn" },
  "pixels": { "meta": false, "tiktok": true, "snap": false },
  "counters": { "clicks": 640, "conversations": 97, "first_messages": 76, "buyers": 14, "revenue_stars": 6200 },
  "archived": false,
  "created_at": "2026-09-12T08:00:00Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Começa com `lnk_` |
| `name` | string | O nome que sua equipe vê |
| `slug` | string | O final da URL pública |
| `creator_id` | string | A criadora para quem o link envia |
| `source`, `campaign` | string | De onde vem o tráfego e o nome da sua campanha |
| `domain` | string | Um domínio verificado do workspace, ou o domínio LanaChat |
| `public_url` | string | `https://<domain>/r/<slug>`: a URL para colocar na bio ou anúncio |
| `destination` | string | `pool` ou `account` |
| `account_id` | string ou null | A conta fixa quando `destination` é `account` |
| `utm` | object | `source`, `medium`, `campaign` |
| `pixels` | object | Quais pixels conectados disparam neste link |
| `counters` | object | `clicks`, `conversations`, `first_messages`, `buyers`, `revenue_stars` |
| `archived` | boolean | Links arquivados são excluídos das estatísticas |
| `created_at` | string | ISO 8601, UTC |

- `destination` é `pool` (a conta é escolhida no clique entre a pool da criadora, veja [pools](https://lanachat.ai/guides/pt/api-telegram-accounts/)) ou `account` (sempre a mesma `account_id`).
- `slug`: letras minúsculas, dígitos e traços, 1 a 48 caracteres, começando e terminando com letra ou dígito, único entre links ativos do mesmo domínio.
- `domain` deve ser um domínio verificado do workspace; sem ele, usa-se o domínio LanaChat.
- Valores `utm`: até 80 letras, dígitos, pontos, traços ou underscores. São marcados em cada clique e enviados aos eventos dos pixels.

## O objeto domínio

```json
{
  "host": "go.mia-links.com",
  "builtin": false,
  "status": "pending",
  "error": null,
  "ssl": "none",
  "is_default": false,
  "label": "Lea TikTok",
  "token": "8be03d5f19a2",
  "checks": 0,
  "added_at": "2026-10-05T10:00:00Z",
  "verified_at": null,
  "last_check_at": null
}
```

| Field | Type | Description |
|---|---|---|
| `host` | string | Um subdomínio em minúsculas (pelo menos 3 níveis), único no workspace |
| `builtin` | boolean | `true` para o domínio LanaChat, que nunca pode ser removido |
| `status` | string | `verified`, `pending` ou `error` |
| `error` | string ou null | Uma frase simples quando `status` é `error` |
| `ssl` | string | `none`, `issuing` ou `active` |
| `is_default` | boolean | Exatamente um domínio verificado é o padrão |
| `label` | string ou null | Um nome para sua equipe, até 60 caracteres |
| `token` | string | O valor do registro TXT de verificação |
| `checks` | number | Verificações DNS feitas até agora |
| `added_at`, `verified_at`, `last_check_at` | string ou null | ISO 8601, UTC |

## O objeto conexão de pixel

```json
{ "connected": true, "pixel_id": "123456789012345", "token_last4": "x9Qa", "token_status": "valid", "token_error": null, "test_event_code": "TEST4821", "connected_at": "2026-10-06T14:30:00Z" }
```

| Field | Type | Description |
|---|---|---|
| `connected` | boolean | O pixel está conectado |
| `pixel_id` | string | Meta: 15 ou 16 dígitos. TikTok: 20 letras maiúsculas ou dígitos. Snap: um UUID |
| `token_last4` | string | Os últimos 4 caracteres do token de acesso, nunca o token completo |
| `token_status` | string | `valid`, `expired` ou `invalid` |
| `token_error` | string ou null | Uma frase simples, por exemplo "Access token expired on 3 Oct. Replace it to resume delivery." |
| `test_event_code` | string ou null | O código de teste do gerenciador de eventos da plataforma |
| `connected_at` | string | ISO 8601, UTC |

## O objeto evento

```json
{
  "id": "evt_purchase",
  "name": "Purchase",
  "builtin": true,
  "trigger": { "type": "purchase" },
  "networks": { "meta": true, "tiktok": true, "snap": false }
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | O id do evento |
| `name` | string | Nome embutido, ou seu nome personalizado: uma letra, depois até 39 letras, dígitos ou underscores, único no workspace |
| `builtin` | boolean | `true` para Lead, Contact, Purchase, Subscribe e InitiateCheckout |
| `trigger` | object | `type`, e um `value` para os triggers que precisam |
| `networks` | object | Ligado ou desligado para `meta`, `tiktok` e `snap` |

## O objeto estatísticas

```json
{
  "days":    [ { "date": "2026-10-05", "clicks": 54, "conversations": 9, "first_messages": 7, "buyers": 2, "revenue_stars": 950 } ],
  "links":   [ { "link_id": "lnk_3", "clicks": 640, "conversations": 97, "first_messages": 76, "buyers": 14, "revenue_stars": 6200 } ],
  "sources": [ { "source": "instagram", "clicks": 1210, "conversations": 160, "first_messages": 131, "buyers": 22, "revenue_stars": 9100 } ]
}
```

| Field | Type | Description |
|---|---|---|
| `days` | array | Uma linha por dia UTC do período |
| `links` | array | Uma linha por link, no período todo |
| `sources` | array | Uma linha por grupo de fonte: `instagram`, `tiktok`, `snapchat`, `meta`, `x` e `other` |
| `clicks` | number | Redirecionamentos servidos |
| `conversations` | number | Conversas no Telegram iniciadas pelo link |
| `first_messages` | number | Fans que escreveram pelo menos uma vez |
| `buyers` | number | Fans distintos com compra verificada de Stars no período |
| `revenue_stars` | number | Compras verificadas de Stars desses fans no período |

## Links

### Listar links

`GET /links` · `can_tracking` ou `can_sales_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Não | Apenas links desta criadora |
| `archived` | boolean | Não | `false` (visualização padrão) oculta links arquivados |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/links?creator_id=cr_lea&archived=false" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta é uma lista paginada de objetos link, cada um com seus `counters`.

### Criar um link

`POST /links` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Sim | O nome que sua equipe vê |
| `slug` | string | Sim | Letras minúsculas, dígitos e traços, 1 a 48 caracteres |
| `creator_id` | string | Sim | A criadora para quem o link envia |
| `source` | string | Não | `instagram`, `tiktok`, `snapchat`, `meta`, `x` ou outra fonte |
| `campaign` | string | Não | O nome da sua campanha |
| `destination` | string | Não | `pool` ou `account` |
| `account_id` | string | Quando `destination` é `account` | A conta fixa do Telegram |
| `domain` | string | Não | Um domínio verificado; sem ele, o domínio LanaChat |
| `utm` | object | Não | `source`, `medium`, `campaign` |
| `pixels` | object | Não | `meta`, `tiktok`, `snap`: `true` para disparar o pixel |

```bash
curl -X POST https://api.lanachat.ai/v1/links \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Insta bio · Lea", "slug": "lea-bio", "creator_id": "cr_lea", "source": "instagram", "destination": "pool", "domain": "go.mia-links.com"}'
```

```json
{
  "id": "lnk_9",
  "name": "Insta bio · Lea",
  "slug": "lea-bio",
  "creator_id": "cr_lea",
  "source": "instagram",
  "campaign": null,
  "domain": "go.mia-links.com",
  "public_url": "https://go.mia-links.com/r/lea-bio",
  "destination": "pool",
  "account_id": null,
  "utm": { "source": null, "medium": null, "campaign": null },
  "pixels": { "meta": false, "tiktok": false, "snap": false },
  "counters": { "clicks": 0, "conversations": 0, "first_messages": 0, "buyers": 0, "revenue_stars": 0 },
  "archived": false,
  "created_at": "2026-10-06T14:40:00Z"
}
```

- Um slug já usado responde `409` com `The slug /lea-bio is already used by "Insta bio · Mia".`
- Um domínio não verificado responde `400` ("Pick a verified domain…").

### Obter um link

`GET /links/{id}` · `can_tracking` ou `can_sales_read`

```bash
curl https://api.lanachat.ai/v1/links/lnk_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta é o objeto link. Um id desconhecido responde `404`.

### Substituir um link

`PUT /links/{id}` · `can_tracking`

Mesmo corpo que **Criar um link**; o `PUT` substitui o link inteiro, então envie todos os campos que quiser manter.

```bash
curl -X PUT https://api.lanachat.ai/v1/links/lnk_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "TikTok · Lea night", "slug": "lea-tiktok-night", "creator_id": "cr_lea", "source": "tiktok", "campaign": "Autumn", "destination": "pool", "domain": "go.mia-links.com", "utm": {"source": "tiktok", "medium": "social", "campaign": "autumn"}, "pixels": {"meta": false, "tiktok": true, "snap": false}}'
```

A resposta é o link atualizado. Mesmos erros que ao criar.

### Arquivar ou excluir um link

`DELETE /links/{id}` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `permanent` | number | Não | `1` exclui o link permanentemente em vez de arquivá-lo |

```bash
curl -X DELETE https://api.lanachat.ai/v1/links/lnk_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Um link arquivado é excluído das estatísticas.

## Domínios

Para usar seu próprio domínio, adicione-o, crie dois registros DNS e depois verifique:

- `CNAME go.mia-links.com → links.lanachat.app`
- `TXT _lanachat.go.mia-links.com = lanachat-verify=8be03d5f19a2`

Domínios pendentes também são verificados a cada 10 minutos por 72 horas, depois diariamente. O `status` vira `verified` e o `ssl` passa a `issuing` e depois `active`.

### Listar domínios

`GET /domains` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | string | Não | `active` (verificado) ou `inactive` (pendente ou erro) |
| `q` | string | Não | Parte do host ou do rótulo |

```bash
curl "https://api.lanachat.ai/v1/domains?status=active" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta lista objetos domínio, incluindo o domínio LanaChat (`builtin: true`).

### Adicionar um domínio

`POST /domains` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `host` | string | Sim | Um subdomínio, por exemplo `go.mia-links.com` |

```bash
curl -X POST https://api.lanachat.ai/v1/domains \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"host": "go.mia-links.com"}'
```

A resposta é o novo domínio com `status: "pending"` e seu `token` para o registro TXT. O host é limpo (minúsculas, sem `https://`, sem caminho). Domínios raiz, `*.lanachat.app` e domínios já adicionados respondem `400` com uma frase.

### Verificar um domínio

`POST /domains/{host}/verify` · `can_tracking`

```bash
curl -X POST https://api.lanachat.ai/v1/domains/go.mia-links.com/verify \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "host": "go.mia-links.com", "builtin": false, "status": "verified", "error": null, "ssl": "issuing", "is_default": false, "label": null, "token": "8be03d5f19a2", "checks": 3, "added_at": "2026-10-05T10:00:00Z", "verified_at": "2026-10-06T14:45:00Z", "last_check_at": "2026-10-06T14:45:00Z" }
```

Quando um registro está errado, o `status` é `error` e o `error` diz qual, por exemplo "The CNAME record points to another service." O domínio LanaChat não pode ser verificado (seu DNS é gerenciado pelo LanaChat).

### Alterar um domínio

`PATCH /domains/{host}` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `is_default` | boolean | Não | `true` para torná-lo o domínio padrão; o padrão anterior deixa de ser |
| `label` | string ou null | Não | Um nome para sua equipe, até 60 caracteres |

```bash
curl -X PATCH https://api.lanachat.ai/v1/domains/go.mia-links.com \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_default": true}'
```

Só um domínio verificado pode ser padrão. O domínio LanaChat rejeita rótulo (`403`).

### Remover um domínio

`DELETE /domains/{host}` · `can_tracking`

```bash
curl -X DELETE https://api.lanachat.ai/v1/domains/go.mia-links.com \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Remover o domínio LanaChat, o domínio padrão ("Set another default domain first") ou um domínio usado por links ativos ("Used by N active links across all creators") responde `409`.

## Pixels

Eventos são enviados servidor a servidor, deduplicados com o pixel do navegador pelo mesmo `event_id`, com o id do Telegram do fan hashado (SHA-256), nunca cru. Sem consentimento, nenhum evento é enviado, jamais. Um pixel dispara só para links que o habilitam.

### Ler conexões de pixel

`GET /pixels` · `can_tracking`

```bash
curl https://api.lanachat.ai/v1/pixels \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta contém uma conexão de pixel para cada um de `meta`, `tiktok` e `snap`, e o `mode` de consentimento.

### Conectar um pixel

`PUT /pixels/{provider}` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pixel_id` | string | Sim | Meta: 15 ou 16 dígitos. TikTok: 20 letras maiúsculas ou dígitos. Snap: um UUID |
| `access_token` | string | Sim | O token da API de Conversions da plataforma |
| `test_event_code` | string | Não | O código de teste da plataforma |

```bash
curl -X PUT https://api.lanachat.ai/v1/pixels/meta \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pixel_id": "123456789012345", "access_token": "EAAG…", "test_event_code": "TEST4821"}'
```

```json
{ "connected": true, "pixel_id": "123456789012345", "token_last4": "x9Qa", "token_status": "valid", "token_error": null, "test_event_code": "TEST4821", "connected_at": "2026-10-06T14:30:00Z" }
```

O token de acesso é armazenado criptografado e nunca retornado: só `token_last4`. Um pixel id em formato errado ou token vazio responde `400`.

### Desconectar um pixel

`DELETE /pixels/{provider}` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/pixels/meta \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

### Enviar um evento de teste

`POST /pixels/{provider}/test` · `can_tracking`

```bash
curl -X POST https://api.lanachat.ai/v1/pixels/meta/test \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "ok": true, "status": 200, "body": "{\"events_received\":1}" }
```

`status` e `body` são a resposta da própria plataforma, assim você vê exatamente o que Meta, TikTok ou Snap disseram.

### Definir o modo de consentimento

`PUT /pixels/consent` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `mode` | string | Sim | `page`: uma tela de consentimento para cada fan antes do Telegram abrir. `implicit_by_country`: a tela só na UE, EEE, Reino Unido e Suíça |

```bash
curl -X PUT https://api.lanachat.ai/v1/pixels/consent \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "implicit_by_country"}'
```

## Eventos

Eventos embutidos: Lead (conversa iniciada por link), Contact (primeira mensagem do fan), Purchase (venda verificada), Subscribe, InitiateCheckout. Eventos personalizados têm um trigger: `sale_over` (venda acima de um valor em dólares), `tag_added` (uma tag), `nth_message` (a N-ésima mensagem do fan, 2 ou mais) ou `offer_viewed`.

### Listar eventos

`GET /events` · `can_tracking`

```bash
curl https://api.lanachat.ai/v1/events \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta lista objetos evento com suas entregas aceitas e falhas em 7 dias, por rede.

### Criar um evento personalizado

`POST /events` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Sim | Uma letra, depois até 39 letras, dígitos ou underscores; único no workspace |
| `trigger` | object | Sim | `type`: `sale_over`, `tag_added`, `nth_message` ou `offer_viewed`; `value` para os três primeiros |
| `networks` | object | Não | `meta`, `tiktok`, `snap`: `true` para enviar lá |

```bash
curl -X POST https://api.lanachat.ai/v1/events \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "BigSpender", "trigger": {"type": "sale_over", "value": 50}, "networks": {"meta": true, "tiktok": true, "snap": false}}'
```

A resposta é o novo evento (`201`). Um nome já usado responde `409`.

### Ligar ou desligar um evento

`PATCH /events/{id}` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `networks` | object | Sim | `meta`, `tiktok`, `snap`: `true` ou `false` |

```bash
curl -X PATCH https://api.lanachat.ai/v1/events/evt_purchase \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"networks": {"meta": true, "tiktok": true, "snap": true}}'
```

### Excluir um evento personalizado

`DELETE /events/{id}` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/events/evt_bigspender \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Eventos embutidos não podem ser excluídos; desligue-os.

## Estatísticas

### Ler estatísticas

`GET /stats` · `can_sales_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from` | string | Sim | Primeiro dia UTC, `YYYY-MM-DD`, incluído |
| `to` | string | Sim | Último dia UTC, `YYYY-MM-DD`, incluído |
| `creator_id` | string | Não | Apenas esta criadora; sem ele, todas |

```bash
curl "https://api.lanachat.ai/v1/stats?from=2026-09-06&to=2026-10-05&creator_id=cr_lea" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta é o objeto estatísticas. Dias são UTC; links arquivados são excluídos.

### Exportar estatísticas como CSV

`GET /stats/export.csv` · `can_sales_read`

Mesmos parâmetros que `GET /stats`.

```bash
curl "https://api.lanachat.ai/v1/stats/export.csv?from=2026-09-06&to=2026-10-05" \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o stats.csv
```

```text
date,link,slug,domain,creator,source,clicks,conversations,first_messages,buyers,revenue_stars
2026-10-05,TikTok · Lea night,lea-tiktok-night,go.mia-links.com,Lea,tiktok,54,9,7,2,950
```

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [Rastreamento: links, domínios e análises](https://lanachat.ai/guides/pt/tracking-links/)
- [API: Contas do Telegram, pools e stories](https://lanachat.ai/guides/pt/api-telegram-accounts/)