Запуск продаж VPN через API за вечер

Ниже путь от пустого проекта до подписки, которая открывается в VPN-клиенте. Всё, что нужно от платформы, это ключ и депозит. Всё, что нужно от вас, это хранилище пользователей и обработчик одного HTTP-события.

Что должно быть на вашей стороне

Минимум три вещи, без них дальше идти бессмысленно:

• свой идентификатор пользователя. Один человек в вашей базе это один external_user_id, и он не должен меняться;
• свой идентификатор операции. Уникальная строка на каждую покупку и на каждое продление, вы генерируете её сами и сохраняете рядом с заказом;
• место, куда сложить ответ. Как минимум идентификатор подписки, ссылку на конфиг и дату окончания.

Шаг первый: ключ и депозит

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

Депозит пополняется там же в кабинете или запросом к API. Списания идут в долларах, и остаток видно в любой момент:

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

# {"balance_minor": 12050, "balance_usd": "120.50", "currency": "USD"}

Шаг второй: тарифы и цена

Список тарифов приходит одним запросом. У каждого есть идентификатор, срок в днях, число устройств и ваша закупочная цена. Периоды стандартные: 14, 30, 90, 180 и 365 дней. Розничную цену вы считаете сами поверх закупочной, платформа в это не вмешивается.

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

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

Шаг третий: первая подписка

Выдача это один POST. Деньги списываются с депозита сразу, в ответе приходит ссылка на конфиг и дата окончания.

curl -X POST https://api.relayhub.surf/api/v1/vpn/subscriptions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"custom_id": "order-1042",
       "external_user_id": "user-42",
       "plan_id": "550e8400-e29b-41d4-a716-446655440000"}'

# {"subscription": {"subscription_id": "...",
#                   "subscription_url": "https://.../sub/wnT9NRf0Zk6M",
#                   "days_left": 30, "end_date": "2026-10-02T12:00:00Z"},
#  "charged_usd": "4.50", "balance_after_usd": "116.00"}

Поле subscription_url это всё, что нужно пользователю. Ссылку открывает любой популярный клиент, ничего собирать вручную не требуется. Если у человека есть Telegram и вы указали его идентификатор вместе со своим ботом, подписка появится ещё и в мини-аппе бота.

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

Шаг четвёртый: продление

Продлить можно на срок тарифа или на выбранное число дней. Второй вариант нужен, когда у вас своя тарифная сетка: цена считается пропорционально сроку. Продление всегда идёт от текущей даты окончания, а не от даты запроса, поэтому продлевать заранее безопасно.

curl -X POST https://api.relayhub.surf/api/v1/vpn/subscriptions/$ID/renew \
  -H "Authorization: Bearer $KEY" \
  -d '{"custom_id": "renew-1042-2"}'

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

Шаг пятый: события вместо опроса

Опрашивать статус каждой подписки по расписанию можно, но незачем. Адрес для событий задаётся запросом или в кабинете, дальше платформа сама сообщает о выдаче, продлении, смене тарифа, заморозке и о том, что срок кончается через трое суток, через сутки и прямо сейчас. Каждое сообщение подписано, подпись лежит в заголовке.

На события удобно вешать письма и уведомления клиенту, а также автопродление, если оно у вас есть. Подробный разбор приёма событий и повторов есть в отдельной статье про вебхуки и продления.

Что проверить до первого клиента

• повторный запрос с тем же идентификатором операции не списывает деньги дважды;
• отказ по недостатку депозита виден у вас в логах и понятен покупателю;
• ссылка на конфиг действительно открывается в клиенте на телефоне;
• продление пришло событием и обновило дату у вас в базе;
• ключ не попал в репозиторий и не уехал во фронтенд.

Сколько это занимает

Первая выданная подписка занимает час или два, включая чтение документации. Дальше время уходит не на API, а на ваш продукт: витрину, оплату, письма и обработку отказов. Считайте это вечером на прототип и несколькими днями на то, что не стыдно показать покупателям.