API#

При обновлении интеграций до версии 5.9.4 необходимо проверить изменения API v1: часть старых маршрутов удалена, схемы запросов стали строже, а Задачи теперь читаются через Очередь. Для каждого запроса необходимо сверять метод, путь и поля со Swagger установленной версии Sherpa Orchestrator.

В разделе API доступны три страницы:

1. Swagger — интерактивное описание запросов, параметров и ответов. Оно также доступно по адресу /api/docs/swagger на сервере своей установки.
2. ReDoc — представление того же API, удобное для чтения схем и обязательных полей.
3. Ключ — таблица API-токенов. Каждый токен имеет имя, назначенные Роли и срок действия. Поддерживается одновременное использование нескольких токенов.

Изменение Работы через устаревший API#

Метод PUT /api/job/update изменяет Работу в Аккаунте, от имени которого авторизован запрос. Для Пользователя или API-токена требуется право обновления Работ. GUID Работы другого Аккаунта не предоставляет доступ к записи.

Перед запросом необходимо проверить принадлежность Работы своему Аккаунту и передать ее GUID в поле Guid. Значения статуса и формат остальных полей необходимо сверять со Swagger установленной версии. Успешное обновление возвращает HTTP 200 и пустой JSON-массив [].

Для недоступной, удаленной или несуществующей Работы возвращается 403, запись не изменяется. Через этот метод нельзя перенести Работу в другой Аккаунт или назначить ей Робота, версию Процесса, Задачу либо Триггер другого Аккаунта. При 403 необходимо проверить авторизацию, права и принадлежность связанных записей. Для работы в другом Аккаунте требуется использовать выданные в нем учетные данные.

Создание API-токена#

Токен позволяет интеграции обращаться к API с правами выбранных Ролей. Сначала настраиваются права, затем токен создается на странице Ключ раздела API.

Настройка прав на экране Роли для токенов#

На экране Роли необходимо открыть нужную Роль и перейти на вкладку "Доступ", чтобы разрешить работу с токенами. Для создания токена необходимо право "Создание" в строке "API". Просмотр списка требует "Чтение", изменение параметров — "Обновление", удаление — "Удаление" в той же строке. Токен получает права выбранных для него Ролей.

Создание токена на странице Ключ раздела API#

Чтобы подготовить токен для интеграции, необходимо открыть страницу Ключ в разделе API и нажать на кнопку "Создать".

Обязательные поля:

• поле "Имя" — поясняет назначение токена;
• поле "Роли" — задает разрешенные токену действия. Требуется выбрать хотя бы одну заранее созданную Роль.

Срок действия:

• чекбокс "Бессрочно" — отключает ограничение срока действия;
• поле "Дата окончания" — задает дату и время окончания действия токена. Заполняется при снятом чекбоксе "Бессрочно".

Пример: для тестовой интеграции с Действиями укажите "Работа с Действиями" в поле "Имя", выберите Роль "my actions (read, write)" в поле "Роли". Снимите чекбокс "Бессрочно" и укажите 21.10.2026 09:00 в поле "Дата окончания". Нажмите на кнопку "Создание", чтобы выпустить токен с выбранными правами и сроком.

После создания необходимо скопировать значение токена или готовый заголовок Authorization из диалога. Значение показывается только один раз: важно сохранить его в защищенном хранилище секретов до закрытия окна. Для вызова API необходимо использовать именно заголовок, показанный Оркестратором, и сверять требования конкретного маршрута со Swagger. Важно не помещать токен в URL, журналы или открытые файлы.

Таблица показывает срок действия и Роли токена. Изменение параметров и удаление выполняются при наличии соответствующих прав. Существующее секретное значение из таблицы повторно получить нельзя. Аутентификация Робота по GUID на предусмотренных для нее маршрутах — отдельный механизм. GUID не является API-токеном.

