Partner API
Szerverek közötti API partnereknek: állíts ki kulcsot, olvasd a kirakat konfigurációját és a helyszíneket, hozz létre ügyfeleket, adj ki csomagokat, és kezeld az előfizetési linkeket saját webhelyedről vagy Telegram-botodból.
A Partner API-val saját webhelyet, saját ügyfélportált vagy Telegram-botot építhetsz a CreateYourVPN-re.
Az API az ügyfeleket, az előfizetéseket, a csomagokat és a kirakat konfigurációját fedi le. Az infrastruktúra (szerverek, csomópontok, panelek és SSH-hozzáférési adatok) nem része a nyilvános szerződésnek.
Csak szerverek közötti integrációkhoz. Az API-kulcsot a saját szervereden tárold, és ne tedd bele a frontend kódjába. A böngészőfejlécekkel érkező kéréseket a rendszer 403 browser_forbidden kóddal elutasítja.
Hogyan kapsz kulcsot
Panel → fiókmenü → „API”, „Kulcsok” lap.
Adj nevet a kulcsnak (Telegram-bot, nyitóoldal), és csak azokat a jogosultságokat kapcsold be, amelyekre szüksége van.
Kattints a „Kulcs kiállítása” gombra, és másold ki a teljes értéket. A titok csak egyszer jelenik meg, mert a szolgáltatás csak a hash-ét tárolja.
Egy partnernek legfeljebb 5 aktív kulcsa lehet. A kulcs cseréjéhez állíts ki egy újat, frissítsd az integrációt, majd vond vissza a régit.
Hitelesítés
A kulcsot bearer tokenként kell átadni:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"Az X-API-Key: cyv_live_… is működik, arra az esetre, ha az Authorization fejlécet egy proxy foglalja.
A kulcs így néz ki: cyv_live_<key_id>_<secret>. Az első fele (key_id) nyilvános: ez látszik a panelen, és nyugodtan megadhatod az ügyfélszolgálatnak. A második fele a titok.
Jogosultságok (scopes)
| Jogosultság | Mit enged |
|---|---|
config:read | A kirakat konfigurációjának, a csomagoknak, a helyszíneknek és a /me adatainak olvasása. |
users:read | Az ügyfelek, az előfizetéseik és a forgalmuk olvasása. |
users:write | Ügyfelek létrehozása, csomagok kiadása, linkek visszaállítása, ügyfelek törlése. |
A config:read elég azokhoz az integrációkhoz, amelyek csak a kirakat adatait olvassák. A users:read vagy a users:write jogosultságot csak akkor add hozzá, ha az integrációnak szüksége van a megfelelő ügyfélműveletekre.
API-szerződés és példák
A teljes, futtatható szerződés a nyilvános Postman-gyűjteményben található. Benne van minden endpoint, jogosultság, paraméter, kéréstörzs, válaszpélda és állandó hibakód. A gyűjtemény a backend szerződéséből készül, és a kérések és válaszok aktuális sémáit tartalmazza.
Korlátok
A korlát minden kulcsra külön számít, és nem függ a kérés IP-címétől.
- Percenként 120 kérés kulcsonként összesen.
- Percenként 10 kérés külön a
GET /usershívásra.
A GET /users külön korlátot kapott, mert minden ilyen kérés a teljes ügyféllistát tölti be. Rendszeres lekérdezésekhez a GET /users/{id} hívást vagy az externalId szerinti keresést használd.
Ajánlott megoldás. Mentsd el az ügyfél CreateYourVPN-azonosítóját a létrehozáskor kapott válaszból, és a további lekérdezésekhez használd a GET /users/{id} hívást. A saját ügyfélazonosítódat az externalId mezővel kötheted hozzá.
Idempotencia
Három művelethez kell Idempotency-Key fejléc: csomag kiadása, előfizetési link visszaállítása és ügyfél törlése.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Ha 24 órán belül ugyanazzal a kulccsal megismétled a kérést, a rendszer a tárolt választ adja vissza, és nem hajtja végre újra a műveletet. Így nem duplázódnak a módosítások, amikor az integráció időtúllépés után újrapróbálkozik.
Minden üzleti eseményhez (például egy fizetéshez vagy egy művelethez) hozz létre külön kulcsot, és az esemény minden ismétlésénél azt használd.
Ha az első próbálkozás még fut, vagy az eredménye átmenetileg ismeretlen, az API 409 conflict választ ad, és nem hajtja végre újra a műveletet. Mielőtt újrapróbálkozol, ellenőrizd az ügyfél aktuális állapotát.
A kérések és válaszok aktuális sémái a fenti nyilvános Postman-gyűjteményben találhatók.
Visszaállítás mentésből
Két módja annak, hogy visszahozd a felhasználóidat: az egykattintásos vezérlőpulti visszaállítás, amely idempotens módon importálja őket újra, vagy a kézi visszaállítás egy üres Marzbanba, mivel a fájl natív Marzban felhasználóformátumú.
Vészhelyzeti hozzáférés
Tartalék csatlakozási mód arra az esetre, amikor a hálózat engedélyezési listát használ, és a fő kapcsolat blokkolva van: hozzon létre egy videohívást, adja át a linkjét a fiókjából vagy e-mailben, és kész kapcsolatot kap.