API и ключи доступа

API нужен, когда к вашим данным должен ходить не человек, а программа: ИИ-ассистент, скрипт выгрузки, свой дашборд или таблица, которая сама подтягивает цифры. Ключ выдаётся в боте: «🧰 Инструменты» → «🔌 API и ИИ-доступ». Раздел есть и в Telegram, и в MAX.

По ключу видно ровно то же, что вам в боте: ваши источники и источники вашей связки аккаунтов. Чужие данные ключ не открывает, тариф не повышает, деньги не тратит.

Два вида ключей

Ключ	Что можно
Только чтение	статистика, источники, метки, отсев фильтров, симулятор трафика
Чтение и запись	то же плюс создание меток-ссылок

Разница не в вежливой просьбе: изменяющий вызов по ключу на чтение не проходит, а ИИ-ассистенту такой инструмент даже не показывается в списке. Для ассистента берите чтение, если не собираетесь поручать ему заводить метки.

Ключ работает, пока активен тариф

Тариф проверяется на каждом запросе, а не в момент выдачи. Подписка кончилась — API отвечает отказом с кодом 402, ассистент получает то же самое. Отзывать ключ при этом не нужно: оплатите тариф, и он заработает снова тем же ключом.

На тестовом тарифе программный доступ закрыт — как и весь раздел «Инструменты».

Что умеет

Операция	Что делает
ping	проверить ключ и связь
list_projects	список проектов
list_sources	список источников трафика
list_labels	метки источника
stats_summary	переходы, подписки, отписки, продажи за период
stats_labels	разбивка по меткам: какая реклама привела людей
filter_hits	сколько трафика и за что срезали фильтры
simulate	прогон посетителя через фильтры
create_label	создать метку-ссылку (нужен ключ с записью)

Актуальный список всегда отдаёт сам сервис по адресу https://nexus-tag.ru/api/v1 — он открыт без ключа, это документация, а не данные.

Как обращаться

GET https://nexus-tag.ru/api/v1/stats_summary?source_id=12&days=7
Authorization: Bearer nxt_ваш_ключ

Ключ передаётся заголовком Authorization: Bearer … (или X-Api-Key, если так удобнее клиенту) — но не в адресе: адреса попадают в логи и в историю браузера. Ответ всегда JSON.

POST https://nexus-tag.ru/api/v1/create_label
Authorization: Bearer nxt_ваш_ключ
Content-Type: application/json

{"source_id": 12, "title": "Реклама ВК", "utm_source": "vk"}

Созданная так метка ничем не отличается от заведённой кнопкой: она сразу видна в боте, а для закрытого канала ей так же выпускается своя invite-ссылка — иначе подписки по ней не привязались бы к метке.

Коды ответов

Код	Что случилось
200	всё хорошо
400	плохой аргумент — в ответе написано какой
401	ключа нет, он неверен или отозван
402	подписка неактивна
403	операция меняет данные, а ключ только на чтение
404	нет такой операции
429	слишком часто

Ограничения частоты

120 запросов в минуту на ключ. У двух операций свой, более низкий потолок, и он не про экономию:

• simulate — 10 в минуту: прогон определяет адрес через внешний сервис с общей на всех клиентов квотой;
• create_label — 20 в минуту: каждая метка закрытого канала — обращение к Telegram, а бот один на всех.

Как обращаться с ключом

• Не публикуйте и не вставляйте в переписку — ключ равен доступу к вашим данным.
• Давайте отдельный ключ каждой программе и называйте понятно: через полгода будет ясно, что отзывать.
• Подрядчику — только ключ на чтение.
• Сомневаетесь, что ключ не утёк, — отзовите. Отзыв действует сразу, выдать новый ничего не стоит.