Вход по логину и паролю через API /api/*#

Некоторые защищенные маршруты /api/* поддерживают вход по логину и паролю. Для обращения к ним используются учетные данные Аккаунта или Пользователя с локальной либо LDAP-аутентификацией. Для LDAP необходима настроенная и доступная служба каталога. Учетная запись должна быть активна. Вход с паролем не заменяет OAuth для учетной записи такого типа.

Права Пользователя определяются назначенными Ролями. Вход от имени Аккаунта использует права Аккаунта. Аутентификация не создает новую GUI-сессию. Необходимо проверить маршрут и требуемые права в Swagger установленной версии. Этот способ нельзя автоматически переносить на /api/v1/*.

Пример чтения списка Роботов через HTTPS:

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

Необходимо заменить адрес и логин своими значениями. curl запросит пароль интерактивно. Не следует добавлять пароль в командную строку или отключать проверку TLS.

Успешная аутентификация по API-ключу или GUID Робота имеет приоритет перед Basic. Для предсказуемого результата не следует смешивать способы аутентификации в одном запросе.

При отказе необходимо проверить логин, пароль, тип и активность учетной записи, а также права на конкретный маршрут. Недоступность LDAP возвращает 503 с сообщением Directory service unavailable. Следует проверить каталог и соединение, а не заменять пароль.

Проверка значений при записи Задач через API /api/*#

Для создания и обновления Задач требуются права на соответствующее действие с Задачами. Формат запросов необходимо сверять со Swagger установленной сборки.

Для POST /api/task/create, POST /api/task/createFromList и PUT /api/task/update действуют следующие ограничения:

• parent_task — UUID родительской Задачи. Пустое значение сохраняется как NULL.
• priority — целое число от 0 до 3.
• status — целое число от 0 до 6.
• retries — целое неотрицательное число.

Методы /api/* также используют имена вида ParentTask. При некорректном значении отдельное создание или обновление возвращает 400 с полем errors. В createFromList ошибка возвращается для конкретного элемента списка, поэтому необходимо проверить результат каждого элемента.

Некорректное значение требуется исправить в Роботе или интеграции перед повторным запросом. Например, вместо ParentTask: "string" необходимо передать UUID существующей родительской Задачи или пустое значение.

При обновлении БД некорректные значения parent_task, включая пустые строки, заменяются на NULL. Миграция не восстанавливает прежние значения при откате. Некорректные priority, status и retries автоматически не исправляются. Правильные значения определяет администратор.

Чтение списка Роботов#

Список используется для выбора Робота в интеграции. Сначала требуется разрешить чтение на экране Роли, затем выполнить запрос через API.

Настройка прав на экране Роли для списка Роботов#

Для разрешения чтения списка необходимо открыть нужную Роль на экране Роли, перейти на вкладку "Доступ" и установить чекбокс "Чтение" в строке "Роботы".

Запрос списка Роботов через API#

Для запроса необходимо использовать заголовок авторизации, указанный в Swagger установленной версии.

Запросы GET /api/v1/robots и GET /api/robot/read возвращают список Роботов без поля machine_password. Отсутствие этого поля в списке не означает, что пароль Робота удален. Если интеграции нужны параметры подключения конкретного Робота, необходимо использовать его guid для одиночного чтения: GET /api/v1/robots/{guid} или GET /api/robot/read/{guid}. Действующие проверки прав для этих запросов сохраняются.

Перед обновлением необходимо проверить, что интеграция не берет пароль из списка. Редактирование Робота и встроенный VNC используют одиночное чтение. Повторно вводить сохраненный пароль после обновления не требуется. Ответы с учетными данными не должны попадать в журналы.

Переназначение Лицензии Autopilot#

Переназначение сохраняет существующего Пользователя и использует прежний CInfo при активации нового ключа. Необходимы права изменения Лицензий и доступ к Пользователю своего Аккаунта. Исходная Лицензия Autopilot должна быть активна, а новый ключ того же типа — импортирован в этот Аккаунт, свободен и еще не активирован.

Операция доступна через API v1. Метод, поля и схемы авторизации необходимо сверять со Swagger установленной версии.

1. Требуется определить GUID Аккаунта, Пользователя и его текущей Лицензии.
2. Необходимо выполнить POST /api/v1/accounts/{account_guid}/users/{user_guid}/autopilot_licenses/{license_guid}/reassignments, передав replacement_license_key и mode со значением automatic или manual. Ключ содержит 38 букв и цифр и должен отличаться от текущего.
3. При automatic сервер пытается активировать новый ключ. При manual используется обычный обмен запросами и ответами активации через XLSX. Создание операции еще не означает успешную активацию: необходимо проверить status, а при ошибке — error_code и error_message.
4. После успешной активации требуется вручную сбросить предыдущий ключ на сервере лицензирования, удалить его из Оркестратора и импортировать заново перед повторным использованием.

До завершения освобождения предыдущего ключа новую связанную Лицензию нельзя удалить, сбросить или переназначить дальше. Предупреждение об освобождении старого ключа не означает ошибку активации нового.

Отмена доступна при can_cancel=true: до отправки запроса активации или после окончательного отказа активации. Для нее используется DELETE по тому же пути с добавленным /{reassignment_guid}. При ожидании ответа (awaiting_response) и после завершения операции отмена недоступна. При 409 необходимо проверить текущее состояние операции, при 422 — ключ и тело запроса.

Фильтр Лицензий через API#

При работе через API точное совпадение задается параметром filters[license_key][equal], а исключение по части ключа — filters[license_key][not_contains]. После удаления пробелов по краям значение фильтра не должно превышать 128 символов. Неизвестные поля и неподдерживаемые операторы возвращают HTTP 422.

Чтение Аккаунтов через legacy API#

Чтение позволяет получить сведения о своем Аккаунте и его прямых дочерних Аккаунтах. Для Пользователя или API-токена требуется право чтения Аккаунтов в назначенных Ролях.

Для проверки интеграции необходимо выполнить запросы с ее заголовком Authorization:

1. GET /api/account/read — получить список доступных Аккаунтов.
2. GET /api/account/read/{guid} — получить один Аккаунт. Вместо {guid} необходимо указать GUID из списка.

Например, у Аккаунта A есть дочерний A1, а у A1 — дочерний A2. При обращении от имени A список содержит A и A1. Аккаунт A2 и независимый Аккаунт B в него не входят. Запрос по GUID недоступного, удаленного или несуществующего Аккаунта возвращает HTTP 200 с JSON-значением false. При недостаточных правах возвращается 403.

Поле password отсутствует во всех ответах. Поле api_key возвращается только для своего Аккаунта. Даты сохраняют формат legacy API и часовой пояс вызывающего Аккаунта.

Перед обновлением необходимо проверить, что интеграция не получает ключи дочерних Аккаунтов из этих ответов. Для работы от имени другого Аккаунта требуется заранее подготовить в нем отдельный API-токен с необходимыми Ролями и передать его интеграции через защищенное хранилище. Отсутствие ключа в ответе не означает его удаление. При ответе false необходимо проверить GUID и связь Аккаунтов, при 403 — права и заголовок авторизации.

Создание записи журнала со скриншотом#

POST /api/v1/logs принимает JSON с полем screenshot в base64 или multipart/form-data с файлом в поле file. Перед использованием необходимо проверить наличие обоих форматов в Swagger установленной версии. Для токена требуется право создания журналов и доступ к Роботу своего Аккаунта.

Обязательное поле robot_guid содержит GUID Робота. Необязательные job_guid и process_version_guid задают контекст Работы и версии Процесса. Если передана Работа, версия определяется из нее. Явно указанная версия должна совпадать с версией Работы.

Дополнительные поля:

• level — уровень Critical, Error, Warning, Notice, Info или Debug;
• message — текст записи;
• fields — JSON-объект. В multipart передается строка с JSON, например {"source":"designer","attempt":1}. Корневые массивы и объекты с последовательными числовыми ключами, например {"0":"value"}, не поддерживаются;
• file — необязательный PNG размером не более 12 MiB (12 582 912 байт) для multipart. Имя screenshot в multipart не используется. Для JSON сохраняется поле screenshot с PNG в base64.

Пример: интеграция сохраняет скриншот завершенного шага. Необходимо подготовить PNG screenshot.png, GUID доступного Робота в ROBOT_GUID и заголовок авторизации в AUTHORIZATION. Адрес требуется заменить адресом своей установки.

curl --fail-with-body 'https://orchestrator.example.com/api/v1/logs' \
  --header "Authorization: ${AUTHORIZATION}" \
  --form-string "robot_guid=${ROBOT_GUID}" \
  --form-string 'level=Info' \
  --form-string 'message=Step completed' \
  --form-string 'fields={"source":"designer","attempt":1}' \
  --form 'file=@screenshot.png;type=image/png'

Ответ 201 содержит data.guid записи и has_file: true. Скриншот не включается в список и карточку журнала. Для получения base64 используется GET /api/v1/logs/{log_guid}/file с правом чтения журналов.

При 422 необходимо исправить формат полей, размер или содержимое файла. Подмена MIME не разрешает загрузку другого формата изображения. При 403 требуется проверить права, при 404 — GUID и доступность связанных объектов. Тестовые записи следует создавать в отдельном тестовом Аккаунте. Общую очистку журналов не следует использовать для удаления одной тестовой записи.