API para socios
API de servidor a servidor para socios: emite una clave, lee la configuración del escaparate y las ubicaciones, crea clientes, asigna planes y gestiona los enlaces de suscripción desde tu propio sitio o bot de Telegram.
La API para socios te permite crear tu propio sitio, tu propio panel o un bot de Telegram sobre CreateYourVPN.
La API abarca clientes, suscripciones, planes y la configuración del escaparate. La infraestructura, como servidores, nodos, paneles y credenciales SSH, queda fuera del contrato público.
Solo de servidor a servidor. Guarda las claves API en tu servidor y no las incluyas en el código del frontend. Las solicitudes con cabeceras de navegador se rechazan con 403 browser_forbidden.
Obtener una clave
Abre el panel → menú de la cuenta → «API», pestaña «Claves».
Ponle un nombre a la clave (bot de Telegram, landing) y elige solo los permisos que necesita.
Pulsa «Emitir clave» y copia el valor completo. El secreto se muestra una sola vez, porque solo se guarda su hash.
Cada socio puede tener hasta 5 claves activas. Para rotar una clave, emite una nueva, actualiza la integración y después revoca la antigua.
Autenticación
Envía la clave como 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_… también funciona, para clientes en los que un proxy ocupa Authorization.
Una clave tiene la forma cyv_live_<key_id>_<secret>. La primera mitad (key_id) es pública: es lo que ves en el panel y lo que puedes mencionar sin riesgo al soporte. La segunda mitad es el secreto.
Permisos (scopes)
| Permiso | Qué permite |
|---|---|
config:read | Leer la configuración del escaparate, los planes, las ubicaciones y /me. |
users:read | Leer los clientes, sus suscripciones y su tráfico. |
users:write | Crear clientes, asignar planes, restablecer enlaces de suscripción y eliminar clientes. |
config:read basta para integraciones que solo leen datos del escaparate. Añade users:read o users:write solo cuando la integración necesite las operaciones con clientes correspondientes.
Contrato de la API y ejemplos
El contrato completo y ejecutable está en la colección pública de Postman. Contiene todos los endpoints, permisos, parámetros, cuerpos de solicitud, ejemplos de respuesta y códigos de error estables. La colección se genera a partir del contrato del backend y es la fuente vigente de los esquemas de solicitud y respuesta.
Límites de solicitudes
Los límites se cuentan por separado para cada clave, independientemente de la dirección IP de la solicitud.
- 120 solicitudes/minuto por clave en total.
- 10 solicitudes/minuto solo para
GET /users.
GET /users tiene un límite propio porque cada solicitud carga la lista completa de clientes. Para consultas habituales, usa GET /users/{id} o la búsqueda por externalId.
Patrón de acceso recomendado. Guarda el ID de cliente de CreateYourVPN que se devuelve al crearlo y usa GET /users/{id} en las consultas posteriores. Puedes asociarlo a tu propio identificador mediante externalId.
Idempotencia
Tres operaciones requieren la cabecera Idempotency-Key: asignar un plan, restablecer un enlace de suscripción y eliminar un cliente.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Repetir una solicitud con la misma clave dentro de las 24 horas devuelve la respuesta guardada en lugar de ejecutar de nuevo la operación. Así se evitan cambios duplicados cuando una integración reintenta tras agotarse el tiempo de espera.
Crea una clave por cada evento de negocio (por ejemplo, un pago o una acción) y reutilízala en todos los reintentos de ese evento.
Si el primer intento sigue en curso, o su resultado es temporalmente desconocido, la API responde 409 conflict sin ejecutar de nuevo la operación. Comprueba el estado actual del cliente antes de decidir si reintentar.
Usa la colección pública de Postman de arriba como fuente de verdad para los esquemas de solicitud y respuesta.
Restaurar desde una copia de seguridad
Dos formas de recuperar a tus usuarios: la restauración con un clic desde el panel, que los reimporta de forma idempotente, o una restauración manual en un Marzban vacío, ya que el archivo está en formato de usuario nativo de Marzban.
Acceso de emergencia
Una forma de reserva para conectarte cuando la red usa listas blancas y la conexión principal está bloqueada: crea una videollamada, danos su enlace desde tu panel o por correo y obtén una conexión lista para usar.