Partnerské API

Serverové API pro partnery: vystavte klíč, čtěte konfiguraci obchodu a lokality, vytvářejte klienty, přidělujte tarify a spravujte odkazy na předplatné z vlastního webu nebo telegramového bota.

Partnerské API umožňuje postavit nad CreateYourVPN vlastní web, vlastní klientský portál nebo telegramového bota.

API pokrývá klienty, předplatná, tarify a konfiguraci obchodu. Infrastruktura, tedy servery, uzly, panely a přístupové údaje SSH, do veřejného kontraktu nepatří.

Jen pro integrace mezi servery. API klíč uchovávejte na svém serveru a nepřidávejte ho do kódu frontendu. Požadavky s hlavičkami prohlížeče se odmítají s kódem 403 browser_forbidden.

Jak získat klíč

Panel → nabídka účtu → „API“, karta „Klíče“.

Pojmenujte klíč (telegramový bot, prodejní stránka) a zapněte jen ta oprávnění, která potřebuje.

Klikněte na „Vystavit klíč“ a zkopírujte celou hodnotu. Tajná část se zobrazí jen jednou, protože služba uchovává pouze její hash.

Partner může mít až 5 aktivních klíčů. Klíč vyměníte tak, že vystavíte nový, aktualizujete integraci a pak starý zrušíte.

Ověřování

Klíč se předává jako 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 také, pro případ, kdy hlavičku Authorization obsadila proxy.

Klíč vypadá jako cyv_live_<key_id>_<secret>. První polovina (key_id) je veřejná: právě ta je vidět v panelu a můžete ji bez obav sdělit podpoře. Druhá polovina je tajná část.

Oprávnění (scopes)

Oprávnění	Co umožňuje
`config:read`	Číst konfiguraci obchodu, tarify, lokality a `/me`.
`users:read`	Číst klienty, jejich předplatná a provoz.
`users:write`	Vytvářet klienty, přidělovat tarify, resetovat odkazy, mazat klienty.

config:read stačí integracím, které jen čtou data obchodu. users:read nebo users:write přidávejte jen tehdy, když integrace potřebuje odpovídající operace s klienty.

Úplný spustitelný kontrakt je ve veřejné kolekci Postman. Obsahuje všechny endpointy, oprávnění, parametry, těla požadavků, příklady odpovědí a stabilní chybové kódy. Kolekce se generuje z kontraktu backendu a obsahuje aktuální schémata požadavků a odpovědí.

Otevřít veřejnou kolekci Postman

Prohlédněte si všechny endpointy a zkopírujte kolekci do svého pracovního prostoru.

Limity

Limit se počítá zvlášť pro každý klíč a nezávisí na IP adrese požadavku.

120 požadavků za minutu na klíč celkem.
10 požadavků za minutu zvlášť na GET /users.

Pro GET /users platí zvláštní limit, protože každý požadavek načítá úplný seznam klientů. Pro pravidelné kontroly používejte GET /users/{id} nebo vyhledávání podle externalId.

Doporučený postup. Uložte si ID klienta CreateYourVPN z odpovědi na vytvoření a pro další požadavky používejte GET /users/{id}. Vlastní identifikátor klienta s ním můžete propojit přes externalId.

Idempotence

Tři operace vyžadují hlavičku Idempotency-Key: přidělení tarifu, reset odkazu na předplatné a smazání klienta.

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

Opakovaný požadavek se stejným klíčem během 24 hodin vrátí uloženou odpověď místo opětovného provedení operace. Tím se zabrání zdvojeným změnám, když integrace požadavek po vypršení časového limitu zopakuje.

Pro každou obchodní událost (například jednu platbu nebo jednu akci) vytvořte samostatný klíč a použijte ho při všech opakováních této události.

Pokud první pokus ještě probíhá nebo je jeho výsledek dočasně neznámý, API vrátí 409 conflict a operaci znovu neprovede. Než požadavek zopakujete, zkontrolujte aktuální stav klienta.

Aktuální schémata požadavků a odpovědí najdete ve veřejné kolekci Postman výše.