API per a socis
API de servidor a servidor per a socis: emet una clau, llegeix la configuració de l’aparador i les ubicacions, crea clients, atorga plans i gestiona els enllaços de subscripció des del teu propi web o bot de Telegram.
L’API per a socis et permet crear el teu propi web, el teu propi tauler o un bot de Telegram sobre CreateYourVPN.
L’API cobreix clients, subscripcions, plans i la configuració de l’aparador. La infraestructura, com ara servidors, nodes, panells i credencials SSH, queda fora del contracte públic.
Només de servidor a servidor. Desa les claus API al teu servidor i no les incloguis al codi del frontend. Les sol·licituds amb capçaleres de navegador es rebutgen amb 403 browser_forbidden.
Obtenir una clau
Obre el tauler → menú del compte → «API», pestanya «Claus».
Posa un nom a la clau (bot de Telegram, landing) i tria només els permisos que necessita.
Prem «Emet la clau» i copia el valor complet. El secret es mostra una sola vegada, perquè només se’n desa el hash.
Cada soci pot tenir fins a 5 claus actives. Per canviar una clau, emet-ne una de nova, actualitza la integració i després revoca l’antiga.
Autenticació
Envia la clau com a token bearer:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"X-API-Key: cyv_live_… també funciona, per als clients en què un proxy ocupa Authorization.
Una clau té la forma cyv_live_<key_id>_<secret>. La primera meitat (key_id) és pública: és el que veus al tauler i el que pots esmentar sense risc al suport. La segona meitat és el secret.
Permisos (scopes)
| Permís | Què permet |
|---|---|
config:read | Llegir la configuració de l’aparador, els plans, les ubicacions i /me. |
users:read | Llegir els clients, les seves subscripcions i el trànsit. |
users:write | Crear clients, atorgar plans, restablir enllaços de subscripció i eliminar clients. |
Amb config:read n’hi ha prou per a integracions que només llegeixen dades de l’aparador. Afegeix users:read o users:write només quan la integració necessiti les operacions corresponents amb clients.
Contracte de l’API i exemples
El contracte complet i executable és a la col·lecció pública de Postman. Conté tots els endpoints, permisos, paràmetres, cossos de sol·licitud, exemples de resposta i codis d’error estables. La col·lecció es genera a partir del contracte del backend i és la font vigent dels esquemes de sol·licitud i resposta.
Límits de sol·licituds
Els límits es compten per separat per a cada clau, independentment de l’adreça IP de la sol·licitud.
- 120 sol·licituds/minut per clau en total.
- 10 sol·licituds/minut només per a
GET /users.
GET /users té un límit propi perquè cada sol·licitud carrega la llista completa de clients. Per a consultes habituals, fes servir GET /users/{id} o la cerca per externalId.
Patró d’accés recomanat. Desa l’ID de client de CreateYourVPN que es retorna en crear-lo i fes servir GET /users/{id} per a les consultes posteriors. Pots associar-lo al teu propi identificador mitjançant externalId.
Idempotència
Tres operacions requereixen la capçalera Idempotency-Key: atorgar un pla, restablir un enllaç de subscripció i eliminar un client.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Repetir una sol·licitud amb la mateixa clau dins de les 24 hores retorna la resposta desada en lloc d’executar de nou l’operació. Així s’eviten canvis duplicats quan una integració torna a provar després d’esgotar-se el temps d’espera.
Crea una clau per a cada esdeveniment de negoci (per exemple, un pagament o una acció) i reutilitza-la en tots els reintents d’aquest esdeveniment.
Si el primer intent encara està en curs, o el seu resultat és temporalment desconegut, l’API respon 409 conflict sense executar de nou l’operació. Comprova l’estat actual del client abans de decidir si tornes a provar.
Fes servir la col·lecció pública de Postman de més amunt com a font de referència per als esquemes de sol·licitud i resposta.
Restaura des d'una còpia de seguretat
Dues maneres de recuperar els teus usuaris: la restauració amb un sol clic del tauler que els reimporta de manera idempotent, o una restauració manual a un Marzban buit, ja que el fitxer té el format d'usuari natiu de Marzban.
Accés d'emergència
Una manera alternativa de connectar-te quan una xarxa fa servir llistes blanques i la connexió principal està bloquejada: crea una videotrucada, dona'ns-en l'enllaç des del teu compte o per correu i obtén una connexió a punt.