# API: трекинг-ссылки, домены, пиксели и статистика

_API · Чтение 9 мин · Обновлено 2026-10-22 · https://lanachat.ai/guides/ru/api-tracking/_

**Трекинг-ссылка** отправляет посетителя к автору в Telegram и считает, что происходит дальше: клики, диалоги, первые сообщения, покупки и выручку. Ссылки могут работать на вашем собственном **домене**, запускать рекламные **пиксели** (Meta, TikTok, Snap) и отправлять серверные **события**. Эти эндпоинты соответствуют странице **Tracking**.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/links` | Список ссылок (`creator_id=`, `archived=false`) с их счетчиками | `can_tracking` или `can_sales_read` | Planned |
| POST | `/links` | Создать ссылку | `can_tracking` | Planned |
| GET | `/links/{id}` | Одна ссылка | `can_tracking` или `can_sales_read` | Planned |
| PUT | `/links/{id}` | Заменить ссылку (name, slug, domain, destination, UTM, pixels) | `can_tracking` | Planned |
| DELETE | `/links/{id}` | Архивировать ссылку (`permanent=1` удаляет её) | `can_tracking` | Planned |
| GET | `/domains` | Ваши домены (`status=active,inactive`, `q=`) | `can_tracking` | Planned |
| POST | `/domains` | Добавить домен (status `pending`) | `can_tracking` | Planned |
| POST | `/domains/{host}/verify` | Проверить DNS-записи сейчас | `can_tracking` | Planned |
| PATCH | `/domains/{host}` | Сделать проверенный домен основным или изменить его label | `can_tracking` | Planned |
| DELETE | `/domains/{host}` | Удалить домен, который не используется активными ссылками | `can_tracking` | Planned |
| GET | `/pixels` | Подключения Meta, TikTok и Snap и режим согласия | `can_tracking` | Planned |
| PUT | `/pixels/{provider}` | Подключить или заменить пиксель (`meta`, `tiktok`, `snap`) | `owner` | Planned |
| DELETE | `/pixels/{provider}` | Отключить пиксель | `owner` | Planned |
| POST | `/pixels/{provider}/test` | Отправить тестовое событие и вернуть ответ платформы | `can_tracking` | Planned |
| PUT | `/pixels/consent` | Режим согласия: `page` или `implicit_by_country` | `owner` | Planned |
| GET | `/events` | Встроенные и кастомные события, с количеством доставок за 7 дней | `can_tracking` | Planned |
| POST | `/events` | Создать кастомное событие | `owner` | Planned |
| PATCH | `/events/{id}` | Включить или выключить событие по сетям | `owner` | Planned |
| DELETE | `/events/{id}` | Удалить кастомное событие | `owner` | Planned |
| GET | `/stats` | Суточные итоги, по ссылкам и источникам (`from=`, `to=`, `creator_id=`) | `can_sales_read` | Planned |
| GET | `/stats/export.csv` | Те же цифры в CSV | `can_sales_read` | Planned |

## The link object

```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 | Начинается с `lnk_` |
| `name` | string | Имя, которое видит ваша команда |
| `slug` | string | Конец публичного URL |
| `creator_id` | string | Автор, на которого ведет ссылка |
| `source`, `campaign` | string | Откуда идет трафик и название вашей кампании |
| `domain` | string | Проверенный домен рабочего пространства или домен LanaChat |
| `public_url` | string | `https://<domain>/r/<slug>`: URL для размещения в био или рекламе |
| `destination` | string | `pool` или `account` |
| `account_id` | string или null | Фиксированный аккаунт, если `destination`, `account` |
| `utm` | object | `source`, `medium`, `campaign` |
| `pixels` | object | Какие подключенные пиксели срабатывают по этой ссылке |
| `counters` | object | `clicks`, `conversations`, `first_messages`, `buyers`, `revenue_stars` |
| `archived` | boolean | Архивные ссылки не попадают в статистику |
| `created_at` | string | ISO 8601, UTC |

