REST API

Внешний REST API для интеграций — работает независимо от веб-интерфейса, на отдельном порту. Ключ для доступа выдаётся в разделе «Администрирование → API‑ключи» — как его получить, описано в статье «API-ключи».

Базовые сведения и аутентификация

• Base URL: http://<адрес сервера>:8081/api/v1/
• Порт 8081 фиксирован и не настраивается через интерфейс.
• Все ответы — JSON, кодировка UTF‑8.
• Видимость данных зависит от прав пользователя, к которому привязан ключ — те же правила, что и в веб-интерфейсе (заявитель, исполнитель и администратор видят разное).

Каждый запрос должен содержать заголовок:

Authorization: Bearer <ваш_ключ>

Без заголовка или с неверным/просроченным ключом сервер возвращает 401 — подробнее обо всех кодах ошибок в самом конце статьи.

Все доступные эндпоинты:

Работа с задачами

Получение одной задачи

GET /api/v1/tasks/{id} — одна задача целиком

Отдаёт те же поля, что и список, плюс body — текст описания задачи.

Пример запроса (получить задачу №42):

curl -H "Authorization: Bearer $API_KEY" "http://server:8081/api/v1/tasks/42"

Пример ответа:

{
  "id": 42,
  "id_status": 1,
  "status": "Новая",
  "id_priority": 2,
  "priority": "Средний",
  "name": "Не печатает принтер в приёмной",
  "id_tree": 8,
  "service": "Принтеры и МФУ",
  "id_group": 16,
  "group": "IT-отдел",
  "id_applicant": 5,
  "id_worker": -1,
  "date_create": "2026-07-18 09:12:00",
  "date_must_be_end": "2026-07-18 17:12:00",
  "date_end": null,
  "body": "Не печатает, индикатор мигает жёлтым. Перезагрузка не помогла."
}

Получение списка задач

GET /api/v1/tasks — список задач

Пример запроса (список задач без фильтров):

curl -H "Authorization: Bearer $API_KEY" "http://server:8081/api/v1/tasks"

Пример ответа:

[
  {
    "id": 42,
    "id_status": 1,
    "status": "Новая",
    "id_priority": 2,
    "priority": "Средний",
    "name": "Не печатает принтер в приёмной",
    "id_tree": 8,
    "service": "Принтеры и МФУ",
    "id_group": 16,
    "group": "IT-отдел",
    "id_applicant": 5,
    "id_worker": -1,
    "date_create": "2026-07-18 09:12:00",
    "date_must_be_end": "2026-07-18 17:12:00",
    "date_end": null
  }
]

Список можно сузить query-параметрами — все необязательные:

Пример запроса (первые 20 новых задач):

curl -H "Authorization: Bearer $API_KEY" \
  "http://server:8081/api/v1/tasks?id_status=1&limit=20"

Формат ответа тот же, что и без фильтров. Пагинация вперёд: возьмите id последней задачи из ответа и передайте его как last_id в следующем запросе.

GET /api/v1/tasks/report — счётчики по статусам

Отдаёт не сами задачи, а количество задач в каждом статусе — удобно для дашбордов и быстрых отчётов, когда не нужен весь список, а нужны только цифры.

Пример запроса (счётчики по всем задачам, без фильтра по датам):

curl -H "Authorization: Bearer $API_KEY" "http://server:8081/api/v1/tasks/report"

Пример ответа:

[
  { "id_status": 1, "status": "Новая", "count": 40 },
  { "id_status": 2, "status": "В работе", "count": 30 },
  { "id_status": 3, "status": "Завершена", "count": 25 }
]

Если нужны счётчики не за всё время, а за конкретный период — например, для еженедельного отчёта — период можно сузить необязательными параметрами date_from, date_to (формат YYYY-MM-DD, фильтр по дате создания, можно передать только один из них):

Пример запроса (счётчики за июль 2026):

curl -H "Authorization: Bearer $API_KEY" \
  "http://server:8081/api/v1/tasks/report?date_from=2026-07-01&date_to=2026-07-31"

Формат ответа тот же.

Создание, изменение и удаление

POST /api/v1/tasks — создать задачу

