API partnerskie

Serwerowe API dla partnerów: wystaw klucz, odczytuj konfigurację witryny i lokalizacje, twórz klientów, przyznawaj plany i zarządzaj linkami subskrypcji z własnej strony lub bota w Telegramie.

API partnerskie pozwala zbudować na bazie CreateYourVPN własną stronę, własny panel klienta albo bota w Telegramie.

API obejmuje klientów, subskrypcje, plany i konfigurację witryny. Infrastruktura, czyli serwery, węzły, panele i dane dostępowe SSH, jest poza publicznym kontraktem.

Tylko do integracji między serwerami. Przechowuj klucz API na swoim serwerze i nie umieszczaj go w kodzie frontendu. Żądania z nagłówkami przeglądarki są odrzucane z kodem 403 browser_forbidden.

Jak uzyskać klucz

Panel → menu konta → „API”, zakładka „Klucze”.

Nadaj kluczowi nazwę (bot Telegram, strona sprzedażowa) i włącz tylko te uprawnienia, których potrzebuje.

Kliknij „Wystaw klucz” i skopiuj całą wartość. Sekret jest pokazywany tylko raz, bo usługa przechowuje wyłącznie jego hash.

Partner może mieć do 5 aktywnych kluczy. Aby wymienić klucz, wystaw nowy, zaktualizuj integrację, a potem unieważnij stary.

Uwierzytelnianie

Klucz przekazuje się jako token bearer:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… też działa: na wypadek, gdy nagłówek Authorization zajmuje proxy.

Klucz wygląda tak: cyv_live_<key_id>_<secret>. Pierwsza połowa (key_id) jest publiczna: właśnie ją widać w panelu i można ją bezpiecznie podać wsparciu. Druga połowa to sekret.

Uprawnienia (scopes)

Uprawnienie	Na co pozwala
`config:read`	Odczyt konfiguracji witryny, planów, lokalizacji i `/me`.
`users:read`	Odczyt klientów, ich subskrypcji i transferu.
`users:write`	Tworzenie klientów, przyznawanie planów, resetowanie linków, usuwanie klientów.

config:read wystarczy integracjom, które tylko odczytują dane witryny. Dodawaj users:read lub users:write tylko wtedy, gdy integracja potrzebuje odpowiednich operacji na klientach.

Kontrakt API i przykłady

Pełny, wykonywalny kontrakt znajduje się w publicznej kolekcji Postman. Zawiera wszystkie endpointy, uprawnienia, parametry, treści żądań, przykłady odpowiedzi i stabilne kody błędów. Kolekcja jest generowana z kontraktu backendu i zawiera aktualne schematy żądań i odpowiedzi.

Otwórz publiczną kolekcję Postman

Przejrzyj wszystkie endpointy i skopiuj kolekcję do swojego obszaru roboczego.

Limity

Limit jest liczony osobno dla każdego klucza i nie zależy od adresu IP żądania.

120 żądań na minutę na klucz łącznie.
10 żądań na minutę osobno dla GET /users.

GET /users ma osobny limit, bo każde żądanie wczytuje pełną listę klientów. Do regularnych sprawdzeń używaj GET /users/{id} albo wyszukiwania po externalId.

Zalecany schemat. Zapisz identyfikator klienta CreateYourVPN z odpowiedzi na utworzenie i używaj GET /users/{id} w kolejnych żądaniach. Własny identyfikator klienta możesz powiązać z nim przez externalId.

Idempotentność

Trzy operacje wymagają nagłówka Idempotency-Key: przyznanie planu, reset linku subskrypcji i usunięcie klienta.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

Powtórzenie żądania z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź zamiast ponownego wykonania operacji. Dzięki temu zmiany nie dublują się, gdy integracja ponawia żądanie po przekroczeniu czasu oczekiwania.

Twórz osobny klucz dla każdego zdarzenia biznesowego (na przykład płatności lub akcji) i używaj go przy wszystkich ponowieniach tego zdarzenia.

Jeśli pierwsza próba wciąż trwa albo jej wynik jest chwilowo nieznany, API zwraca 409 conflict bez ponownego wykonania operacji. Zanim ponowisz żądanie, sprawdź bieżący stan klienta.

Aktualne schematy żądań i odpowiedzi znajdziesz w publicznej kolekcji Postman powyżej.