API#

Al actualizar integraciones a la versión 5.9.4, revise los cambios de la API v1: se eliminaron algunas rutas antiguas, los esquemas de solicitudes son más estrictos y las tareas ahora se consultan a través de una cola. Verifique el método, la ruta y los campos de cada solicitud con Swagger de la versión instalada de Sherpa Orchestrator.

La sección API contiene tres páginas:

1. Swagger — documentación interactiva de solicitudes, parámetros y respuestas. También está disponible en /api/docs/swagger en el servidor de su instalación.
2. ReDoc — otra vista de la misma API, útil para leer esquemas y campos obligatorios.
3. Key — tabla de tokens de API. Cada token tiene nombre, roles asignados y fecha de vencimiento. Se pueden utilizar varios tokens al mismo tiempo.

Crear un token de API#

Crear un token requiere Create en la fila API. Consultar la lista requiere Read, modificar parámetros requiere Update y eliminar requiere Delete en esa fila. El token recibe los permisos de los Roles seleccionados.

Para preparar un token de integración, abra Key en API y pulse "New". Se indican los nombres de la interfaz inglesa; la captura muestra la interfaz rusa.

Campos obligatorios:

• "Name" — finalidad del token;
• "Roles" — acciones permitidas. Seleccione al menos un Rol existente.

Vencimiento:

• "Unlimited" — elimina el límite de vigencia;
• "Expiration date" — fecha y hora de vencimiento cuando Unlimited está desmarcado.

Ejemplo: indique Работа с Действиями en "Name" para una integración de prueba con Acciones y seleccione el Rol my actions (read, write). Desmarque "Unlimited" e indique 21.10.2026 09:00 en "Expiration date". Pulse "Create" para crear el token con esos permisos y vigencia.

Después de crearlo, copie el valor del token o el encabezado Authorization preparado desde el diálogo. El valor se muestra una sola vez: guárdelo en un almacén seguro de secretos antes de cerrar la ventana. Utilice el encabezado mostrado por el Orquestador para llamar a la API y compruebe los requisitos de cada ruta en Swagger. No coloque el token en URL, registros ni archivos sin protección.

La tabla permite consultar el vencimiento y los roles, modificar los parámetros del token o eliminarlo si se tienen los permisos necesarios. El valor secreto de un token existente no puede recuperarse desde la tabla. La autenticación de un Robot mediante GUID en las rutas que la admiten es un mecanismo distinto. Un GUID no es un token de API.

Autenticación Basic de la API legacy#

