Партнерський API

Серверний API для партнерів: випуск ключа, читання конфігурації вітрини й локацій, створення клієнтів, видача тарифів і керування посиланнями підписки зі свого сайту або телеграм-бота.

Партнерський API дає змогу створити власний сайт, особистий кабінет або телеграм-бота поверх CreateYourVPN.

API охоплює клієнтів, підписки, тарифи й конфігурацію вітрини. Сервери, вузли, панелі та SSH-дані перебувають поза межами публічного контракту.

Лише для інтеграцій між серверами. Зберігайте API-ключ на своєму сервері й не додавайте його у frontend-код. Запити з браузерними заголовками відхиляються з кодом 403 browser_forbidden.

Як отримати ключ

Панель → меню акаунта → «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`	Створювати клієнтів, видавати тарифи, скидати посилання, видаляти клієнтів.

config:read достатньо для інтеграцій, які лише читають дані вітрини. Додавайте users:read або users:write тільки тоді, коли інтеграції потрібні відповідні операції з клієнтами.

Повний виконуваний контракт міститься в публічній колекції Postman. У ній перелічено всі ендпоїнти, права, параметри, тіла запитів, приклади відповідей і стабільні коди помилок. Колекція генерується з backend-контракту й містить актуальні схеми запитів і відповідей.

Відкрити публічну колекцію Postman

Перегляньте всі ендпоїнти й скопіюйте колекцію у свій робочий простір.

Ліміти

Ліміт рахується окремо для кожного ключа й не залежить від IP-адреси запиту.

120 запитів на хвилину на ключ загалом.
10 запитів на хвилину окремо на GET /users.

Для GET /users діє окремий ліміт, бо кожен запит завантажує повний список клієнтів. Для регулярних перевірок використовуйте GET /users/{id} або пошук за externalId.

Рекомендована схема. Збережіть ID клієнта CreateYourVPN із відповіді на створення й використовуйте 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 годин повертає збережену відповідь замість повторного виконання операції. Це запобігає дублюванню змін, коли інтеграція повторює запит після тайм-ауту.

Створюйте окремий ключ для кожної бізнес-події (наприклад, платежу чи дії) і використовуйте його в усіх повторах цієї події.

Якщо перша спроба ще виконується або її результат тимчасово невідомий, API повертає 409 conflict без повторного виконання операції. Перш ніж повторювати запит, перевірте поточний стан клієнта.

Актуальні схеми запитів і відповідей містяться в публічній колекції Postman вище.