Быстрый старт

1. В кабинете, в разделе «Ключ и вебхук», выпустите ключ и пополните депозит.
2. GET /plans покажет тарифы и цены в USD.
3. POST /subscriptions с plan_uuid, вашим external_user_id и новым custom_id вернёт подписку, а в ней subscription_url.
4. Отдайте ссылку пользователю: он вставляет её в VPN-клиент (INCY, Happ, v2rayTun, Hiddify, Streisand).
5. Укажите адрес вебхука (в кабинете или PUT /webhook) и получайте subscription.expires_in_24h, чтобы вовремя предложить продление.

Первый запрос, чтобы проверить ключ:

curl https://api.relayhub.surf/api/v1/vpn/plans \
  -H "Authorization: Bearer $VPN_API_KEY"

Ответ 200 со списком plans значит, что ключ работает. 401 unauthorized значит, что ключ не тот или в заголовке опечатка. Все вызовы по шагам, с телами запросов и полями ответов, собраны в главе «Сценарии».

Готовые файлы для импорта: спецификация OpenAPI (Postman, Insomnia, Bruno, генераторы клиентов) и коллекция Postman с переменными base_url и api_key.

• Подписка на срок: обычная подписка на 14, 30, 90, 180 или 365 дней. Её можно продлевать, замораживать и менять тариф.
• «Навсегда»: бессрочная подписка. Она продаётся отдельным блоком lifetime в GET /plans, а её докупки идут через /addons.
• Лимитные серверы: серверы обхода белых списков. На обычных серверах трафик безлимитный, на лимитных действует лимит traffic_limit_bytes. «Купить белые списки» значит «докупить трафик».
• Депозит: ваш предоплаченный счёт. Покупки через API списываются с него по закупочной цене.
• `external_user_id`: идентификатор человека в вашей системе.
• `custom_id`: ключ операции, который придумываете вы. По нему повтор запроса не списывает деньги второй раз.
• `subscription_url`: ссылка, которую человек вставляет в VPN-клиент.
• `bot_id`: UUID вашего бота. Нужен только если пользователь должен увидеть подписку в мини-приложении бота.