Partnerski API

Poslužiteljski API za partnere: izdajte ključ, čitajte konfiguraciju izloga i lokacije, stvarajte klijente, dodjeljujte planove i upravljajte poveznicama pretplate sa svoje stranice ili Telegram bota.

Partnerski API omogućuje da na CreateYourVPN-u izgradite vlastitu stranicu, vlastiti korisnički portal ili Telegram bota.

API obuhvaća klijente, pretplate, planove i konfiguraciju izloga. Infrastruktura, odnosno poslužitelji, čvorovi, paneli i SSH pristupni podaci, nije dio javnog ugovora.

Samo za integracije između poslužitelja. API ključ čuvajte na svom poslužitelju i ne dodajte ga u frontend kod. Zahtjevi sa zaglavljima preglednika odbijaju se s kodom 403 browser_forbidden.

Kako dobiti ključ

Nadzorna ploča → izbornik računa → „API”, kartica „Ključevi”.

Dajte ključu naziv (Telegram bot, prodajna stranica) i uključite samo ovlasti koje mu trebaju.

Kliknite „Izdaj ključ” i kopirajte cijelu vrijednost. Tajna se prikazuje samo jednom jer usluga čuva samo njezin hash.

Partner može imati najviše 5 aktivnih ključeva. Da biste zamijenili ključ, izdajte novi, ažurirajte integraciju, a zatim opozovite stari.

Autentifikacija

Ključ se šalje kao 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_… također radi, za slučaj kad zaglavlje Authorization zauzima proxy.

Ključ izgleda ovako: cyv_live_<key_id>_<secret>. Prva polovica (key_id) je javna: upravo nju vidite u nadzornoj ploči i možete je bez brige navesti podršci. Druga polovica je tajna.

Ovlasti (scopes)

Ovlast	Što dopušta
`config:read`	Čitanje konfiguracije izloga, planova, lokacija i `/me`.
`users:read`	Čitanje klijenata, njihovih pretplata i prometa.
`users:write`	Stvaranje klijenata, dodjela planova, resetiranje poveznica, brisanje klijenata.

config:read dovoljan je za integracije koje samo čitaju podatke izloga. users:read ili users:write dodajte samo kad integraciji trebaju odgovarajuće operacije s klijentima.

API ugovor i primjeri

Potpuni izvršivi ugovor nalazi se u javnoj Postman kolekciji. Sadrži sve endpointe, ovlasti, parametre, tijela zahtjeva, primjere odgovora i stabilne kodove pogrešaka. Kolekcija se generira iz backend ugovora i sadrži aktualne sheme zahtjeva i odgovora.

Otvori javnu Postman kolekciju

Pregledajte sve endpointe i kopirajte kolekciju u svoj radni prostor.

Ograničenja

Ograničenje se broji zasebno za svaki ključ i ne ovisi o IP adresi zahtjeva.

120 zahtjeva u minuti po ključu ukupno.
10 zahtjeva u minuti zasebno za GET /users.

Za GET /users vrijedi zasebno ograničenje jer svaki zahtjev učitava cijeli popis klijenata. Za redovite provjere koristite GET /users/{id} ili pretragu po externalId.

Preporučeni pristup. Spremite ID klijenta u CreateYourVPN-u iz odgovora na stvaranje i za daljnje zahtjeve koristite GET /users/{id}. Vlastiti identifikator klijenta možete povezati s njim preko externalId.

Idempotentnost

Tri operacije zahtijevaju zaglavlje Idempotency-Key: dodjela plana, resetiranje poveznice pretplate i brisanje klijenta.

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

Ponovljeni zahtjev s istim ključem unutar 24 sata vraća spremljeni odgovor umjesto ponovnog izvođenja operacije. Tako se promjene ne dupliciraju kad integracija ponovi zahtjev nakon isteka vremena.

Za svaki poslovni događaj (na primjer jedno plaćanje ili jednu radnju) izradite zaseban ključ i koristite ga u svim ponovnim pokušajima tog događaja.

Ako se prvi pokušaj još izvodi ili mu je ishod privremeno nepoznat, API vraća 409 conflict bez ponovnog izvođenja operacije. Prije ponovnog pokušaja provjerite trenutačno stanje klijenta.

Aktualne sheme zahtjeva i odgovora nalaze se u javnoj Postman kolekciji iznad.