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

_API · Читання 9 хв · Оновлено 2026-10-22 · https://lanachat.ai/guides/uk/api-tracking/_

**Трекінговий лінк** перенаправляє відвідувача до авторки в Telegram і рахує подальші дії: кліки, розмови, перші повідомлення, покупців і дохід. Лінки можуть працювати на вашому **домені**, запускати рекламні **пікселі** (Meta, TikTok, Snap) і надсилати серверні **події**. Ці endpoint-и відповідають сторінці **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 |

## Об'єкт лінка

```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 | Перевірений домен workspace або домен 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/uk/api-telegram-accounts/)) або `account` (завжди той самий `account_id`).
- `slug`: маленькі літери, цифри та дефіси, 1-48 символів, починається й закінчується літерою або цифрою, унікальний серед активних лінків цього домену.
- `domain` має бути перевіреним доменом workspace; без нього використовується домен LanaChat.
- Значення `utm`: до 80 літер, цифр, крапок, дефісів або підкреслень. Вони додаються до кожного кліку й передаються у події пікселів.

## Об'єкт домену

```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 частини), унікальний у workspace |
| `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 |

## Об'єкт підключення пікселя

```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 не повертається |
| `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 |

## Об'єкт події

```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 літер, цифр чи підкреслень, унікальна у workspace |
| `builtin` | boolean | `true` для Lead, Contact, Purchase, Subscribe і InitiateCheckout |
| `trigger` | object | `type` і `value` для тригерів, які це потребують |
| `networks` | object | Увімкнено чи вимкнено для `meta`, `tiktok`, `snap` |

## Об'єкт статистики

```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 цими фанами за період |

## Лінки

### Список лінків

`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/uk/api-overview/) |

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

Відповідь, це сторінковий список об'єктів лінків, кожен із його `counters`.

### Створити лінк

`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 /links/{id}` · `can_tracking` або `can_sales_read`

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

Відповідь, об'єкт лінка. Невідомий id повертає `404`.

### Замінити лінк

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

Тіло таке саме, як у **Створити лінк**; `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}}'
```

Відповідь, оновлений лінк. Помилки такі ж, як при створенні.

### Архівувати або видалити лінк

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

Архівований лінк не враховується у статистиці.

## Домени

Щоб використовувати власний домен, додайте його, створіть два DNS-записи, потім підтвердьте:

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

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

### Список доменів

`GET /domains` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | string | No | `active` (перевірені) або `inactive` (pending чи error) |
| `q` | string | No | Частина host або label |

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

Відповідь, список об'єктів доменів, включно з доменом LanaChat (`builtin: true`).

### Додати домен

`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` з поясненням.

### Перевірити домен

`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).

### Змінити домен

`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`).

### Видалити домен

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

## Пікселі

Події надсилаються сервер-сервер, дублюються з браузерним пікселем через той самий `event_id`, id Telegram фана хешується (SHA-256), ніколи не передається у відкритому вигляді. Без згоди подія не надсилається взагалі. Піксель спрацьовує лише для лінків, де він увімкнений.

### Переглянути підключення пікселів

`GET /pixels` · `can_tracking`

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

Відповідь містить по одному об'єкту підключення пікселя для `meta`, `tiktok` і `snap`, а також режим згоди `mode`.

### Підключити піксель

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

### Відключити піксель

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

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

### Надіслати тестову подію

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

### Встановити режим згоди

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

## Події

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

### Список подій

`GET /events` · `can_tracking`

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

Відповідь, список об'єктів подій з кількістю доставок і помилок за 7 днів по мережах.

### Створити кастомну подію

`POST /events` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Літера, далі до 39 літер, цифр чи підкреслень; унікальна у workspace |
| `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`.

### Увімкнути або вимкнути подію

`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 /events/{id}` · `owner`

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

Вбудовані події не можна видалити; просто вимкніть їх.

## Статистика

### Переглянути статистику

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

Відповідь, об'єкт статистики. Дати у UTC; архівовані лінки не враховуються.

### Експорт статистики у 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/uk/api-overview/)
- [Відстеження: посилання, домени та аналітика](https://lanachat.ai/guides/uk/tracking-links/)
- [API: Telegram-акаунти, пули та історії](https://lanachat.ai/guides/uk/api-telegram-accounts/)