- `destination`, это `pool` (аккаунт выбирается при клике из пула автора, см. [pools](https://lanachat.ai/guides/ru/api-telegram-accounts/)) или `account` (всегда один и тот же `account_id`).
- `slug`: строчные буквы, цифры и дефисы, от 1 до 48 символов, начинается и заканчивается буквой или цифрой, уникален среди активных ссылок на одном домене.
- `domain` должен быть проверенным доменом рабочего пространства; если не указан, используется домен LanaChat.
- Значения `utm`: до 80 букв, цифр, точек, дефисов или подчеркиваний. Они проставляются при каждом клике и передаются в события пикселей.

## The domain object

```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 | Поддомен в нижнем регистре (минимум 3 части), уникален в рабочем пространстве |
| `builtin` | boolean | `true` для домена LanaChat, который нельзя удалить |
| `status` | string | `verified`, `pending` или `error` |
| `error` | string или null | Простое сообщение, если `status`, `error` |
| `ssl` | string | `none`, `issuing` или `active` |
| `is_default` | boolean | Ровно один проверенный домен, основной |
| `label` | string или null | Имя для вашей команды, до 60 символов |
| `token` | string | Значение TXT-записи для верификации |
| `checks` | number | Сколько раз проверялись DNS |
| `added_at`, `verified_at`, `last_check_at` | string или null | ISO 8601, UTC |

## The pixel connection object

```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 | Пиксель подключен |
| `pixel_id` | string | Meta: 15 или 16 цифр. TikTok: 20 заглавных букв или цифр. Snap: UUID |
| `token_last4` | string | Последние 4 символа access token, сам токен не возвращается |
| `token_status` | string | `valid`, `expired` или `invalid` |
| `token_error` | string или null | Простое сообщение, например "Access token expired on 3 Oct. Replace it to resume delivery." |
| `test_event_code` | string или null | Тестовый код в менеджере событий платформы |
| `connected_at` | string | ISO 8601, UTC |

## The event object

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

| Field | Type | Description |
|---|---|---|
| `id` | string | ID события |
| `name` | string | Встроенное имя или ваше: буква, затем до 39 букв, цифр или подчеркиваний, уникально в рабочем пространстве |
| `builtin` | boolean | `true` для Lead, Contact, Purchase, Subscribe и InitiateCheckout |
| `trigger` | object | `type` и `value` для нужных триггеров |
| `networks` | object | Включено или выключено для `meta`, `tiktok` и `snap` |

## The stats object

```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 | Одна строка на каждый UTC-день периода |
| `links` | array | Одна строка на каждую ссылку за весь период |
| `sources` | array | Одна строка на каждую группу источников: `instagram`, `tiktok`, `snapchat`, `meta`, `x` и `other` |
| `clicks` | number | Перенаправления по ссылке |
| `conversations` | number | Диалоги в Telegram, начатые по ссылке |
| `first_messages` | number | Фаны, написавшие хотя бы раз |
| `buyers` | number | Уникальные фаны с подтвержденной покупкой Stars за период |
| `revenue_stars` | number | Подтвержденные покупки Stars этими фанами за период |

## Links

### List links

`GET /links` · `can_tracking` или `can_sales_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | No | Только ссылки этого автора |
| `archived` | boolean | No | `false` (по умолчанию) скрывает архивные ссылки |
| `limit`, `cursor` | number, string | No | [Пагинация](https://lanachat.ai/guides/ru/api-overview/) |

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

Ответ, постраничный список link objects, каждый со своими `counters`.

### Create a link

`POST /links` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Имя, которое видит ваша команда |
| `slug` | string | Yes | Строчные буквы, цифры и дефисы, от 1 до 48 символов |
| `creator_id` | string | Yes | Автор, на которого ведет ссылка |
| `source` | string | No | `instagram`, `tiktok`, `snapchat`, `meta`, `x` или другой источник |
| `campaign` | string | No | Название вашей кампании |
| `destination` | string | No | `pool` или `account` |
| `account_id` | string | Когда `destination`, `account` | Фиксированный Telegram-аккаунт |
| `domain` | string | No | Проверенный домен; если не указан, домен LanaChat |
| `utm` | object | No | `source`, `medium`, `campaign` |
| `pixels` | object | No | `meta`, `tiktok`, `snap`: `true`, чтобы сработал этот пиксель |

```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"
}
```

- Если slug уже занят, ответ, `409` с `The slug /lea-bio is already used by "Insta bio · Mia".`
- Если домен не проверен, ответ, `400` ("Pick a verified domain…").

### Get a link

`GET /links/{id}` · `can_tracking` или `can_sales_read`

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

Ответ, link object. Неизвестный id, ответ `404`.

### Replace a link

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

Тело такое же, как у **Create a link**; `PUT` заменяет всю ссылку, поэтому передавайте все поля, которые хотите сохранить.

```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}}'
```

Ответ, обновленная ссылка. Ошибки такие же, как при создании.

### Archive or delete a link

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `permanent` | number | No | `1` удаляет ссылку полностью вместо архивирования |

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

Архивная ссылка не попадает в статистику.

## Domains

Чтобы использовать свой домен, добавьте его, создайте две DNS-записи и затем подтвердите:

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

Ожидающие домены также проверяются каждые 10 минут в течение 72 часов, затем раз в день. `status` становится `verified`, а `ssl` переходит в `issuing`, затем в `active`.

### List domains

`GET /domains` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | string | No | `active` (проверен) или `inactive` (ожидание или ошибка) |
| `q` | string | No | Часть host или label |

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

Ответ, список domain objects, включая домен LanaChat (`builtin: true`).

### Add a domain

`POST /domains` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `host` | string | Yes | Поддомен, например `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"}'
```

Ответ, новый домен со `status: "pending"` и его `token` для TXT-записи. Host очищается (нижний регистр, без `https://`, без пути). Корневые домены, `*.lanachat.app` и уже добавленный домен, ответ `400` с сообщением.

### Verify a domain

`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" }
```

Если запись неверна, `status`, `error`, а `error` объясняет причину, например "The CNAME record points to another service." Домен LanaChat нельзя верифицировать (его DNS управляется LanaChat).

### Change a domain

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `is_default` | boolean | No | `true` делает этот домен основным; предыдущий перестает быть основным |
| `label` | string или null | No | Имя для вашей команды, до 60 символов |

```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}'
```

Только проверенный домен может быть основным. Домен LanaChat не принимает label (`403`).

### Remove a domain

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

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

Удаление домена LanaChat, основного домена ("Set another default domain first") или домена, используемого активными ссылками ("Used by N active links across all creators"), ответ `409`.

## Pixels

События отправляются сервер-сервер, дублируются с браузерным пикселем через тот же `event_id`, Telegram id фана хэшируется (SHA-256), никогда не передается в открытом виде. Без согласия событие не отправляется вообще. Пиксель срабатывает только для ссылок, где он включен.

### Read pixel connections

`GET /pixels` · `can_tracking`

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

Ответ содержит по одному pixel connection для каждого из `meta`, `tiktok` и `snap`, а также режим согласия `mode`.

### Connect a pixel

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pixel_id` | string | Yes | Meta: 15 или 16 цифр. TikTok: 20 заглавных букв или цифр. Snap: UUID |
| `access_token` | string | Yes | Conversions API token платформы |
| `test_event_code` | string | No | Тестовый код платформы |

```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" }
```

Access token хранится зашифрованно и никогда не возвращается: только `token_last4`. Если pixel id в неверном формате или token пустой, ответ `400`.

### Disconnect a pixel

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

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

### Send a test event

`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` и `body`, это ответ самой платформы, чтобы вы видели, что именно вернули Meta, TikTok или Snap.

### Set the consent mode

`PUT /pixels/consent` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `mode` | string | Yes | `page`: экран согласия для каждого фана перед открытием Telegram. `implicit_by_country`: экран только для ЕС, ЕЭЗ, Великобритании и Швейцарии |

```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"}'
```

## Events

Встроенные события: Lead (диалог начат по ссылке), Contact (первое сообщение фана), Purchase (подтвержденная покупка), Subscribe, InitiateCheckout. Кастомные события требуют триггер: `sale_over` (покупка выше суммы в долларах США), `tag_added` (тег), `nth_message` (N-е сообщение фана, 2 и более) или `offer_viewed`.

### List events

`GET /events` · `can_tracking`

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

Ответ, список event objects с количеством доставок (успешных и неудачных) за 7 дней по сетям.

### Create a custom event

`POST /events` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Буква, затем до 39 букв, цифр или подчеркиваний; уникально в рабочем пространстве |
| `trigger` | object | Yes | `type`: `sale_over`, `tag_added`, `nth_message` или `offer_viewed`; `value` для первых трех |
| `networks` | object | No | `meta`, `tiktok`, `snap`: `true`, чтобы отправлять туда |

```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}}'
```

Ответ, новое событие (`201`). Уже занятое имя, ответ `409`.

### Turn an event on or off

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `networks` | object | Yes | `meta`, `tiktok`, `snap`: `true` или `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}}'
```

### Delete a custom event

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

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

Встроенные события нельзя удалить; их можно только выключить.

## Stats

### Read stats

`GET /stats` · `can_sales_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from` | string | Yes | Первый UTC-день, `YYYY-MM-DD`, включительно |
| `to` | string | Yes | Последний UTC-день, `YYYY-MM-DD`, включительно |
| `creator_id` | string | No | Только этот автор; если не указан, все авторы |

```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"
```

Ответ, stats object. Дни, в UTC; архивные ссылки не учитываются.

### Export stats as CSV

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

Те же параметры, что и у `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
```

## Похожие статьи

- [LanaChat API: быстрое начало, аутентификация и ошибки](https://lanachat.ai/guides/ru/api-overview/)
- [Отслеживание: ссылки, домены и аналитика](https://lanachat.ai/guides/ru/tracking-links/)
- [API: Аккаунты Telegram, пулы и истории](https://lanachat.ai/guides/ru/api-telegram-accounts/)