ShareSub API.
Ваш VPN-пул, подписки и проверки — через единый API.
Доступ выдаёт администратор в основном Telegram-боте ShareSub.
01 / Начните с ключа
Откройте ShareSub API в основном боте и скопируйте личный ключ. Базовый адрес: https://api.sharesub.ru/v1. Для каждого метода необходим заголовок Authorization: Bearer YOUR_API_KEY. Передавайте JSON с Content-Type: application/json.
curl 'https://api.sharesub.ru/v1/me' \
-H 'Authorization: Bearer YOUR_API_KEY'Не публикуйте ключ и не передавайте его в URL. Перевыпуск в боте немедленно отключает старый ключ. Вы получаете доступ только к своим подпискам и устройствам. API не доступен в ресейл-ботах.
02 / Добавьте подписки
curl 'https://api.sharesub.ru/v1/subscriptions/import' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"subscriptions":[
{"url":"https://provider.example/sub/token","name":"Мой VPN"},
{"url":"https://another.example/sub/token","name":"Второй VPN"}
]}'Ответ 202 Accepted означает постановку в очередь, не успешную проверку. Импорты разных пользователей и их серверы проверяются последовательно одним обработчиком. Поддерживаются те же конфигурации и правила, что в боте. Повторный домен провайдера не создаёт дубликат. Если ни один сервер не работает, подписка отправляется в архив, в активный пул не попадает и сатоши не начисляются.
{
"success": true,
"data": {
"batchId": "UUID", "status": "QUEUED", "accepted": 2,
"pollUrl": "https://api.sharesub.ru/v1/imports/UUID",
"jobs": [{"id":"JOB_UUID","status":"QUEUED"}]
},
"meta": {"requestId":"REQUEST_UUID","timestamp":"ISO-8601","version":"1"}
}Опрашивайте GET /imports/{batchId} или GET /jobs/{jobId} раз в 3–5 секунд. Стадии: QUEUED → FETCHING → CHECKING → COMPLETED / FAILED / CANCELLED. Поле progress содержит total, checked, working, failed и percent. Ping и результат каждого сервера: GET /subscriptions/{id}/hosts, поле check.
Лимит — 12 именно подписок за скользящие 60 секунд, а не 12 HTTP-запросов. Пакет из 12 расходует весь минутный лимит. Общий лимит: 120 запросов/мин; очередь: до 48 незавершённых заданий на пользователя и 240 на сервис. Повторные проверки хостов: до 12/мин. Ключи одного пользователя разделяют одни лимиты; перевыпуск не обнуляет их. Не повторяйте успешно принятый пакет: храните batchId и опрашивайте статус.
03 / Справочник методов
К каждому пути добавьте базовый адрес https://api.sharesub.ru/v1. Идентификаторы источников берите из /subscriptions, серверов — из /subscriptions/{id}/hosts. Числа байтов возвращаются строками, даты — ISO 8601 UTC.
| Метод | Путь | Что делает |
|---|---|---|
| GET | /me | Профиль, баланс сатоши и лимиты |
| GET / PATCH | /settings | Настройки: isAnonymous, notificationsEnabled, showHostExpiry, groupServers (boolean) |
| GET | /subscription | Персональная ссылка подключения |
| POST | /subscription/rotate | Перевыпустить ссылку; старая ссылка и устройства отключаются |
| POST | /subscription/share | Временная ссылка: 1 час, раз в сутки |
| GET | /devices | Список своих устройств |
| DELETE | /devices/{key} | Удалить своё устройство по deviceKey |
| POST | /subscriptions/import | Пакетный импорт, 1–12 подписок. Ответ 202 и batchId |
| GET | /imports/{batchId} | Прогресс всех подписок пакета; история 30 дней |
| GET | /jobs/{jobId} | Прогресс отдельного импорта, проверки или синхронизации |
| GET | /subscriptions?scope=active&page=1&limit=20 | Свои подписки. scope: active или deleted; limit: 1–50 |
| GET | /subscriptions/{id} | Статус, срок, трафик провайдера и число хостов |
| GET | /subscriptions/{id}/hosts?page=1&limit=20 | Серверы, последние проверки, ping (latencyMs) и защита |
| PATCH | /subscriptions/{id}/name | Переименовать: {"name":"Мой VPN"}, до 32 символов |
| PATCH | /subscriptions/{id}/url | Заменить ссылку через очередь: {"url":"https://provider.example/sub/token"}; затем запустите sync |
| DELETE | /subscriptions/{id} | Переместить в архив на 3 дня |
| DELETE | /subscriptions/{id}/purge | Навсегда удалить свою архивную подписку |
| POST | /subscriptions/{id}/sync | Синхронизация через очередь; не чаще раза в минуту на пользователя |
| POST | /subscriptions/{id}/restore | Восстановить из архива только после успешной проверки |
| POST | /subscriptions/{id}/device | Обновить идентификатор устройства провайдера; раз в минуту |
| PATCH | /subscriptions/{id}/hosts/{hostId} | Выбрать/исключить сервер: {"selected":true} |
| PATCH | /subscriptions/{id}/hosts | Выбрать/исключить все доступные серверы: {"selected":true} |
| POST | /subscriptions/{id}/hosts/{hostId}/check | Поставить повторную проверку сервера в последовательную очередь |
| PATCH | /subscriptions/{id}/protection | ShareSub Nodes: {"enabled":true}; БС-хосты остаются без защиты |
| GET | /shop | Каталог магазина |
| GET | /shop/purchases | Свои покупки |
| POST | /shop/{productId}/buy | Купить товар за сатоши |
04 / Понятные ответы
{
"success": false,
"error": {"code":"RATE_LIMITED","message":"Лимит исчерпан.","retryAfterSeconds":42},
"meta": {"requestId":"REQUEST_UUID","timestamp":"ISO-8601","version":"1"}
}400 — некорректные параметры; 401 — ключ не передан, неверен или отозван; 403 — аккаунт неактивен; 404 — ресурс не найден или принадлежит другому пользователю; 409 — конфликт состояния; 429 — лимит, учитывайте Retry-After; 500 / 503 — временная недоступность. Коды заданий: PROVIDER_ALREADY_EXISTS, NO_SUPPORTED_HOSTS, NO_WORKING_HOSTS, SUBSCRIPTION_EXPIRED, TRAFFIC_EXHAUSTED, ACCESS_REVOKED, IMPORT_FAILED.