Управление компьютерами
Документация описывает работу с API для управления компьютерами в приложении Severcart.
Назначение
API управления компьютерами предоставляет конечные точки для:
- получения списка компьютеров с фильтрацией, сортировкой и пагинацией;
- создания новых записей о компьютерах;
- получения информации об отдельном компьютере;
- частичного и полного обновления данных компьютера;
- удаления записей о компьютерах.
Все операции выполняются через REST API с использованием JSON для передачи данных.
Базовый URL API
Все запросы к API компьютеров отправляются по адресу:
/api/v1/computers/
Полный URL формируется путём добавления пути к базовому адресу сервера. Например:
http://<your-server>/api/v1/computers/
Аутентификация
Все конечные точки API требуют JWT-аутентификации. Токен передаётся в
заголовке Authorization:
Authorization: Bearer <access_token>
Подробнее о получении токенов см. документацию JWT-аутентификация.
Права доступа
Для работы с API компьютеров требуются следующие права:
| Операция | Право | Код права |
|---|---|---|
| Просмотр списка / получение данных | ro_ce |
2048 |
| Создание | ap_ce |
2097152 |
| Редактирование (PATCH, PUT) | rw_ce |
4096 |
| Удаление | er_ce |
4194304 |
Права назначаются через группы пользователей в административной панели. Наличие права на запись/создание подразумевает право на чтение.
Конечные точки
Все URL-адреса обязаны заканчиваться символом /. Запросы без завершающего
слэша возвращают 301 Moved Permanently (редирект).
| Метод | URL | Описание | Право |
|---|---|---|---|
POST |
/api/v1/computers/list/ |
Получение списка компьютеров | ro_ce |
POST |
/api/v1/computers/ |
Создание компьютера | ap_ce |
GET |
/api/v1/computers/{pk}/ |
Получение данных компьютера | ro_ce |
PATCH |
/api/v1/computers/{pk}/ |
Частичное обновление | rw_ce |
PUT |
/api/v1/computers/{pk}/ |
Полное обновление | rw_ce |
DELETE |
/api/v1/computers/{pk}/ |
Удаление компьютера | er_ce |
POST /api/v1/computers/list/
Получение списка компьютеров с поддержкой фильтрации, сортировки и пагинации.
Назначение
Используется для получения списка компьютеров с возможностью гибкой настройки вывода данных. Запрос отправляется методом POST с параметрами в теле запроса в формате JSON.
HTTP-метод
POST
Параметры запроса
Тело запроса должно быть в формате JSON и может содержать следующие поля:
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
page |
integer | Нет | 1 | Номер страницы для пагинации |
size |
integer | Нет | 20 | Количество записей на странице (1–100) |
sort |
string | Нет | -id |
Поле для сортировки (префикс - для убывания) |
filter |
object | Нет | {} |
Объект с фильтрами по полям компьютера |
Формат запроса
Content-Type: application/json
Коды состояния HTTP
| Код | Описание |
|---|---|
200 OK |
Список успешно получен |
400 Bad Request |
Неверный формат запроса или параметры |
401 Unauthorized |
Токен недействителен или истёк |
403 Forbidden |
Недостаточно прав для операции |
Пример запроса (curl)
curl -X POST http://<your-server>/api/v1/computers/list/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"page": 1,
"size": 20,
"sort": "-id",
"filter": {
"status": "Резерв",
"place": "Office A"
}
}'
Пример успешного ответа
Код состояния: 200 OK
{
"items": [
{
"id": 150,
"dns_name": "pc-150.corp.local",
"serial_number": "SN123456",
"inventory_number": "INV-000150",
"inventory_number2": "",
"name": "Dell XPS 13",
"manufacturer": "Dell",
"ce_type": "Ноутбук",
"status": "Резерв",
"branch": "Здание 1",
"place": "Здание 1. 1 этаж > Office A",
"date_change": "15/01/2025 03:30 PM",
"date_added": "15/01/2025 10:00 AM",
"pur_date": "15/01/2025",
"end_warranty": "15/01/2028",
"prod_year": 2025,
"date_connect": "15/01/2025 10:05 AM",
"user": "ivanov | Иванов Иван Иванович",
"responsible": "petrov | Петров Петр Петрович",
"comment": "Рабочая станция",
"price": 1500.00,
"supplier": "Tech Supplier",
"guarantee": "3 года",
"os_name": "Microsoft Corporation Windows 10 Pro",
"user_agent": "Offline inventory.",
"domain": "WORKGROUP"
}
],
"pagination": {
"page": 1,
"size": 20,
"total": 150,
"pages": 8
}
}
Доступные поля для фильтрации
Фильтры передаются в объекте filter в теле запроса. Все текстовые фильтры
используют частичное совпадение (icontains), кроме status — точное совпадение
по названию (регистронезависимое).
| Поле | Тип | Описание |
|---|---|---|
pk |
string | ID компьютера (точное совпадение) |
status |
string | Статус компьютера (точное совпадение по названию) |
name |
string | Название модели (частичное совпадение) |
dns_name |
string | Сетевое имя (частичное совпадение) |
manufacturer |
string | Производитель (частичное совпадение) |
ce_type |
string | Тип техники (частичное совпадение) |
branch |
string | Филиал (частичное совпадение) |
place |
string | Помещение (частичное совпадение) |
user |
string | Пользователь (по username или ФИО, частичное совпадение) |
responsible |
string | Ответственный (по username или ФИО, частичное совпадение) |
serial_number |
string | Серийный номер (частичное совпадение) |
inventory_number |
string | Инвентарный номер (частичное совпадение) |
inventory_number2 |
string | Дополнительный инвентарный номер (частичное совпадение) |
comment |
string | Комментарий (частичное совпадение) |
price |
string | Цена (частичное совпадение) |
supplier |
string | Поставщик (частичное совпадение) |
guarantee |
string | Гарантия (частичное совпадение) |
os_name |
string | Операционная система (частичное совпадение) |
user_agent |
string | Агент (частичное совпадение) |
domain |
string | Домен (частичное совпадение) |
Пример фильтрации по нескольким полям
curl -X POST http://<your-server>/api/v1/computers/list/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"status": "Резерв",
"place": "Office A",
"manufacturer": "Dell"
},
"size": 50
}'
Доступные поля для сортировки
| Поле | Описание |
|---|---|
id |
ID компьютера |
dns_name |
Сетевое имя |
serial_number |
Серийный номер |
inventory_number |
Инвентарный номер |
inventory_number2 |
Дополнительный инвентарный номер |
status |
Статус |
name__name |
Название модели |
name__manufacturer__name |
Производитель |
name__ce_type__name |
Тип техники |
place__branch__name |
Название филиала |
place__name |
Помещение |
user__username |
Пользователь |
responsible__username |
Ответственный |
comment |
Комментарий |
price |
Цена |
supplier__name |
Поставщик |
pur_date |
Дата покупки |
guarantee |
Гарантия |
end_warranty |
Дата окончания гарантии |
prod_year |
Год выпуска |
date_connect |
Дата подключения |
os_name__name |
Операционная система |
user_agent |
Агент |
domain__name |
Домен |
date_added |
Дата добавления |
date_change |
Дата изменения |
Для сортировки по убыванию добавьте префикс -:
{
"sort": "-date_added",
"size": 20
}
Пример ответа при ошибке пагинации
Код состояния: 400 Bad Request
{
"detail": [
{
"msg": "Form filling error.",
"type": "form_error",
"extra": "Invalid pagination parameters"
}
]
}
Пример ответа при неверном поле сортировки
Код состояния: 400 Bad Request
{
"detail": [
{
"msg": "Form filling error.",
"type": "form_error",
"extra": "Invalid sort field"
}
]
}
POST /api/v1/computers/
Создание новой записи о компьютере.
Назначение
Используется для добавления нового компьютера в базу данных. После успешного создания генерируется событие в журнале аудита.
HTTP-метод
POST
Параметры запроса
Тело запроса должно быть в формате JSON. Все поля необязательные.
| Поле | Тип | Описание |
|---|---|---|
serial_number |
string | Серийный номер |
inventory_number |
string | Инвентарный номер |
inventory_number2 |
string | Дополнительный инвентарный номер |
name |
integer | ID модели компьютера |
status |
string | Код статуса (1–7, передаётся как строка) |
place |
integer | ID помещения |
user |
integer | ID пользователя |
responsible |
integer | ID ответственного |
dns_name |
string | Сетевое имя |
supplier |
integer | ID поставщика |
comment |
string | Комментарий |
price |
string | Цена в копейках (например, "150000" для 1500.00) |
pur_date |
string | Дата покупки (DD.MM.YYYY) |
guarantee |
string | Гарантия |
end_warranty |
string | Дата окончания гарантии (DD.MM.YYYY) |
prod_year |
string | Год выпуска (целое число ≥ 1970) |
domain |
integer | ID домена |
Формат запроса
Content-Type: application/json
Коды состояния HTTP
| Код | Описание |
|---|---|
200 OK |
Компьютер успешно создан |
400 Bad Request |
Ошибка валидации данных |
401 Unauthorized |
Токен недействителен или истёк |
403 Forbidden |
Недостаточно прав для операции |
500 Internal Server Error |
Внутренняя ошибка сервера |
Пример запроса (curl)
curl -X POST http://<your-server>/api/v1/computers/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"serial_number": "SN-2025-001",
"inventory_number": "INV-2025-0001",
"name": 15,
"status": "2",
"place": 5,
"user": 10,
"responsible": 10,
"dns_name": "ws-001.corp.local",
"comment": "Новая рабочая станция",
"price": "150000",
"pur_date": "15.01.2025",
"guarantee": "3 года",
"end_warranty": "15.01.2028",
"prod_year": "2025",
"domain": 3
}'
Пример успешного ответа
Код состояния: 200 OK
{
"id": 151
}
Пример ответа при ошибке валидации
Код состояния: 400 Bad Request
{
"name": [
{
"message": "Выберите корректный вариант. Вашего варианта нет среди допустимых значений.",
"code": "invalid_choice"
}
],
"status": [
{
"message": "Выберите корректный вариант. 999 нет среди допустимых значений.",
"code": "invalid_choice"
}
]
}
Пример ответа при превышении лимита
Код состояния: 400 Bad Request
{
"detail": [
{
"msg": "A limit on the number of objects. Buy the professional version.",
"type": "free_limit"
}
]
}
GET /api/v1/computers/{pk}/
Получение данных отдельного компьютера по идентификатору.
Назначение
Используется для получения полной информации о конкретном компьютере. Ответ содержит сырые имена полей базы данных.
HTTP-метод
GET
Параметры запроса
| Параметр | Тип | Расположение | Описание |
|---|---|---|---|
pk |
integer | URL | Первичный ключ компьютера |
Коды состояния HTTP
| Код | Описание |
|---|---|
200 OK |
Данные успешно получены |
401 Unauthorized |
Токен недействителен или истёк |
403 Forbidden |
Недостаточно прав для операции |
404 Not Found |
Компьютер не найден |
Пример запроса (curl)
curl -X GET http://<your-server>/api/v1/computers/151/ \
-H "Authorization: Bearer <access_token>"
Пример успешного ответа
Код состояния: 200 OK
{
"id": 151,
"dns_name": "ws-001.corp.local",
"serial_number": "SN-2025-001",
"inventory_number": "INV-2025-0001",
"status": 2,
"name__name": "Dell XPS 15",
"name__manufacturer__name": "Dell",
"name__ce_type__name": "Ноутбук",
"place__branch__name": "Здание 1",
"place__branch": 1,
"place__name": "1 этаж",
"place__id": 10,
"date_change": "2025-02-20T14:45:00.000000Z",
"user__username": "ivanov",
"user__fio": "Иванов Иван Иванович",
"responsible__username": "ivanov",
"responsible__fio": "Иванов Иван Иванович",
"comment": "Новая рабочая станция",
"inventory_number2": "",
"price": 150000,
"supplier__name": "Tech Supplier",
"pur_date": "2025-01-15",
"guarantee": "3 года",
"end_warranty": "2028-01-15",
"prod_year": "2025-01-01",
"date_connect": "2025-01-15T10:05:00.000000Z",
"os_name__manufacturer__name": "Microsoft Corporation",
"os_name__name": "Windows 10 Pro",
"user_agent": "Offline inventory.",
"domain__name": "WORKGROUP",
"date_added": "2025-01-15T10:00:00.000000Z"
}
Пример ответа при отсутствии ресурса
Код состояния: 404 Not Found
{
"detail": [
{
"msg": "Resource not found.",
"type": "not_found"
}
]
}
PATCH /api/v1/computers/{pk}/
Частичное обновление данных компьютера.
Назначение
Используется для обновления отдельных полей компьютера. Поля, не указанные в запросе, остаются без изменений. При обновлении генерируются события в журнале аудита для каждого изменённого поля.
HTTP-метод
PATCH
Параметры запроса
Тело запроса должно быть в формате JSON. Указываются только поля, требующие обновления.
| Поле | Тип | Описание |
|---|---|---|
serial_number |
string | Серийный номер |
inventory_number |
string | Инвентарный номер |
inventory_number2 |
string | Дополнительный инвентарный номер |
name |
integer | ID модели компьютера |
status |
string | Код статуса (1–7, передаётся как строка) |
place |
integer | ID помещения |
user |
integer | ID пользователя |
responsible |
integer | ID ответственного |
dns_name |
string | Сетевое имя |
supplier |
integer | ID поставщика |
comment |
string | Комментарий |
price |
string | Цена в копейках |
pur_date |
string | Дата покупки (DD.MM.YYYY) |
guarantee |
string | Гарантия |
end_warranty |
string | Дата окончания гарантии (DD.MM.YYYY) |
prod_year |
string | Год выпуска (целое число ≥ 1970) |
domain |
integer | ID домена |
Коды состояния HTTP
| Код | Описание |
|---|---|
204 No Content |
Компьютер успешно обновлён |
400 Bad Request |
Ошибка валидации данных |
401 Unauthorized |
Токен недействителен или истёк |
403 Forbidden |
Недостаточно прав для операции |
404 Not Found |
Компьютер не найден |
Пример запроса (curl)
curl -X PATCH http://<your-server>/api/v1/computers/151/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"comment": "Обновлённый комментарий",
"status": "3",
"price": "200000"
}'
Пример успешного ответа
Код состояния: 204 No Content
(пустое тело ответа)
Пример обновления нескольких полей
curl -X PATCH http://<your-server>/api/v1/computers/151/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"place": 10,
"user": 25,
"responsible": 25,
"comment": "Перемещён в новый офис"
}'
Пример ответа при ошибке валидации
Код состояния: 400 Bad Request
{
"status": [
{
"message": "Выберите корректный вариант. 999 нет среди допустимых значений.",
"code": "invalid_choice"
}
]
}
Пример ответа при несуществующем поле
Код состояния: 400 Bad Request
{
"detail": [
{
"msg": "Nonexistent field.",
"type": "nonexistent_field"
}
]
}
Пример ответа при неверном JSON
Код состояния: 400 Bad Request
{
"detail": [
{
"msg": "Form filling error.",
"type": "form_error",
"extra": "Invalid JSON"
}
]
}
PUT /api/v1/computers/{pk}/
Полное обновление данных компьютера.
Назначение
Используется для обновления данных компьютера. Указываются только поля, требующие обновления. Поля, не указанные в запросе, остаются без изменений. При обновлении генерируются события в журнале аудита для каждого изменённого поля.
HTTP-метод
PUT
Параметры запроса
Тело запроса должно быть в формате JSON. Указываются только поля, требующие обновления.
| Поле | Тип | Описание |
|---|---|---|
serial_number |
string | Серийный номер |
inventory_number |
string | Инвентарный номер |
inventory_number2 |
string | Дополнительный инвентарный номер |
name |
integer | ID модели компьютера |
status |
string | Код статуса (1–7, передаётся как строка) |
place |
integer | ID помещения |
user |
integer | ID пользователя |
responsible |
integer | ID ответственного |
dns_name |
string | Сетевое имя |
supplier |
integer | ID поставщика |
comment |
string | Комментарий |
price |
string | Цена в копейках |
pur_date |
string | Дата покупки (DD.MM.YYYY) |
guarantee |
string | Гарантия |
end_warranty |
string | Дата окончания гарантии (DD.MM.YYYY) |
prod_year |
string | Год выпуска (целое число ≥ 1970) |
domain |
integer | ID домена |
Коды состояния HTTP
| Код | Описание |
|---|---|
204 No Content |
Компьютер успешно обновлён |
400 Bad Request |
Ошибка валидации данных |
401 Unauthorized |
Токен недействителен или истёк |
403 Forbidden |
Недостаточно прав для операции |
404 Not Found |
Компьютер не найден |
Пример запроса (curl)
curl -X PUT http://<your-server>/api/v1/computers/151/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"status": "3",
"comment": "Обновлён через PUT"
}'
Пример успешного ответа
Код состояния: 204 No Content
(пустое тело ответа)
DELETE /api/v1/computers/{pk}/
Удаление записи о компьютере.
Назначение
Используется для удаления компьютера из базы данных. При удалении генерируется событие в журнале аудита.
HTTP-метод
DELETE
Параметры запроса
| Параметр | Тип | Расположение | Описание |
|---|---|---|---|
pk |
integer | URL | Первичный ключ компьютера |
Коды состояния HTTP
| Код | Описание |
|---|---|
204 No Content |
Компьютер успешно удалён |
401 Unauthorized |
Токен недействителен или истёк |
403 Forbidden |
Недостаточно прав для операции |
404 Not Found |
Компьютер не найден |
Пример запроса (curl)
curl -X DELETE http://<your-server>/api/v1/computers/151/ \
-H "Authorization: Bearer <access_token>"
Пример успешного ответа
Код состояния: 204 No Content
(пустое тело ответа)
Пример ответа при отсутствии ресурса
Код состояния: 404 Not Found
{
"detail": [
{
"msg": "Resource not found.",
"type": "not_found"
}
]
}
Статусы компьютеров
Система использует следующие статусы для компьютеров:
| Код | Статус | Описание |
|---|---|---|
| 1 | Unused | Компьютер в резерве |
| 2 | In use | Компьютер установлен и используется |
| 3 | Broken | Компьютер неисправен |
| 4 | Repair | Компьютер в ремонте |
| 5 | Decommission | Компьютер на списании |
| 6 | Decommissioned | Компьютер списан |
| 7 | Unallocated | Статус не определён |
Примечание: Статусы в запросах фильтрации передаются в виде текстовых названий на русском языке (например,
Резерв,Установленные,Сломанные). В поляхstatusобъекта ответа LIST возвращается текстовое название. В поляхstatusответа GET detail — числовой код.
Журнал аудита
При выполнении операций создания, обновления и удаления компьютеров автоматически создаются записи в журнале событий.
Типы событий
| Событие | Тип события | Описание |
|---|---|---|
| Создание компьютера | COMP_ADD |
Добавлен новый компьютер |
| Изменение данных | COMP_CI |
Изменены поля компьютера |
| Изменение помещения | COMP_PLACE |
Изменено помещение |
| Удаление компьютера | COMP_DEL |
Компьютер удалён |
Отслеживаемые поля
При изменении следующих полей создаются отдельные записи в журнале:
dns_name— сетевое имяserial_number— серийный номерinventory_number— инвентарный номерinventory_number2— дополнительный инвентарный номерstatus— статусplace— помещениеuser— пользовательresponsible— ответственныйcomment— комментарийprice— ценаsupplier— поставщикpur_date— дата покупкиguarantee— гарантияend_warranty— дата окончания гарантииprod_year— год выпускаdomain— домен
Обработка ошибок
Единый формат ошибок
Все ошибки API возвращаются в едином формате:
{
"detail": [
{
"msg": "Описание ошибки",
"type": "код_ошибки"
}
]
}
Типовые ошибки
| Ошибка | Тип | HTTP-код | Причина | Решение |
|---|---|---|---|---|
| Resource not found | not_found |
404 | Ресурс не найден | Проверьте идентификатор объекта |
| Nonexistent field | nonexistent_field |
400 | Указано несуществующее поле | Проверьте список допустимых полей |
| Form filling error | form_error |
400 | Неверный формат JSON или ошибка валидации | Проверьте тело запроса |
| A limit on the number of objects | free_limit |
400 | Превышен лимит компьютеров по лицензии | Докупите лицензии |
| Server error | server_error |
500 | Внутренняя ошибка сервера | Обратитесь к администратору |
| Authentication required | auth_required |
401 | Токен отсутствует | Получите JWT-токен |
| Login permission required | login_required |
403 | Нет права на вход | Обратитесь к администратору |
| Permission denied | permission_denied |
403 | Недостаточно прав | Обратитесь к администратору |
Ошибки валидации полей
Ошибки валидации возвращаются с указанием имени поля:
{
"field_name": [
{
"message": "Описание ошибки",
"code": "код_ошибки"
}
]
}
Сценарии использования
Получение списка всех компьютеров
curl -X POST http://<your-server>/api/v1/computers/list/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"size": 100}'
Поиск компьютеров по статусу и помещению
curl -X POST http://<your-server>/api/v1/computers/list/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"status": "Резерв",
"place": "Office A"
},
"sort": "name__name",
"page": 1,
"size": 20
}'
Создание нового компьютера
curl -X POST http://<your-server>/api/v1/computers/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"serial_number": "SN-NEW-001",
"inventory_number": "INV-NEW-001",
"name": 15,
"status": "1",
"place": 5,
"user": 10,
"responsible": 10
}'
Частичное обновление статуса и комментария
curl -X PATCH http://<your-server>/api/v1/computers/151/ \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"status": "4",
"comment": "Отправлен в ремонт"
}'
Удаление компьютера
curl -X DELETE http://<your-server>/api/v1/computers/151/ \
-H "Authorization: Bearer <access_token>"
Рекомендации
Пагинация
- Максимальный размер страницы — 100 записей
- При запросе большего значения размер автоматически ограничивается
- Для получения больших объёмов данных используйте последовательную пагинацию
Сортировка
- По умолчанию сортировка по
-id(новые записи первыми) - Для сортировки по убыванию используйте префикс
- - Используйте только разрешённые поля для сортировки
Фильтрация
- Пустой объект фильтра
{}возвращает все записи - Несколько фильтров комбинируются по логическому И
- Текстовые фильтры поддерживают частичное совпадение
Безопасность
- Не сохраняйте токены в localStorage браузера
- Используйте HTTPS для всех запросов к API
- Регулярно обновляйте токены доступа