> For the complete documentation index, see [llms.txt](https://doc.velneo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.velneo.com/38/velneo-vserver/api-rest-en-vserver/api-rest-de-administracion.md). # API REST de administración La **API REST de administración** de [Velneo vServer](/38/velneo-vserver/que-es-velneo-vserver.md) permite automatizar, mediante peticiones HTTP con JSON, las tareas de administración del servidor que normalmente realizamos con [Velneo vAdmin](/38/velneo-vadmin/que-es-velneo-vadmin.md): usuarios, grupos y permisos, soluciones, instancias, carpetas compartidas y disco, tareas programadas, colas, conexiones, transacciones, logs, licencia y servicio HTTPS. Es útil, por ejemplo, para integrar Velneo vServer en procesos de despliegue continuo (CI/CD), aprovisionar usuarios desde otros sistemas o monitorizar el servidor. Se publica desde el [servicio HTTPS](#servicio-https) de Velneo vServer e incluye la especificación **OpenAPI 3.1** y un visor **Swagger UI**. {% hint style="info" %} No hay que confundir esta API con la [API REST de instancia](/38/velneo-vserver/api-rest-en-vserver/api-rest-de-instancia.md), que da acceso a los datos de una instancia, ni con la [API de Velneo Cloud](/38/velneo-cloud/velneo-cloud-api.md), que permite gestionar los servidores contratados en Velneo Cloud. {% endhint %} ## Requisitos La API REST de administración está disponible en: * Servidores de Velneo Cloud. * Servidores locales con **licencia de suscripción** vigente. En cualquier otro caso (licencia que no es de suscripción, caducada o sin licencia), la API solo permite [iniciar sesión y consultar y activar la licencia](#sesion-y-licencia). El resto de operaciones, incluida la consulta de la licencia, responden con un error 403 (*"Operación de administración disponible solo en servidores cloud o de suscripción"*). Al arrancar Velneo vServer, y cada vez que cambia la licencia, se registra en el log del servidor y en el panel de mensajes de Velneo vAdmin si la API está activada o no, y el motivo. Por ejemplo: * *API REST de administración activada. Motivo: licencia de suscripción* * *API REST de administración desactivada. Motivo: licencia caducada* La disponibilidad se recalcula automáticamente, sin reiniciar el servidor, al cambiar la licencia y al llegar su fecha de caducidad. ## Configuración en Velneo vAdmin La API se publica en una [ruta](/38/velneo-vadmin/web.md#rutas) de tipo **Apirest admin** de un *virtual host* del servicio HTTPS. Para ello: 1. Abrir Velneo vAdmin y conectarse al servidor. 2. En la opción [Web](/38/velneo-vadmin/web.md), editar el *virtual host* y añadir una ruta de tipo **Apirest admin**, sin instancia. 3. Indicar como **usuario** un usuario **administrador** de Velneo vServer. 4. Marcar los **métodos HTTP** que se permitirán (**GET**, **POST**, **PUT**, **DELETE**). Una ruta nueva no tiene ningún método marcado, y las peticiones con un método no marcado responden con un error 405. 5. Configurar su seguridad con [perfiles de seguridad](/38/velneo-vadmin/web.md#perfiles-de-seguridad). 6. Aceptar, guardar la configuración y reiniciar el servicio HTTPS. ### Ruta /api de serie Todo *virtual host* nuevo incluye de serie una ruta `/api` de tipo **Apirest admin**, con los métodos **GET** y **POST** y la casilla **Solo operaciones de arranque** marcada. Está pensada para iniciar sesión y activar la licencia de un servidor recién instalado. {% hint style="warning" %} La ruta `/api` se crea sin ningún método de seguridad (autenticación **Sin configurar** en su perfil **Default**), por lo que **no se sirve** hasta que se configure. Velneo vAdmin lo indica con el aviso *"Seguridad: NO ACTIVA"*. {% endhint %} Para usar el resto de la API hay que desmarcar **Solo operaciones de arranque**, marcar los métodos necesarios y configurar su seguridad. ## URL de la API Los *endpoints* se componen con la ruta configurada seguida del path de la operación. Por ejemplo, con la ruta de serie `/api`: * `https://miservidor.miempresa.com/api/login` * `https://miservidor.miempresa.com/api/admin/users` En esta página los paths se indican relativos a la ruta: `login`, `admin/users`, etc. ## Autenticación Todas las operaciones, salvo el inicio y el cierre de sesión, requieren la cabecera: `Authorization: Bearer ` El usuario debe ser **administrador** de Velneo vServer. En caso contrario, se responde con un error 403 (*"Operación requiere privilegios de administrador"*). ### Con API Key u OAuth externo Si el perfil de seguridad de la ruta usa API Keys o un proveedor OAuth externo, se envía directamente la API Key (o el token del proveedor) como token *Bearer*. Las peticiones se ejecutan con el **usuario** de la ruta. ### Con usuario y contraseña Si la ruta tiene un perfil de seguridad con autenticación **Sin autenticación**, se puede obtener un token de sesión de un usuario de Velneo vServer con `POST login`: ```json { "user": "admin", "password": "********" } ``` Respuesta: ```json { "success": true, "token": "3f1c…", "user": "admin", "expiresIn": 3600 } ``` El token caduca tras 3600 segundos sin uso. Tras 5 intentos fallidos en 60 segundos para un mismo usuario, el inicio de sesión se bloquea durante 60 segundos (error 429). Para cerrar la sesión: `POST logout` con `{ "token": "3f1c…" }`. {% hint style="warning" %} El token obtenido con `login` está pensado para poder acceder a las operaciones de licencia, que exigen siempre una credencial de administrador. Solo se admite si la ruta tiene un perfil **Sin autenticación**; en caso contrario, se responde con un error 403. Un perfil sin autenticación debe combinarse con una restricción de IP o usarse solo en entornos controlados. {% endhint %} ## Peticiones y respuestas * Los parámetros se pueden pasar en el path, en la *query string* o en el cuerpo JSON (`Content-Type: application/json`). Un cuerpo que no sea JSON se rechaza con un error 415. * Algunas operaciones de consulta usan POST con los parámetros en el cuerpo. * Las listas se devuelven normalmente como `{ "data": [ … ] }` y las operaciones de modificación como `{ "success": true, … }`. * Todas las respuestas incluyen la cabecera `X-Request-Id` (se devuelve la enviada por el cliente o una generada). ### Errores Los errores se devuelven en formato *problem details* (RFC 9457), con `Content-Type: application/problem+json`: ```json { "type": "https://velneo.com/api/problems/403", "title": "Forbidden", "status": 403, "detail": "Operación requiere privilegios de administrador" } ``` En los errores 5xx no se muestra el detalle interno, sino un identificador de correlación para buscarlo en el log del servidor. | Código | Causa | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | Error en la operación o argumentos no válidos. | | 401 | Falta la credencial o no es válida. | | 403 | El usuario no es administrador, IP no permitida, token de sesión en ruta con perfiles, o servidor sin Velneo Cloud ni licencia de suscripción. | | 404 | Ruta o recurso no encontrado, u operación no servida por una ruta con **Solo operaciones de arranque**. | | 405 | Método HTTP no permitido en la ruta (cabecera `Allow`). | | 409 | El elemento ya existe. | | 413 | Cuerpo de la petición demasiado grande. | | 415 | El cuerpo no es JSON. | | 429 | Límite de peticiones superado o inicio de sesión bloqueado. | | 500 | Error interno (con identificador de correlación). | | 503 | Ruta sin método de seguridad o servicio HTTPS en pausa. | | 504 | Se ha superado el tiempo máximo de la ruta. | ## OpenAPI y Swagger UI * `GET openapi.json`: especificación OpenAPI 3.1 de la API, con las operaciones disponibles en la ruta. Requiere autenticación como administrador. * `GET docs`: visor Swagger UI para consultar y probar la API desde el navegador. La especificación incluye la descripción y los parámetros de cada operación, por lo que es la referencia completa de la API. ## Operaciones ### Sesión y licencia `login`, `logout` y `admin/license/activate` son las **operaciones de arranque**, disponibles siempre, aunque el servidor no tenga licencia de suscripción. La consulta de la licencia (`GET admin/license`) requiere, como el resto de operaciones, un servidor de Velneo Cloud o una licencia de suscripción. | Método | Path | Descripción | | ------ | ------------------------ | --------------------------------------------------------------------------------------------------- | | POST | `login` | Inicio de sesión. Parámetros: `user`, `password`. | | POST | `logout` | Cierre de sesión. Parámetro: `token`. | | GET | `admin/license` | Datos de la licencia del servidor. Requiere Velneo Cloud o licencia de suscripción. | | POST | `admin/license/activate` | Activa la licencia. Parámetros: `email`, `license`, `activationKey`. No disponible en Velneo Cloud. | {% hint style="info" %} Las operaciones de licencia (`admin/license` y `admin/license/activate`) exigen siempre una credencial de administrador, es decir, un token obtenido con `login` o una API Key, aunque el perfil de seguridad de la ruta sea **Sin autenticación**. {% endhint %} ### Usuarios
MétodoPathDescripción
GETadmin/usersLista de usuarios.
POSTadmin/usersAlta de usuario. Parámetros: name, password, group (nombre o identificador).
GETadmin/users/{id}Datos de un usuario (por identificador o nombre).
PUTadmin/users/{id}Modifica un usuario. Parámetros: name, fullName, email, comments, password, isAdministrator, accountDisabled, accountBlocked (solo false, para desbloquear), passwordNotExpire, changePasswordNextConnect, addGroup, removeGroup.
DELETEadmin/users/{id}Elimina un usuario.
POSTadmin/users/{id}/passwordCambia la contraseña. Parámetro: password.
POSTadmin/users/check-passwordComprueba usuario y contraseña sin iniciar sesión.
POSTadmin/users/by-nameBusca un usuario por nombre.
POSTadmin/users/by-emailBusca un usuario por email.
POSTadmin/userExecutableInstancesInstancias que puede ejecutar un usuario.
{% hint style="info" %} Para crear un usuario administrador, se da de alta el usuario y después se modifica con `PUT admin/users/{id}` indicando `"isAdministrator": true`. {% endhint %} ### Grupos y permisos | Método | Path | Descripción | | ------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `admin/groups` | Lista de grupos. | | POST | `admin/groups` | Alta de grupo. Parámetros: `name`, `canCreateSolutions`, `canDeleteSolutions`, `canRunDataClient`. | | GET / PUT / DELETE | `admin/groups/{id}` | Consulta, modificación y baja de un grupo. | | POST | `admin/groups/by-name` | Busca un grupo por nombre. | | POST | `admin/groups/{id}/users` | Usuarios de un grupo. | | POST | `admin/grantRunAppToGroup` / `admin/revokeRunAppFromGroup` | Concede o retira a un grupo el permiso de ejecución de una instancia de aplicación (y de su instancia de datos). | | POST | `admin/listRunAppAccessOfGroup` | Instancias de aplicación que puede ejecutar un grupo. | | POST | `admin/grantRunDataToGroup` / `admin/revokeRunDataFromGroup` | Concede o retira el permiso sobre una instancia de datos. | | POST | `admin/groups/{id}/runDataAccess` | Instancias de datos de un grupo. | | POST | `admin/grantSolutionAccessToGroup` / `admin/revokeSolutionAccessFromGroup` | Concede o retira permisos sobre una solución. `flags` es una máscara: 1 = ver, 2 = editar, 4 = traducir, 8 = crear, 16 = borrar, 32 = exportable. | | POST | `admin/listSolutionAccessOfGroup` | Permisos de un grupo sobre las soluciones. | | POST | `admin/grantFolderToGroup` / `admin/revokeFolderFromGroup` | Concede o retira el acceso a una carpeta compartida. | | POST | `admin/groups/{id}/folders` | Carpetas de un grupo. | ### Soluciones y despliegue
MétodoPathDescripción
GETadmin/solutionsLista de soluciones.
GETadmin/solutions/{solution}/projectsProyectos de una solución: identificador, nombre, alias, versión, tipo (datos o aplicación) y compilación.
POSTadmin/solutions/createCrea una solución vacía. Parámetros: name, version (por defecto "1.0"), shared.
POSTadmin/solutions/deleteElimina una solución y sus instancias.
POSTadmin/solutions/restartReinicia una solución. Parámetros: solution, restartInheritance. Puede fallar si hay conexiones activas.
POSTadmin/solutions/disconnectDesconecta los enganches de ejecución de una solución.
POSTadmin/installVinInstala un fichero .vin ubicado en el servidor (vinPath): crea la solución, sus instancias y, opcionalmente, concede permisos a grupos (grantGroups).
POSTadmin/downloadProjectFileDescarga un proyecto (en base64).
POSTadmin/uploadProjectFileSube un proyecto (en base64).
POSTadmin/registerExecutableInstanceRegistra una instancia de datos o de aplicación de un proyecto.
POSTadmin/detachRunInstanceDesengancha las instancias en ejecución de un proyecto (sin clientes conectados).
POSTadmin/reloadProjectRecarga un proyecto en caliente (sin conexiones activas).
### Instancias
MétodoPathDescripción
GETadmin/instancesLista de instancias, con su tipo, solución, ruta y estado (running, stopped, stopped_no_accepts_connections, not_started, error).
POSTadmin/instances/infoDatos de una instancia (code o instance).
POSTadmin/instances/createCrea una instancia de datos o de aplicación. Parámetros: type, instanceId, name, solution, projectId, path (obligatorio en instancias de datos). Si el identificador ya existe, se crea con un sufijo y se indica en la respuesta (renamed).
POSTadmin/instances/create-with-folderCrea una instancia de datos junto con su carpeta compartida.
POSTadmin/instances/modModifica nombre, senda (instancias de datos) o icono.
POSTadmin/instances/deleteElimina una instancia.
POSTadmin/instances/stopDetiene una instancia (deja de aceptar conexiones).
POSTadmin/instances/start / admin/instances/resumeReanuda una instancia detenida.
POSTadmin/instances/restartReinicia una instancia.
POSTadmin/instances/init-runInicializa la ejecución de una instancia.
POSTadmin/instances/link-dataEnlaza una instancia de aplicación con su instancia o instancias de datos.
POSTadmin/expose-instancePublica una instancia en una ruta del servicio HTTPS. Se aplica al reiniciar el servicio HTTPS.
### Carpetas compartidas y disco
MétodoPathDescripción
GETadmin/foldersLista de carpetas compartidas con sus permisos.
POSTadmin/foldersAlta de carpeta compartida (name, path absoluto existente, permissions).
DELETEadmin/foldersBaja de carpeta compartida.
POSTadmin/folders/get / admin/folders/modConsulta y modificación de una carpeta.
GETadmin/disk/folders, admin/disk/folders/namesCarpetas de disco disponibles.
POSTadmin/disk/dirContenido de un directorio (carpetaCompartida/subruta).
POSTadmin/disk/dir/create, admin/disk/dir/delete, admin/disk/dir/renameCrear, borrar (vacío) y renombrar directorios.
POSTadmin/disk/fileLee un fichero (maxBytes, offset, binary).
POSTadmin/disk/file/writeEscribe un fichero en base64. Admite subida por partes (offset, append).
POSTadmin/disk/file/delete, admin/disk/file/delete-batchBorra uno o varios ficheros (no en uso).
POSTadmin/disk/file/renameRenombra un fichero.
POSTadmin/disk/file/attributesAtributos de un fichero.
Todos los accesos a disco se realizan siempre dentro de carpetas compartidas. ### Tareas programadas
MétodoPathDescripción
GETadmin/tasksLista de tareas.
POSTadmin/tasks/getDatos de una tarea.
POSTadmin/tasks/addAlta de tarea. Tipo (taskTypeCode): 0 copia completa, 1 copia sin herencia, 2 tarea de sistema, 3 ejecutar proceso, 4 reiniciar solución, 5 reiniciar instancia. Planificación (executionPlanCode): 0 una vez, 1 semanal, 2 mensual, 3 periódica.
POSTadmin/tasks/modModifica una tarea.
DELETEadmin/tasksElimina una tarea.
POSTadmin/tasks/runEjecuta una tarea en el momento.
POSTadmin/tasks/historyHistorial de ejecuciones.
GETadmin/timezonesZonas horarias disponibles.
### Colas de procesos | Método | Path | Descripción | | ------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | GET | `admin/queues` | Lista de colas de procesos en 4º plano. | | POST | `admin/queues/get`, `admin/queues/items` | Datos de una cola y sus elementos. | | POST | `admin/queues/start`, `admin/queues/stop` | Arranca o detiene una cola. | | POST | `admin/queues/items/pause`, `.../resume`, `.../reorder`, `.../move`, `.../delete` | Pausar, reanudar, reordenar, mover a otra cola o eliminar un elemento. | | POST | `admin/queues/historics` | Histórico de una cola entre dos fechas. | ### Monitorización | Método | Path | Descripción | | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- | | GET | `admin/metrics` | Métricas del servidor: tiempo en marcha, versión, memoria, CPU, conexiones y estado del servicio HTTPS. | | GET | `admin/connections` | Conexiones (enganches) activas. | | POST | `admin/connections/disconnect` | Desconecta un enganche. | | GET | `admin/transactions` | Transacciones en curso. | | POST | `admin/transactions/get` | Detalle de una transacción. | | POST | `admin/messages` | Mensajes del sistema de un día (`day`: 0 hoy, -1 ayer…). | | POST | `admin/logs/dates` | Fechas disponibles de un log (`general`, `access`, `mcp`, `apirest`). | | POST | `admin/logs/text` | Contenido de un log en una fecha. | | GET / POST | `admin/files` | Consulta y recarga del registro de ficheros de base de datos. | ### Servicio HTTPS | Método | Path | Descripción | | ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `admin/httpserver/status` | Estado del servicio HTTPS. | | POST | `admin/httpserver/stop` | Pausa el servicio HTTPS. Requiere `confirm: true`. `autoStartSeconds` indica en cuántos segundos se reanuda automáticamente (por defecto 300, máximo 3600, 0 = no se reanuda). | | POST | `admin/httpserver/start` | Reanuda el servicio HTTPS. | | GET | `admin/http-config` | Configuración del servicio HTTPS (*virtual hosts*, rutas, perfiles), sin secretos. | | POST | `admin/http-config` | Guarda la configuración del servicio HTTPS. Se aplica al reiniciar el servicio. | {% hint style="danger" %} Pausar el servicio HTTPS con `admin/httpserver/stop` pausa también la propia API REST de administración. Indica siempre un tiempo de reanudación automática (`autoStartSeconds`) si no tienes otra forma de acceder al servidor. {% endhint %} ## Ejemplo: alta de un usuario ```bash # 1. Obtener token (ruta con perfil "Sin autenticación") curl -s -X POST https://miservidor.miempresa.com/api/login \ -H "Content-Type: application/json" \ -d '{"user":"admin","password":"********"}' # 2. Alta de usuario en el grupo "Comerciales" curl -s -X POST https://miservidor.miempresa.com/api/admin/users \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"name":"jperez","password":"********","group":"Comerciales"}' ``` {% hint style="info" %} Las operaciones de esta API también están disponibles para agentes de IA a través del servidor MCP de Velneo vServer. {% endhint %}