VPN Reseller API

Публичный API для партнёров платформы: выдавайте VPN-подписки своим пользователям из своего сайта, бота или биллинга. Оплата с предоплаченного депозита по вашей закупочной цене, розницу назначаете вы. Ключ выпускается в кабинете партнёра: hexpartners.pro/api/vpn/app.

Каждый запрос несёт заголовок Authorization: Bearer <ключ>. Ключ один на аккаунт, показывается один раз при выпуске; потерянный перевыпускается в кабинете, старый перестаёт работать сразу. Ключ тратит ваши деньги: храните его в переменной окружения, не в коде и не в логах.

Лимит: 60 запросов в минуту на ключ. Превышение отвечает 429 с заголовком Retry-After.

Все суммы в долларах США и приходят парой: *_minor (целые центы, по ним считайте) и *_usd (строка «10.25», её показывайте). Цена тарифа это ваша закупка: себестоимость поставщика плюс наценка платформы. Курс рубля в ответах не участвует, цены не меняются от курса.

Депозит состоит из двух карманов: paid (внесено пополнениями, вывести нельзя) и earned (заработано на продажах в ботах платформы, выводится). Покупки через API списываются сначала с paid, потом с earned; spendable это их сумма. Нехватка средств отвечает 402 insufficient_balance до обращения к поставщику: подписка при этом не создаётся.

У каждой денежной операции есть custom_id, который придумываете вы (удобнее всего UUID). Повтор запроса с тем же custom_id и тем же телом возвращает результат первой попытки с idempotent_replay: true и денег не списывает. Тот же custom_id с другим телом отбивается 409 custom_id_conflict. Пока первая попытка выполняется, повтор получает 409 operation_in_progress: подождите секунду и повторите.

Правило одно: новая операция это новый custom_id, ретрай упавшего запроса это тот же custom_id. При 503 upstream_unavailable и таймауте повторяйте с тем же custom_id, двойного списания не будет.

external_user_id это идентификатор человека в вашей системе, один человек = один id. Подписок у него может быть несколько. Больше о пользователе знать не нужно: ни телефона, ни почты.

Если ваш пользователь есть в Telegram, приложите telegram_id и bot_id вашего бота из кабинета. Тогда он увидит подписку в мини-приложении бота и получит его уведомления. Один Telegram нельзя привязать к двум разным external_user_id: второй получит 409 external_user_conflict.

subscription_url это ссылка подписки для VPN-клиента, она не меняется при продлении и апгрейде. Статус подписки: active, frozen или expired. Истёкшая продлевается с текущего момента, действующая получает дни к концу срока. Замороженную сначала разморозьте: продлить её нельзя.

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

POST /subscriptions/{id}/renew-custom добавляет от 3 до 1095 дней. Цена пропорциональна тарифу: цена_тарифа / дней_в_тарифе × дней, округление вверх до цента. Трафик на лимитных серверах прибавляется в той же пропорции.

Укажите https-адрес в кабинете или через PUT /webhook. Секрет подписи выдаётся только в кабинете. Каждое событие приходит POST с JSON-телом и заголовками X-Signature: sha256=<hex>, X-Event, X-Delivery-Id. Подпись: HMAC-SHA256 от сырых байтов тела на вашем секрете, сравнивайте constant-time до разбора JSON.

Отвечайте 2xx быстро, работу уносите в фон. При ошибке доставка повторяется с растущим интервалом (1, 2, 4 … 512 минут, всего 10 попыток), потом уходит в dead, и вы получаете сообщение от бота платформы. Одно и то же событие может прийти повторно: дедупите по event_id. Незнакомое событие игнорируйте, список пополняется. Источник истины остаётся за GET /subscriptions/{id}.

POST /deposit выставляет счёт на сумму в центах, ответ содержит invoice_url. Комиссия провайдера прибавляется сверху, на депозит зачислится ровно указанная сумма. Одновременно открытых счетов не больше пяти. Зачисление приходит вебхуком deposit.credited и видно в GET /deposit/{custom_id}.

Все пути начинаются с /api/v1/vpn. Новые поля в ответах добавляются без смены версии: не ломайтесь на незнакомых ключах. Удаление или переименование поля выйдет только под /v2 с предупреждением в кабинете.