Партнёрский API
Серверный API для партнёров: выпуск ключа, чтение конфигурации витрины и локаций, создание клиентов, выдача тарифов и управление подписочными ссылками из своего сайта или телеграм-бота.
Партнёрский API — это минимальный набор ручек, которого хватает, чтобы собрать свой сайт, свой личный кабинет или телеграм-бота поверх CreateYourVPN, не имея доступа ни к чему инфраструктурному.
Он говорит на одном языке: партнёр → клиенты → подписки → тарифы. Серверы, ноды, панели и SSH — наша забота, и в ответах их нет.
Ключ работает только с сервера на сервер. Запрос, похожий на браузерный, отклоняется с 403 browser_forbidden. Это не формальность: ключ, положенный во фронтенд, уже у ваших посетителей — он лежит внутри вашего JavaScript-бандла. Держите его на своём сервере.
Как получить ключ
Панель → меню аккаунта → Настройки → API и интеграции.
Дайте ключу название (телеграм-бот, лендинг) и включите только те права, которые ему нужны.
Нажмите Выпустить ключ и скопируйте строку целиком. Она показывается один раз — у нас лежит только хеш, и показать её снова мы физически не можем.
До 5 активных ключей на партнёра. Ротация делается так: выпустить новый, перевести интеграцию, отозвать старый.
Аутентификация
Ключ передаётся как bearer-токен:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"X-API-Key: cyv_live_… тоже работает — на случай, когда Authorization занят прокси.
Ключ выглядит как cyv_live_<key_id>_<secret>. Первая половина (key_id) публична: именно её видно в панели, и её безопасно назвать поддержке. Вторая — секрет.
Права (scopes)
| Право | Что разрешает |
|---|---|
config:read | Читать конфигурацию витрины, тарифы, локации и /me. |
users:read | Читать клиентов, их подписки и трафик. |
users:write | Заводить клиентов, выдавать тарифы, сбрасывать ссылки, удалять клиентов. |
Ключ без нужного права получает 403 forbidden_scope. Дайте лендингу только config:read — тогда им нельзя тронуть ни одного клиента.
Контракт API и примеры
Полный исполняемый контракт находится в публичной коллекции Postman. В ней перечислены все эндпоинты, права, параметры, тела запросов, примеры ответов и стабильные коды ошибок. Коллекция генерируется из backend-контракта, поэтому Academy не хранит вторую ручную копию, которая со временем разъедется с кодом.
Лимиты
Лимит считается на ключ, а не на IP: ваш бот ходит с одного адреса, и IP-лимит либо не поймал бы его вовсе, либо задел бы соседей за тем же NAT.
- 120 запросов в минуту на ключ в целом.
- 10 запросов в минуту отдельно на
GET /users.
Второй лимит не выдуман. GET /users — самая дорогая ручка: она читает полный список клиентов из вашей панели на каждый вызов. Опрос в цикле тормозит не нас, а ваш сервис.
Не опрашивайте список. Обращайтесь к клиенту адресно — GET /users/{id}. Свяжите свой идентификатор с нашим через externalId при создании клиента, и список вам не понадобится вовсе.
Идемпотентность
Три операции требуют заголовок Idempotency-Key: выдача тарифа, сброс подписочной ссылки и удаление клиента.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Повтор с тем же ключом 24 часа переигрывает сохранённый ответ, а не выполняет операцию заново. Без этого бот, ретраящий по таймауту, продлевает одну и ту же подписку дважды за один платёж — и узнаёте вы об этом по балансу, а не по ошибке.
Ключ заводится на бизнес-событие (один платёж, одно нажатие), а не на HTTP-попытку: ретраи обязаны переиспользовать тот же ключ.
Если ретрай приходит, пока первая попытка ещё выполняется — или пока её исход по-настоящему неизвестен, потому что наш процесс умер между применением изменения и записью результата, — вы получите 409 conflict, а не второе выполнение. Посмотрите состояние клиента и решите сами: отказать дешевле, чем списать дважды.
Схемы запросов и ответов всегда сверяйте с публичной коллекцией Postman выше — это единственный источник истины.
Восстановление из копии
Два способа вернуть пользователей: восстановление в один клик прямо в панели (идемпотентный повторный импорт) или ручное восстановление в «чистый» Marzban, ведь файл — это нативный формат пользователей Marzban.
Аварийный доступ
Запасной способ подключиться, когда сеть использует белые списки и основное соединение заблокировано — создайте видеозвонок, передайте ссылку на него из кабинета или письмом и получите готовое подключение.