API: адрес, первый запрос и ответы

Главная / Документация / APIAPI: адрес, первый запрос и ответыГде находится API вашей установки volrix.pm, как сделать первый запрос с ключом, как устроены списки, коды ошибок (401, 403, 423, 503) и Swagger.Обновлено 16.10.2026У каждой установки volrix.pm свой API. Он работает на том же адресе, что и веб-интерфейс, под префиксом /api/v1: если сотрудники открывают систему по адресу https://pm.company.ru, то базовый адрес API - https://pm.company.ru/api/v1. В статьях раздела он записан как **https://ваш-адрес/api/v1**. Сайт volrix.ru не является адресом API вашей организации.Запросы и ответы передаются в JSON (UTF-8). Исключения: загрузка файлов идет формой multipart/form-data, выгрузки (PDF, XLSX, CSV, DOCX) приходят файлом. Даты передаются как ГГГГ-ММ-ДД, отметки времени - в ISO 8601, идентификаторы объектов - UUID.Чем авторизоваться

Способ

Заголовок

Когда подходит

API-ключ

X-Api-Key: volrix_...

Интеграция с другой системой: 1С, кадровая система, BI, скрипты. Ключ выпускает администратор, права ключа ограничены скоупами.

Сессия пользователя

Authorization: Bearer <access_token>

Действие от имени конкретного человека и маршруты с пометкой «Только сессия». Токен выдает POST /api/v1/auth/login.

API-ключ выпускается в разделе «Администрирование» → «Настройки продукта» → «Интеграции» кнопкой «Создать ключ». Как это сделать, какие права получает ключ и как войти под пользователем - в статье API: вход, токен и API-ключи.Первый запросСначала проверьте, что сервер доступен. Этот адрес открыт без авторизации и отвечает {"status": "ok"}:curl -sS https://ваш-адрес/api/v1/healthЗатем запрос с ключом. Для примера нужен ключ со скоупом users:read («Пользователи: Просмотр»), а у сотрудника, который выпустил ключ, - такое же право в роли:export VOLRIX_API_KEY="volrix_xxxxxxxx.секрет" # храните вне исходного кода curl --fail-with-body -sS \ -H "X-Api-Key: $VOLRIX_API_KEY" \ "https://ваш-адрес/api/v1/users?page=1&page_size=20"Ответ - страница учетных записей. Поля элемента соответствуют схеме UserRead:{ "items": [ { "id": "3f2c...", "email": "ivanov@company.ru", "full_name": "Иванов Иван", "is_active": true, "employee_id": "9a41...", "last_login_at": "2026-09-20T08:15:00Z", "created_at": "2026-01-12T10:00:00Z", "roles": [{"role": "user"}], "permissions": ["projects.read", "..."] } ], "total": 1, "page": 1, "page_size": 20, "pages": 1 }Как устроены спискиЕдиной обертки у списков нет, смотрите колонку «Успешный ответ» в справочнике: **array[...]** - маршрут возвращает массив целиком, имя схемы или **object** - объект.

Вид списка

Параметры

Где встречается

Страница

page (с 1) и page_size; в ответе items, total, page, page_size, у большинства еще pages

Пользователи, проекты, организации, входящие письма, поручения, журнал аудита, реестр документов

Смещение

limit и offset; в ответе items и total

Общий почтовый ящик, журнал ошибок, лента активности профиля

Массив целиком

Только фильтры

Сделки, программы, портфели, договоры, доски, сотрудники (GET /people)

Предел page_size у каждого маршрута свой и указан в справочнике: например, 100 у пользователей и проектов, 200 у организаций и журнала аудита. Значение больше предела вернет 422.Коды и подписи статусов, которые показывает интерфейс, отдает GET /api/v1/reference/enums (нужна сессия пользователя). Значения перечислений, принятые в теле запросов, приведены в конце каждой справочной статьи.Коды ответовТекст ошибки приходит в поле detail. У 422 это список ошибок, у каждой указан путь к полю (loc) и сообщение (msg).

