Partnerské API

Serverové API pre partnerov: vystavte kľúč, čítajte konfiguráciu vitríny a lokality, vytvárajte klientov, prideľujte tarify a spravujte odkazy na predplatné z vlastného webu alebo telegramového bota.

Partnerské API umožňuje postaviť nad CreateYourVPN vlastný web, vlastnú zákaznícku zónu alebo telegramového bota.

API pokrýva klientov, predplatné, tarify a konfiguráciu vitríny. Infraštruktúra, teda servery, uzly, panely a prístupové údaje SSH, do verejného kontraktu nepatrí.

Len pre integrácie medzi servermi. API kľúč uchovávajte na svojom serveri a nepridávajte ho do kódu frontendu. Požiadavky s hlavičkami prehliadača sa odmietajú s kódom 403 browser_forbidden.

Ako získať kľúč

Panel → ponuka účtu → „API“, karta „Kľúče“.

Pomenujte kľúč (telegramový bot, landing) a zapnite len tie oprávnenia, ktoré potrebuje.

Kliknite na „Vystaviť kľúč“ a skopírujte celú hodnotu. Tajná časť sa zobrazí len raz, pretože služba uchováva iba jej hash.

Partner môže mať najviac 5 aktívnych kľúčov. Kľúč vymeníte tak, že vystavíte nový, aktualizujete integráciu a potom starý zrušíte.

Overovanie

Kľúč sa odovzdáva ako bearer token:

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

X-API-Key: cyv_live_… funguje tiež, pre prípad, keď hlavičku Authorization obsadila proxy.

Kľúč vyzerá ako cyv_live_<key_id>_<secret>. Prvá polovica (key_id) je verejná: práve tú vidno v paneli a môžete ju bez obáv povedať podpore. Druhá polovica je tajná časť.

Oprávnenia (scopes)

Oprávnenie	Čo umožňuje
`config:read`	Čítať konfiguráciu vitríny, tarify, lokality a `/me`.
`users:read`	Čítať klientov, ich predplatné a prevádzku.
`users:write`	Vytvárať klientov, prideľovať tarify, resetovať odkazy, mazať klientov.

config:read stačí integráciám, ktoré len čítajú údaje vitríny. users:read alebo users:write pridávajte len vtedy, keď integrácia potrebuje zodpovedajúce operácie s klientmi.

Úplný spustiteľný kontrakt je vo verejnej kolekcii Postman. Obsahuje všetky endpointy, oprávnenia, parametre, telá požiadaviek, príklady odpovedí a stabilné chybové kódy. Kolekcia sa generuje z backend kontraktu a obsahuje aktuálne schémy požiadaviek a odpovedí.

Otvoriť verejnú kolekciu Postman

Prezrite si všetky endpointy a skopírujte kolekciu do svojho pracovného priestoru.

Limity

Limit sa počíta osobitne pre každý kľúč a nezávisí od IP adresy požiadavky.

120 požiadaviek za minútu na kľúč celkovo.
10 požiadaviek za minútu osobitne na GET /users.

Pre GET /users platí osobitný limit, pretože každá požiadavka načítava úplný zoznam klientov. Na pravidelné kontroly používajte GET /users/{id} alebo vyhľadávanie podľa externalId.

Odporúčaný postup. Uložte si ID klienta CreateYourVPN z odpovede na vytvorenie a na ďalšie požiadavky používajte GET /users/{id}. Vlastný identifikátor klienta s ním môžete prepojiť cez externalId.

Idempotencia

Tri operácie vyžadujú hlavičku Idempotency-Key: pridelenie tarifu, reset odkazu na predplatné a odstránenie klienta.

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

Opakovaná požiadavka s rovnakým kľúčom počas 24 hodín vráti uloženú odpoveď namiesto opätovného vykonania operácie. Tým sa zabráni zdvojeným zmenám, keď integrácia po vypršaní časového limitu požiadavku zopakuje.

Pre každú obchodnú udalosť (napríklad jednu platbu alebo jednu akciu) vytvorte samostatný kľúč a použite ho pri všetkých opakovaniach tejto udalosti.

Ak prvý pokus ešte prebieha alebo je jeho výsledok dočasne neznámy, API vráti 409 conflict a operáciu znova nevykoná. Skôr než požiadavku zopakujete, skontrolujte aktuálny stav klienta.

Aktuálne schémy požiadaviek a odpovedí nájdete vo verejnej kolekcii Postman vyššie.