Заявителем становится пользователь, привязанный к ключу — как и при создании через обычную форму.

Пример запроса (создать задачу с минимальным набором полей):

curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Не работает Wi-Fi в кабинете 210","id_tree":9}' \
  "http://server:8081/api/v1/tasks"

Пример ответа (созданная задача целиком, в том же формате, что и GET /api/v1/tasks/{id}):

{
  "id": 105,
  "id_status": 1,
  "status": "Новая",
  "id_priority": 2,
  "priority": "Средний",
  "name": "Не работает Wi-Fi в кабинете 210",
  "id_tree": 9,
  "service": "Сеть и интернет",
  "id_group": 16,
  "group": "IT-отдел",
  "id_applicant": 5,
  "id_worker": -1,
  "date_create": "2026-07-20 11:02:00",
  "date_must_be_end": "2026-07-20 19:02:00",
  "date_end": null,
  "body": null
}

Обязательные поля — без них задачу не создать:

Кроме обязательных, можно сразу передать и необязательные поля:

Пример запроса (то же самое, но сразу с описанием и наблюдателями):

curl -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Не работает Wi-Fi в кабинете 210","id_tree":9,"comment":"Пропадает сигнал каждые 10 минут","watchers":[3,7]}' \
  "http://server:8081/api/v1/tasks"

Формат ответа тот же, только поле body будет заполнено переданным описанием.

PUT / PATCH /api/v1/tasks/{id} — обновить задачу

Частичное обновление — присылайте только те поля, которые хотите изменить, остальные останутся как есть.

Пример запроса (перевести задачу №42 в статус «В работе»):

curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"id_status":2}' \
  "http://server:8081/api/v1/tasks/42"

В ответ — та же задача целиком, уже с обновлённым полем.

В одном запросе можно менять сразу несколько полей — доступны: name, id_tree, comment, id_group, id_applicant, id_worker, id_status, id_priority, watchers.

Пример запроса (тот же перевод в работу, но сразу с назначением исполнителя):

curl -X PATCH -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"id_status":2,"id_worker":19}' \
  "http://server:8081/api/v1/tasks/42"

• Если watchers не передан — текущий список наблюдателей сохраняется как есть.
• id_worker — используйте -1 (или не указывайте), чтобы задача осталась без исполнителя.

DELETE /api/v1/tasks/{id} — удалить задачу

Удалять может только администратор.

Пример запроса (удалить задачу №42):

curl -X DELETE -H "Authorization: Bearer $API_KEY" "http://server:8081/api/v1/tasks/42"

Пример ответа:

{ "deleted": true }

Справочники

GET /api/v1/trees — ветки услуг

Доступные пользователю ключа ветки, куда можно создавать задачи — для заполнения id_tree.

Пример ответа:

[
  { "id": 8, "name": "Принтеры и МФУ", "id_parent": 1 },
  { "id": 1, "name": "IT и техника", "id_parent": null }
]

GET /api/v1/groups — группы

Пример ответа:

[
  { "id": 16, "name": "IT-отдел", "tipe": 2 }
]

tipe: 1 — Пользователь, 2 — Исполнитель, 3 — Администратор.

GET /api/v1/users — пользователи

Пример запроса (все пользователи):

curl -H "Authorization: Bearer $API_KEY" "http://server:8081/api/v1/users"

Пример ответа:

[
  { "id": 5, "login": "a.ivanov", "name": "Иванов Андрей", "tipe": 1 }
]

Искать по логину или имени можно необязательным параметром search:

Пример запроса (поиск по фамилии «Иванов»):

curl -H "Authorization: Bearer $API_KEY" "http://server:8081/api/v1/users?search=иванов"

Формат ответа тот же.

Удалённые пользователи в выдачу не попадают.

Диагностика

GET /api/v1/debug/pool — состояние пула подключений к БД

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

Ошибки

Все ошибки — в едином формате:

{ "error": "текст ошибки" }

Общие коды:

Частые причины по конкретным эндпоинтам:

Справочные значения по умолчанию

Точный список и порядок могут отличаться, если администратор их менял — актуальный список всегда можно посмотреть в самом интерфейсе.