API pentru parteneri
API server-la-server pentru parteneri: emite o cheie, citește configurația vitrinei și locațiile, creează clienți, acordă planuri și gestionează linkurile de abonament din propriul site sau bot de Telegram.
API-ul pentru parteneri îți permite să construiești propriul site, propriul panou sau un bot de Telegram peste CreateYourVPN.
API-ul acoperă clienții, abonamentele, planurile și configurația vitrinei. Infrastructura, cum ar fi serverele, nodurile, panourile și datele de acces SSH, rămâne în afara contractului public.
Doar server-la-server. Păstrează cheile API pe serverul tău și nu le include în codul frontend. Cererile cu antete de browser sunt respinse cu 403 browser_forbidden.
Obținerea unei chei
Deschide panoul → meniul contului → „API”, fila „Chei”.
Dă-i cheii un nume (bot Telegram, pagină de destinație) și alege doar permisiunile de care are nevoie.
Apasă „Emite cheia” și copiază valoarea completă. Secretul este afișat o singură dată, pentru că se păstrează doar hash-ul lui.
Fiecare partener poate avea până la 5 chei active. Ca să schimbi o cheie, emite una nouă, actualizează integrarea și apoi revoc-o pe cea veche.
Autentificare
Trimite cheia ca token bearer:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"Funcționează și X-API-Key: cyv_live_…, pentru clienții la care Authorization este ocupat de un proxy.
O cheie arată ca cyv_live_<key_id>_<secret>. Prima jumătate (key_id) este publică: pe ea o vezi în panou și o poți comunica fără grijă echipei de suport. A doua jumătate este secretul.
Permisiuni (scopes)
| Permisiune | Ce permite |
|---|---|
config:read | Citirea configurației vitrinei, a planurilor, a locațiilor și a /me. |
users:read | Citirea clienților, a abonamentelor lor și a traficului. |
users:write | Crearea clienților, acordarea planurilor, resetarea linkurilor de abonament, ștergerea clienților. |
config:read este suficient pentru integrările care doar citesc datele vitrinei. Adaugă users:read sau users:write doar când integrarea are nevoie de operațiunile corespunzătoare cu clienții.
Contractul API și exemple
Contractul complet și executabil se află în colecția publică Postman. Ea conține toate endpointurile, permisiunile, parametrii, corpurile cererilor, exemplele de răspuns și codurile de eroare stabile. Colecția este generată din contractul backend și este sursa actuală pentru schemele de cerere și răspuns.
Limite de cereri
Limitele se numără separat pentru fiecare cheie, independent de adresa IP a cererii.
- 120 de cereri/minut per cheie în total.
- 10 cereri/minut separat pentru
GET /users.
GET /users are o limită separată, pentru că fiecare cerere încarcă lista completă de clienți. Pentru interogări obișnuite, folosește GET /users/{id} sau căutarea după externalId.
Model de acces recomandat. Păstrează ID-ul de client CreateYourVPN returnat la creare și folosește GET /users/{id} pentru interogările ulterioare. Îl poți asocia cu propriul tău identificator prin externalId.
Idempotență
Trei operațiuni necesită antetul Idempotency-Key: acordarea unui plan, resetarea unui link de abonament și ștergerea unui client.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Repetarea unei cereri cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, în loc să execute din nou operațiunea. Astfel se evită modificările duble atunci când o integrare reîncearcă după un timeout.
Creează câte o cheie pentru fiecare eveniment de business (de exemplu, o plată sau o acțiune) și refolosește-o la fiecare reîncercare a acelui eveniment.
Dacă prima încercare este încă în desfășurare sau rezultatul ei este temporar necunoscut, API-ul răspunde cu 409 conflict fără să execute din nou operațiunea. Verifică starea actuală a clientului înainte să decizi dacă reîncerci.
Folosește colecția publică Postman de mai sus ca sursă de referință pentru schemele de cerere și răspuns.
Restaurează dintr-o copie de rezervă
Două moduri de a-ți aduce utilizatorii înapoi: restaurarea cu un clic din dashboard, care îi reimportă idempotent, sau o restaurare manuală într-un Marzban gol, deoarece fișierul este în formatul nativ de utilizator Marzban.
Acces de urgență
O cale de rezervă pentru conectare atunci când rețeaua folosește liste de permisiuni, iar conexiunea principală este blocată: creezi un apel video, ne dai linkul lui din cont sau prin e-mail și primești o conexiune gata de folosit.