Код

Что значит

Что делать

200, 201, 204

Успех. 201 - объект создан, 204 - ответ без тела.

Сверьте результат: успешный код не гарантирует, что выбран нужный объект или фильтр.

400

Запрос нарушает правило предметной области.

Прочитайте detail и исправьте данные. Повтор без изменений даст тот же ответ.

401

Нет авторизации: заголовок не передан, токен истек, ключ неверный, отозван или истек, учетная запись владельца ключа заблокирована.

Проверьте заголовок и ключ, см. таблицу ошибок в статье о ключах.

403

Нет права: в ключе нет скоупа, у владельца ключа нет права в роли, маршрут не принимает ключ или нет доступа к объекту.

Текст detail называет причину и право вида collection.action.

404

Объект не найден или скрыт областью видимости.

Проверьте идентификатор и доступ владельца ключа к объекту.

409

Конфликт: объект уже есть или изменен параллельно. Например, организация с тем же ИНН - в ответе existing_id.

Перечитайте объект и решите, обновлять ли существующий.

415

Неподдерживаемый тип файла (например, экспертиза принимает только DOCX и PDF).

Передайте файл нужного формата.

422

Ошибка схемы: не хватает обязательного поля, неверный тип или значение вне допустимых.

Смотрите loc и msg в detail.

423

Нет действующей лицензии: POST, PUT, PATCH и DELETE заблокированы, чтение работает. В ответе license_status: expired, invalid, missing или mismatch. На входе 423 означает временную блокировку учетной записи после неудачных попыток.

Администратор загружает файл лицензии, см. Лицензия.

429

Превышен предел частоты: вход - 5 запросов в минуту с адреса, восстановление пароля - 3.

Подождите время из заголовка Retry-After.

503

Временная недоступность: в кластере основной сервер базы данных переключается на резервный (обычно 10-30 секунд). В detail: «База данных переключается на резервный сервер. Повторите через несколько секунд.», в заголовке Retry-After: 5. На одном сервере такой ответ бывает только при сбое самой базы.

Подождите время из Retry-After и повторите запрос. GET повторяйте смело, перед повтором POST, PUT, PATCH и DELETE перечитайте объект: запрос мог дойти до базы до переключения.

Другие 5xx

Ошибка сервера.

Сохраните время запроса и метод, проверьте, не выполнилась ли операция, и передайте администратору (журнал ошибок).

Swagger и схема OpenAPIИнтерактивная документация на сервере по умолчанию выключена. Чтобы ее открыть, администратор сервера задает в файле .env установки переменную **EXPOSE_API_DOCS=true** и перезапускает backend. После этого доступны:

/api/docs - Swagger UI, можно выполнять запросы с ключом (кнопка Authorize, поле APIKeyHeader);

/api/redoc - ReDoc;

/api/openapi.json - схема OpenAPI для генерации клиента.

Кнопка «Открыть Swagger» на экране «Интеграции» ведет на /api/docs и без этой настройки ничего не откроет. Схема описывает именно вашу версию, поэтому при расхождении со справочником верьте ей. Держите схему закрытой, если она не нужна: она раскрывает полный перечень маршрутов.Повторы и надежность

GET можно безопасно повторять после сетевого сбоя.

Ответ 503 с заголовком Retry-After означает переключение базы данных на резервный сервер (только в кластере). Подождите указанное число секунд и повторите запрос - для GET это безопасно. Делайте несколько попыток с нарастающей паузой, а не бесконечный цикл: если 503 держится дольше минуты, сообщите администратору, он увидит состояние узлов на экране «Администрирование» → «Наблюдение» → «Кластер».

Перед повтором POST (создание, переход статуса, отправка) перечитайте объект: общей гарантии идемпотентности у операций нет, повтор может создать дубль.