# Персональный API tgtrack
Версия инструкции: 1
Дата инструкции: 2026-09-29
## Для человека
Отправьте агенту ссылку на эту страницу и попросите сделать навык (skill) по ней для бота «Откуда подписки».
Дальше в чате пишите, что нужно. Например: «сделай новую интеграцию в канале Реклама заработает».
Агент сам запросит персональный ключ и напишет, что нажать в боте. Ссылку на канал, id и JSON собирать не нужно: это делает агент.
## Для ИИ-агента
Прочитай страницу целиком и сделай навык. В навык запиши «Версия инструкции» и «Дата инструкции» с этой страницы. Человек формулирует задачу обычными словами. Запросы к API отправляешь ты.
Перед каждой задачей заново открой https://bot-api.tgtrack.ru/personal-api.md и сравни версию и дату со значениями в навыке. Если номер или дата на странице другие, обнови навык по свежей инструкции и только потом выполняй задачу. По устаревшему навыку запросы не отправляй.
Один контракт для Telegram и MAX. Отличаются только базовый URL и вид ссылки на канал.
Ключ даёт создавать яндекс-интеграции и трекинг-ссылки в каналах, к которым у владельца ключа есть доступ. Чат-методы (`user_did_start_bot`, `send_reach_goal`, вебхуки) этим ключом вызывать нельзя.
Если ключа ещё нет, API не вызывай. Остановись и попроси человека создать персональный ключ. Напиши ему эти шаги:
1. Откройте бота «Откуда подписки»: в Telegram это бот tgtrack, в MAX — бот tgtrack.
2. Отправьте команду `/personal_api`.
3. Нажмите «Создать персональный ключ».
4. Пришлите ключ в этот чат.
Ключ — секрет. Храни его в секрете навыка. В ответах человеку ключ целиком не показывай, если он сам не попросил. В другие чаты, тикеты и логи ключ не пиши.
Перевыпуск: та же команда `/personal_api`, кнопка «Перевыпустить». Старый ключ перестаёт работать сразу. После перевыпуска попроси новый ключ.
Если при создании яндекс-интеграции пришёл ответ `No live Yandex Metrika access. Create one integration with /integration_yandex in the bot first.`, попроси человека один раз сделать интеграцию в боте. Объясни, что так сохраняется доступ к Яндекс.Метрике, и следующие интеграции создашь ты.
- Telegram: `/integration_yandex`
- MAX: `/yandex`
Если канал не найден, код `405`, попроси человека подключить его к боту:
- Telegram: `/add_channel`
- MAX: `/add_chat`
## 1. Запрос
`POST`, тело — JSON.
Персональный ключ и имя метода стоят в пути. Заголовки `X-Api-Key`, `Authorization` и query `token` не используются. Вместо `<ключ>` подставь персональный ключ. Полный адрес каждого метода указан в его разделе.
- Telegram: `https://bot-api.tgtrack.ru/v1/<ключ>/get_channels`
- MAX: `https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_channels`
Успех:
```json
{
"status": "OK",
"data": {}
}
```
Ошибка:
```json
{
"status": "error",
"error_code": 422,
"error_description": "Unprocessable entity",
"error_details": "текст причины"
}
```
Коды:
| code | когда |
| --- | --- |
| 400 | нет метода или пустое тело |
| 401 | ключ не передан или неверный |
| 402 | ключ отозван |
| 403 | нет доступа к каналу, либо ключ не того типа |
| 405 | канал не подключён к боту |
| 409 | такое имя в канале уже есть |
| 422 | поля не прошли проверку, нет доступа к Метрике, Яндекс отказал |
| 429 | слишком много запросов |
Поле `channel` — ссылка на канал или его id в мессенджере. Внутренний id tgtrack не подходит. `channelID` из `get_channels` копируйте строкой, как есть.
- Telegram: `https://t.me/username`, пригласительная `https://t.me/+...` или id чата, например `-1001234567890`
- MAX: ссылка `max.ru/...` или id чата в MAX
## 2. Лимиты
Только персональный ключ: не больше 1 запроса в секунду и не больше 1000 запросов в сутки. При превышении код `429`.
Между вызовами держите паузу не меньше одной секунды. Пачку созданий не отправляйте параллельно.
## 3. get_channels
Список каналов, к которым у владельца ключа есть доступ. Тело не нужно.
`POST`
- Telegram: `https://bot-api.tgtrack.ru/v1/<ключ>/get_channels`
- MAX: `https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_channels`
По ответу агент сопоставляет имя из запроса пользователя с полем `name` и дальше передаёт `channelID` в поле `channel` других методов.
Успех, поле `data`:
```json
{
"channels": [
{
"channelID": "-1001234567890",
"name": "Реклама заработает",
"username": "reklama"
}
]
}
```
`channelID` в Telegram — id чата, в MAX — id чата MAX. `username` пустой, если у канала нет публичного адреса. Закрытый канал без публичной ссылки и без уже сохранённой пригласительной в `channel` по id не создаётся: передайте пригласительную ссылку.
## 4. create_yandex_integration
Создаёт яндекс-интеграцию и возвращает код ссылки и тег скрипта для сайта.
`POST`
- Telegram: `https://bot-api.tgtrack.ru/v1/<ключ>/create_yandex_integration`
- MAX: `https://max.tgtrack.ru/API/bot-api/v1/<ключ>/create_yandex_integration`
Тело:
```json
{
"name": "Директ — кампания 1",
"counterID": "12345678",
"channel": "https://t.me/username",
"autoFollow": false,
"goalToChannel": "toTelegram",
"goalOpen": "userDidOpenTelegram",
"goalSub": "userDidSubscribe"
}
```
Обязательны `name`, `counterID`, `channel`. Остальные поля можно не передавать: подставятся значения по умолчанию из примера. Имена целей по умолчанию в Telegram и MAX одни и те же.
`channel` — ссылка или id канала в мессенджере. Id берите из `get_channels` (`channelID`) и передавайте строкой, не числом.
```json
{
"name": "Директ — кампания 1",
"counterID": "12345678",
"channel": "-1001234567890"
}
```
Ссылка вместо id: Telegram `https://t.me/username` или `https://t.me/+...`, MAX `https://max.ru/...`. У закрытого канала без публичного адреса и без уже сохранённой пригласительной id не хватает: передайте пригласительную ссылку.
`counterID` — только цифры, длина 6–9. Имена целей уникальны, латиница, цифры и `_`, не длиннее 45 символов. `name` уникально внутри канала, не длиннее 100 символов.
Успех, поле `data`:
```json
{
"linkID": "AbCdEf",
"script": ""
}
```
Если живого доступа к Метрике нет, `error_details`: `No live Yandex Metrika access. Create one integration with /integration_yandex in the bot first.` В MAX текст тот же по смыслу: сначала одна интеграция через бота.
OAuth-токен Яндекса в запрос не передаётся.
## 5. get_yandex_integrations
Список яндекс-интеграций канала. В `channel` та же ссылка или тот же id, что и при создании.
`POST`
- Telegram: `https://bot-api.tgtrack.ru/v1/<ключ>/get_yandex_integrations`
- MAX: `https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_yandex_integrations`
```json
{
"channel": "-1001234567890"
}
```
Успех, поле `data`:
```json
{
"integrations": [
{
"name": "Директ — кампания 1",
"linkID": "AbCdEf",
"counterID": "12345678",
"autoFollow": false,
"goalToChannel": "toTelegram",
"goalOpen": "userDidOpenTelegram",
"goalSub": "userDidSubscribe",
"script": ""
}
]
}
```
## 6. create_tracking_link
Создаёт обычную трекинг-ссылку (посев, сайт, соцсеть), без рекламного кабинета.
`POST`
- Telegram: `https://bot-api.tgtrack.ru/v1/<ключ>/create_tracking_link`
- MAX: `https://max.tgtrack.ru/API/bot-api/v1/<ключ>/create_tracking_link`
```json
{
"name": "Посев — канал партнёра",
"channel": "https://t.me/username"
}
```
Обязательны `name` и `channel`. В `channel` ссылка или id канала, как в `create_yandex_integration`. Имя уникально в канале, не длиннее 100 символов.
Успех, поле `data`:
```json
{
"name": "Посев — канал партнёра",
"linkID": "AbCdEf",
"url": "https://click.example/AbCdEf",
"urlMessenger": "https://t.me/bot?start=TL..."
}
```
`url` — ссылка вне мессенджера. `urlMessenger` — ссылка для размещения внутри Telegram или MAX.
## 7. get_tracking_links
Список уже созданных трекинг-ссылок канала. Нужен, чтобы не упереться в занятое имя. В `channel` ссылка или id канала.
`POST`
- Telegram: `https://bot-api.tgtrack.ru/v1/<ключ>/get_tracking_links`
- MAX: `https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_tracking_links`
```json
{
"channel": "-1001234567890"
}
```
Успех, поле `data`:
```json
{
"links": [
{
"name": "Посев — канал партнёра",
"linkID": "AbCdEf",
"url": "https://click.example/AbCdEf",
"urlMessenger": "https://t.me/bot?start=TL..."
}
]
}
```
## 8. Порядок работы агента
- Перед задачей открой https://bot-api.tgtrack.ru/personal-api.md и сверь «Версия инструкции» и «Дата инструкции» с навыком. Если они отличаются, обнови навык и работай уже по новой версии.
- Ключа нет — остановись и попроси его по шагам из раздела «Для ИИ-агента». Запросы без ключа не отправляй. Ключ ставь в путь, как в адресах методов. Заголовки авторизации не передавай. Полный URL с ключом в логи и в ответ человеку не пиши.
- Методы только эти: `get_channels`, `create_yandex_integration`, `get_yandex_integrations`, `create_tracking_link`, `get_tracking_links`.
- Канал человек называет по имени или присылает ссылку. Если человек называет канал по имени, сначала вызови `get_channels`, найди `name` и передай его `channelID` строкой в поле `channel`. Ссылку проси только если подходящего канала в списке нет или у закрытого канала нет публичного адреса.
- Поля бери только из этой страницы. OAuth Яндекса и внутренние id tgtrack не передавай.
- Перед созданием вызови список интеграций или ссылок канала и проверь, что `name` свободно.
- Между запросами пауза не меньше 1 секунды. Лимит 1000 запросов в сутки.
- `403` с текстом `user API key required` значит, что передан чат-ключ, а не персональный. Попроси персональный ключ.
- `405` значит, что канал ещё не подключён к боту. Попроси человека добавить его командой из раздела «Для ИИ-агента».
- `409` значит, что имя занято: возьми другое или используй уже существующий `linkID`.
- Ответ `No live Yandex Metrika access...` значит, что человек ещё не делал первую интеграцию в боте. Попроси её один раз и объясни зачем.