Las rutas legacy protegidas /api/* que admiten este método aceptan el nombre y la contraseña de una Cuenta, o los de un Usuario con autenticación local o LDAP. LDAP requiere un servicio de directorio configurado y accesible. La cuenta debe estar activa; la autenticación con contraseña no sustituye OAuth para cuentas de ese tipo.

Los permisos del Usuario proceden de sus Roles. El acceso como Cuenta utiliza los permisos de la Cuenta. La autenticación no crea una nueva sesión de interfaz gráfica. Es necesario comprobar la ruta y sus permisos en Swagger de la versión instalada; no debe suponerse que este método se aplica a /api/v1/*.

Ejemplo de lectura de la lista de Robots por HTTPS:

curl --user 'integration_user' 'https://orchestrator.example.com/api/robot/read'

Es necesario sustituir la dirección y el nombre de usuario. curl solicita la contraseña de forma interactiva. No debe incluirse la contraseña en la línea de comandos ni desactivarse la verificación TLS.

La autenticación correcta mediante clave API o GUID de Robot tiene prioridad sobre Basic. Para obtener un resultado predecible, no deben mezclarse métodos en una solicitud.

Si se deniega el acceso, es necesario revisar credenciales, tipo y estado activo de la cuenta y permisos de la ruta. Si LDAP no está disponible, se devuelve 503 con Directory service unavailable; se debe revisar el directorio y la conexión, no cambiar la contraseña.

Validación de valores al escribir Tareas mediante la API heredada#

La creación y actualización de Tareas requieren permiso para la operación correspondiente. Los formatos de solicitud deben comprobarse en Swagger de la compilación instalada.

Para POST /api/task/create, POST /api/task/createFromList y PUT /api/task/update se aplican estas restricciones:

• parent_task — UUID de la Tarea principal. Un valor vacío se guarda como NULL.
• priority — entero de 0 a 3.
• status — entero de 0 a 6.
• retries — entero no negativo.

Los métodos heredados también utilizan nombres como ParentTask. Un valor incorrecto en una solicitud individual de creación o actualización devuelve 400 con el campo errors. En createFromList, el error corresponde al elemento afectado, por lo que debe comprobarse el resultado de cada elemento.

El valor incorrecto debe corregirse en el Robot o la integración antes de repetir la solicitud. Por ejemplo, ParentTask: "string" debe sustituirse por el UUID de una Tarea principal existente o un valor vacío.

Al actualizar la base de datos, los valores incorrectos de parent_task, incluidas las cadenas vacías, se sustituyen por NULL. La migración no restaura los valores anteriores al revertirse. Los valores incorrectos de priority, status y retries no se corrigen automáticamente. El administrador determina los valores correctos.

Consultar la lista de Robots#

La consulta de Robots requiere los permisos del Rol correspondiente. Utilice el encabezado de autorización indicado en Swagger para la versión instalada.

Las solicitudes GET /api/v1/robots y GET /api/robot/read devuelven una lista de Robots sin el campo machine_password. La ausencia de este campo en la lista no significa que se haya eliminado la contraseña del Robot. Si una integración necesita los parámetros de conexión de un Robot concreto, utilice su guid para consultar ese Robot: GET /api/v1/robots/{guid} o GET /api/robot/read/{guid}. Las comprobaciones de permisos existentes para estas solicitudes se mantienen.

Antes de actualizar, compruebe que la integración no obtiene la contraseña de la lista. La edición del Robot y el visor VNC integrado consultan registros individuales; no es necesario volver a introducir las contraseñas guardadas después de actualizar. No registre respuestas que contengan credenciales.

Reasignación de una Licencia Autopilot#

La reasignación conserva el Usuario existente y utiliza el CInfo anterior para activar la nueva clave. Se requieren permisos de modificación de Licencias y acceso al Usuario de la misma Cuenta. La Licencia Autopilot original debe estar activa; la clave nueva debe ser del mismo tipo, estar importada en esa Cuenta, libre y sin activar.

La operación está disponible mediante API v1. El método, los campos y la autenticación deben comprobarse en Swagger de la versión instalada.

1. Es necesario identificar los GUID de Cuenta, Usuario y Licencia actual.
2. Se debe enviar POST /api/v1/accounts/{account_guid}/users/{user_guid}/autopilot_licenses/{license_guid}/reassignments con replacement_license_key y mode igual a automatic o manual. La clave contiene 38 letras y dígitos y debe ser distinta de la actual.
3. En modo automatic, el servidor intenta activar la clave nueva. En modo manual, se utiliza el intercambio habitual de solicitudes y respuestas mediante XLSX. Crear la operación no confirma la activación: es necesario comprobar status y, en caso de error, error_code y error_message.
4. Tras la activación correcta, es necesario restablecer manualmente la clave anterior en el servidor de licencias, eliminarla de Orchestrator e importarla nuevamente antes de reutilizarla.

Hasta completar la liberación y limpieza de la clave anterior, no puede eliminarse, restablecerse ni reasignarse otra vez la Licencia nueva vinculada. La advertencia sobre liberar la clave anterior no significa que haya fallado la activación nueva.

La cancelación está disponible cuando can_cancel=true: antes de enviar la solicitud de activación o después de un fallo definitivo de activación. Se utiliza DELETE en la misma ruta añadiendo /{reassignment_guid}. No está disponible mientras se espera la respuesta (awaiting_response) ni después de completar la operación. Ante 409, es necesario comprobar el estado de la operación; ante 422, la clave y el cuerpo de la solicitud.

Filtrar Licencias mediante API#

En la API, filters[license_key][equal] indica una coincidencia exacta y filters[license_key][not_contains] excluye las claves que contienen el valor. Tras eliminar los espacios iniciales y finales, el valor no debe superar los 128 caracteres. Los campos desconocidos y los operadores no admitidos devuelven HTTP 422.