API — документация 0.4

Всё, что делает панель, доступно через REST API https://<сервер>:8443/api/v1: запускать процессы из 1С и других систем, добавлять элементы в очереди, забирать отчёты, выкладывать конфигурацию из CI. Панель сама пользуется этим API.

Вход #

Способ	Как	Для чего
Токен API	Заголовок `Authorization: Bearer tlp_…`	Скрипты и внешние системы
Сеанс панели	Cookie `tulpar_sid` после `POST /api/v1/auth/login`	Браузер

Токен создаётся в панели: «Профиль» → «Токены API» → «Создать токен». Права токена — вид токена в пересечении с правами его владельца (см. права токенов): «Только чтение» разрешает GET и SQL-запросы к базе отчётов (они только читают), «Запуск» — ещё задания, элементы очередей и запись в отчёты, «Полный доступ» — всё, что может владелец.

Изменяющие запросы (POST, PUT, PATCH, DELETE) с cookie обязаны иметь заголовок X-Tulpar-Csrf: 1; с токеном он не нужен.

GET https://orch.company.kg:8443/api/v1/processes?q=сверка&withTotal=true
Authorization: Bearer tlp_…

Общие правила #

Ошибки — JSON { "error": { "code", "message", "details"? } }, message — по-русски, для человека:

HTTP	`code`	Когда
400	`BadRequest`	Неверный запрос
401	`Unauthorized`, `InvalidCredentials`	Нет входа или неверный логин/пароль
403	`Forbidden`, `CsrfHeaderMissing`, `LicenseRequired`	Нет права; нет заголовка CSRF; ограниченный режим лицензии
404	`NotFound`	Нет объекта — или он в рабочей области, к которой у вас нет доступа
409	`Conflict`, `ConcurrentUpdate`, `VersionExists`, `InvalidState`	Имя занято; объект изменил другой; версия уже опубликована; недопустимое состояние
422	`ValidationFailed`	Неверные поля: `details: [{ "field": "args.amount", "message": "…" }]`
423	`AccountLocked`	Учётная запись временно заблокирована после неудачных входов
429	`RateLimited`	Слишком много запросов — повторите позже
503	`Unavailable`	Временно недоступно (например, база отчётов)

Списки — ?limit=50 (до 500), cursor, withTotal=true, sort=поле:asc|desc и фильтры ресурса. Ответ — { "items": [...], "nextCursor": "…" | null, "total"? }. Следующая страница — тот же запрос с cursor=<nextCursor>; курсор устойчив к добавлению новых записей.

Изменение — PATCH с частичным телом и полем version объекта (из GET). Если объект успели изменить, ответ — 409 ConcurrentUpdate: перечитайте объект и повторите.

Время — ISO 8601 в UTC с Z: 2026-11-16T04:30:00.000Z. Идентификаторы — GUID.

Ограничения частоты: токен API — 600 запросов в минуту, вход — 10 попыток в минуту с адреса, поиск по журналу и выгрузки — 30 в минуту на пользователя.

Ресурсы #

Ресурс	Основные адреса
Процессы и версии	`GET /processes`, `GET /processes/{id}`, `GET /processes/{id}/versions`, `POST /processes/{id}/current-version`, `POST /packages` (публикация `.tpkg`), `GET /processes/{id}/passport`, `GET /processes/{id}/passport/export?format=xlsx`
Задания	`GET /jobs`, `POST /jobs`, `GET /jobs/{id}`, `GET /jobs/{id}/wait`, `POST /jobs/{id}/stop`, `POST /jobs/{id}/restart`, `GET /jobs/{id}/events`
Расписания	`GET /triggers`, `POST /triggers`, `PATCH /triggers/{id}`, `POST /triggers/{id}/run-now`, `GET /triggers/{id}/history`, `POST /triggers/preview`
Очереди	`GET /queues`, `POST /queues`, `POST /queues/{id}/items`, `POST /queues/{id}/import`, `GET /queues/{id}/items`, `GET /queues/{id}/items/export`, `POST /queue-items/retry`, `POST /queue-items/complete`
Роботы	`GET /robots`, `GET /robots/{id}`, `POST /robots/{id}/maintenance`, `POST /robots/{id}/update`, `POST /robots/{id}/diagnostics`
Ресурсы	`GET /assets`, `POST /assets`, `PUT /assets/{id}/value`, `POST /assets/{id}/copy`
Журнал, ошибки, аналитика	`GET /logs/search`, `GET /logs/export`, `GET /errors/groups`, `GET /analytics/processes`, `GET /analytics/robots`
Оповещения	`GET /alerts`, `POST /alerts/{id}/ack`, `POST /alerts/{id}/resolve`, `GET /alert-rules`
Отчёты	`GET /reports`, `GET /reports/{id}/records`, `POST /reports/{id}/records`, `GET /reports/{id}/records/export`, `GET /reports/builtin/process/{id}`, `GET /reports/builtin/summary`, `POST /reports/sql/run`, `POST /reports/queries/{id}/run`, `POST /reports/queries/{id}/export`
Лицензия	`GET /license`, `POST /license`, `GET /license/history`, `PUT /robots/{id}/license`, `PUT /users/{id}/studio-seat`
Перенос	`POST /transfer/export`, `POST /transfer/preview`, `POST /transfer/import`, `POST /transfer/copy`, `GET /transfer/profiles`, `GET /transfer/runs`
Администрирование	`GET /users`, `POST /users`, `GET /workspaces`, `PUT /workspaces/{id}/members/{userId}`, `GET /audit`, `GET /audit/export`, `GET /system/status`
Проверки здоровья (без входа)	`GET /health/live`, `GET /health/ready`

