Частые вопросы

Где взять `bot_id`? В кабинете: раздел «Ключ и вебхук», карточка «Ваши боты», UUID с кнопкой «Скопировать». Параметр нужен только вместе с telegram_id, чтобы подписка появилась в мини-приложении вашего бота. Без Telegram bot_id не нужен.

Как купить белые списки? Это докупка трафика, один метод для любой подписки: POST /subscriptions/{id}/traffic с gb. Подписке на срок gb из traffic_packs, «Навсегда» из lifetime.traffic_packs. Пошагово в сценарии «Докупить трафик (белые списки)».

Сколько трафика осталось? GET /subscriptions/{id} отдаёт traffic_limit_bytes (лимит) и traffic_used_bytes (расход). Лимит null значит, что ограничения нет. Когда израсходовано 80 %, приходит вебхук subscription.traffic_threshold.

Нужен ли пользователю Telegram? Нет. Достаточно вашего external_user_id: вы получаете subscription_url и отдаёте его сами.

Ответ на покупку потерялся. Что делать? Спросите GET /operations/{custom_id}: там статус и готовый ответ. Или просто повторите тот же запрос с тем же custom_id: деньги второй раз не спишутся, а в ответе будет idempotent_replay: true. Новый custom_id создаст вторую подписку.

Как не списать больше, чем показали покупателю? Передайте max_charge_minor с показанной ценой. Если цена выросла, придёт 409 max_charge_exceeded, а деньги останутся на депозите. Цену продления заранее даёт GET /subscriptions/{id}/renew-quote.

Как найти мой запрос в логах поддержки? У каждого ответа есть заголовок X-Request-ID, а у ошибки ещё и поле request_id. Назовите его поддержке.

Можно ли вызывать API из браузера или приложения? Нет. Ключ тратит ваши деньги, поэтому вызывайте API только со своего сервера.

Как продлить на произвольный срок? POST /subscriptions/{id}/renew-custom с days от 3 до 1095. Цена пропорциональна тарифу.

Как перевести пробный период на платный тариф? Апгрейдом: GET /subscriptions/{id}/upgrade-quote, затем POST /subscriptions/{id}/upgrade. Продлить или заморозить пробную нельзя.

Почему «Навсегда» нельзя продлить или заморозить? Она бессрочная. Продление, заморозка и апгрейд к ней не применяются, API отвечает 409 unsupported_for_product. Трафик и устройства работают так же, как у подписки на срок.

Ссылка утекла. Что делать? POST /subscriptions/{id}/rotate-link выдаст новую, старая перестанет работать. Уже подключённые устройства продолжат работать, чтобы закрыть доступ совсем, заморозьте подписку.

Деньги на депозите есть, а API отвечает 402. Покупки списываются с депозита по закупочной цене, а не по вашей розничной. Сверьтесь с GET /balance: нужна сумма spendable, в ответе 402 есть required_minor и balance_minor.

Можно ли проверить интеграцию без настоящих денег? Да: тестовый ключ из раздела «Песочница». Те же адреса и ответы, тестовый депозит, сбои по заказу заголовком X-Sandbox-Simulate, машина времени для окончания срока.

Как перевыпустить ключ, не уронив интеграцию? В кабинете при перевыпуске выберите перекрытие на 1, 24 или 72 часа: прежний ключ поработает рядом с новым, пока вы его меняете.

Как дать доступ подрядчику без права тратить депозит? Выпустите ключ только для чтения: он видит подписки, баланс и операции, но ничего не покупает.

Сколько запросов можно делать? 60 в минуту на ключ. Сколько осталось, видно в заголовке X-RateLimit-Remaining каждого ответа. При превышении ответ 429 с заголовком Retry-After.

Мой сервер лежал час. Как узнать, что я пропустил? GET /events?since=<когда упал>: события по порядку с телами, как у вебхука. Плюс автоматические повторы доставки ещё идут.

Как держать свою базу подписок актуальной? GET /subscriptions?updated_since=<прошлый заход> и листать по next_cursor: придут только изменившиеся.

Есть ли файлы для Postman или генерации клиента? Да: OpenAPI и коллекция Postman.