Пути даны от /api/v1, кроме /health/*. Полный набор запросов с телами — файл docs/orchestrator-api.http в репозитории (открывается в VS Code REST Client и в Rider).

Задания: запусти и дождись #

POST /api/v1/jobs
Authorization: Bearer tlp_…
Content-Type: application/json

{ "processId": "019a…", "args": { "period": "2026-11" }, "priority": "high", "note": "по запросу из 1С" }

Ответ 201 { "job": { "id", "number", "status": "pending", … } }. Без versionId берётся текущая версия; аргументы проверяются по типам (422 с полями args.*). Дождаться результата:

GET /api/v1/jobs/019a…/wait?timeoutSec=120
Authorization: Bearer tlp_…

Запрос ждёт финального статуса не дольше timeoutSec (1–120 с) и возвращает задание: status, error { code, message, stepId }, output — поля, которые процесс записал шагом Результат задания (аргументы и результат видны токену с правом на данные). Не дождались — повторите wait.

Очереди: добавить элементы #

POST /api/v1/queues/019a…/items
Authorization: Bearer tlp_…
Content-Type: application/json

{ "items": [
  { "reference": "З-1001", "payload": { "Номер": "З-1001", "ФИО": "Асанова Айгерим" }, "priority": "high", "deadline": "2026-11-17T12:00:00Z" },
  { "reference": "З-1002", "payload": { "Номер": "З-1002" }, "notBefore": "2026-11-17T03:00:00Z" }
] }

Нужен токен «Запуск» или «Полный доступ». В очереди с „без дубликатов по ссылке“ элемент с существующей ссылкой отклоняется с кодом QueueItemDuplicate. Список элементов — GET /queues/{id}/items?status=failed&errorType=system.

Ресурсы: сменить пароль #

PUT /api/v1/assets/019a…/value
Authorization: Bearer tlp_…
Content-Type: application/json

{ "username": "robot-bank", "password": "новый-пароль" }

С robotId — значение для одного робота. Пароль никогда не возвращается в ответах GET. Удобно для скрипта, который меняет пароль сервисной учётной записи по расписанию.

Отчёты #

Записи пользовательского отчёта с фильтрами — тот же синтаксис, что в адресе страницы отчёта в панели:

GET /api/v1/reports/019a…/records?f.status=Ошибка&createdFrom=2026-11-15&limit=200
Authorization: Bearer tlp_…

f.<поле>=… — равно (у текста — „содержит“), f.<поле>.from / .to — диапазон, f.<поле>.empty=true, q — поиск, createdFrom / createdTo, jobId, source. Выгрузка той же выборки — GET …/records/export?format=csv (или xlsx); для Excel и BI-систем это самый простой способ, хватает токена «Только чтение».

Записать строку от имени оператора — POST /reports/{id}/records с { "values": { "number": "П-0001", "amount": "3 400,50" } }.

SQL-запрос и сохранённый запрос:

POST /api/v1/reports/sql/run
Authorization: Bearer tlp_…
Content-Type: application/json

{ "workspaceId": "019a…",
  "sql": "SELECT process, sum(runs) AS runs FROM process_daily WHERE day >= :from GROUP BY process",
  "values": { "from": "startOfMonth" } }

POST /api/v1/reports/queries/019a…/export
Authorization: Bearer tlp_…
Content-Type: application/json

{ "format": "csv", "values": { "from": "yesterday", "to": "today" } }

Ответ run — колонки и первые 1 000 строк, export — файл (format: csv — без ограничения строк, xlsx). Ошибка SQL — 422 ReportSqlError с позицией. Запросы выполняются только на чтение (транзакция READ ONLY от роли области), поэтому POST /reports/sql/run, /reports/sql/explain, /reports/sql/export и POST /reports/queries/{id}/run, /export принимает и токен «Только чтение» — его удобно отдать Power BI, Excel или другой BI-системе. Права всё равно проверяются по владельцу токена: свой SQL — разработчик, владелец области, аудитор, администратор; сохранённый общий запрос — все, кто видит отчёты области. Сохранить, изменить или удалить запрос токеном «Только чтение» нельзя (403).

Прямое подключение BI к базе отчётов (без API) — ролью области, логин и пароль показывает администратор в «Настройки» → «Отчёты» (см. База отчётов). API этой вкладки — только для администратора: GET /settings/reports (адрес базы и роли областей, без паролей), POST /settings/reports/roles/{workspaceId}/reveal — пароль роли (каждый показ в аудите), POST …/rotate — новый пароль.

Лицензия #

GET /license — состояние, лимиты, занятые места и requestCode; POST /license { "text": "<содержимое .tlic>" } — ввести лицензию (422 LicenseInvalid с причиной); PUT /robots/{id}/license { "licensed": true } — назначить место роботу, PUT /users/{id}/studio-seat { "granted": true } — место студии (409 LicenseLimitReached, если мест нет). Только администратор. Подробнее — Лицензирование.

Перенос #

POST /api/v1/transfer/export
Authorization: Bearer tlp_…
Content-Type: application/json

{ "workspaceId": "019a…",
  "include": { "assets": true, "credentials": "secrets", "queues": true, "triggers": true, "reports": true, "processes": true },
  "password": "Пароль-файла-2026" }

Ответ — файл .tbundle. POST /transfer/preview и /transfer/import принимают multipart: часть file (файл переноса) и часть options — JSON { "workspaceId", "password"?, "robotMapping"?: { "РОБОТ-01": "<id робота цели>" }, "substitutions"?: [{ "find": "test-1c.local", "replace": "prod-1c.local" }], "profileId"?, "defaultPolicy": "update", "policies"?: { "assets/Адрес 1С": "skip" }, "dryRun"? }. Ошибка любого объекта откатывает всё — 422 TransferFailed со списком. Нужен токен «Полный доступ» владельца области или администратора. Для CI проще команды сервера — см. Перенос между средами.