Управление компьютерами

Документация описывает работу с API для управления компьютерами в системе Severcart.

Назначение

API управления компьютерами предоставляет конечные точки для:

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

Все операции выполняются через REST API с использованием JSON для передачи данных.

Базовый URL API

Все запросы к API компьютеров отправляются по адресу:

/api/v1/computers/

Полный URL формируется путём добавления пути к базовому адресу сервера. Например:

https://<your-server>/api/v1/computers/

Аутентификация

Все конечные точки API требуют JWT-аутентификации. Токен передаётся в заголовке Authorization:

Authorization: Bearer <access-токен>

Подробнее о получении токенов см. документацию JWT-аутентификация.

Права доступа

Для работы с API компьютеров требуются следующие права:

Операция	Право	Код права
Просмотр списка	`ro_ce`	2048
Создание	`ap_ce`	4096
Редактирование	`rw_ce`	8192
Удаление	`er_ce`	16384

Права назначаются через группы пользователей в административной панели.

Конечные точки

Метод	URL	Описание
`POST`	`/api/v1/computers/list/`	Получение списка компьютеров
`POST`	`/api/v1/computers/`	Создание компьютера
`GET`	`/api/v1/computers/{pk}/`	Получение данных компьютера
`PATCH`	`/api/v1/computers/{pk}/`	Частичное обновление
`PUT`	`/api/v1/computers/{pk}/`	Полное обновление
`DELETE`	`/api/v1/computers/{pk}/`	Удаление компьютера

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 https://<your-server>/api/v1/computers/list/ \
  -H "Authorization: Bearer <access-токен>" \
  -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",
      "status": "Резерв",
      "name": "Dell XPS 13",
      "manufacturer": "Dell",
      "ce_type": "Ноутбук",
      "place": "Office A",
      "user": "ivanov",
      "responsible": "petrov",
      "date_added": "2025-01-15",
      "date_change": "2025-02-20",
      "price": 1500.00,
      "supplier": "Tech Supplier",
      "comment": "Рабочая станция"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 150,
    "pages": 8
  }
}

Доступные поля для фильтрации

Поле	Тип	Описание
`status`	string	Статус компьютера (Резерв, Установленные, Сломанные, В ремонте, Списан)
`name`	string	Название модели (точное совпадение)
`place`	string	Помещение (точное совпадение)
`inventory_number`	string	Инвентарный номер (частичное совпадение)
`serial_number`	string	Серийный номер (частичное совпадение)
`user`	string	Пользователь (по имени пользователя)
`responsible`	string	Ответственный (по имени пользователя)
`manufacturer`	string	Производитель
`ce_type`	string	Тип техники
`domain`	string	Домен

Пример фильтрации по нескольким полям

curl -X POST https://<your-server>/api/v1/computers/list/ \
  -H "Authorization: Bearer <access-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "status": "Резерв",
      "place": "Office A",
      "manufacturer": "Dell"
    },
    "size": 50
  }'

Доступные поля для сортировки

Поле	Описание
`id`	ID компьютера
`name__name`	Название модели
`inventory_number`	Инвентарный номер
`serial_number`	Серийный номер
`status`	Статус
`place__name`	Помещение
`user__username`	Пользователь
`responsible__username`	Ответственный
`date_added`	Дата добавления
`price`	Цена
`pur_date`	Дата покупки
`name__manufacturer__name`	Производитель
`name__ce_type__name`	Тип техники
`domain__name`	Домен

Для сортировки по убыванию добавьте префикс -:

{
  "sort": "-date_added",
  "size": 20
}

Пример ответа при ошибке пагинации

Код состояния: 400 Bad Request

{
  "error_code": "form_error",
  "extra": "Invalid pagination parameters"
}

Пример ответа при неверном поле сортировки

Код состояния: 400 Bad Request

{
  "error_code": "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`	integer	Да	Статус (1–7)
`place`	integer	Да	ID помещения
`user`	integer	Да	ID пользователя
`responsible`	integer	Да	ID ответственного
`dns_name`	string	Нет	Сетевое имя
`supplier`	integer	Нет	ID поставщика
`comment`	string	Нет	Комментарий
`price`	string	Нет	Цена (в формате "1500.00")
`pur_date`	string	Нет	Дата покупки (YYYY-MM-DD)
`guarantee`	string	Нет	Гарантия
`end_warranty`	string	Нет	Дата окончания гарантии (YYYY-MM-DD)
`prod_year`	string	Нет	Год выпуска
`domain`	integer	Нет	ID домена

Формат запроса

Content-Type: application/json

Коды состояния HTTP

Код	Описание
`201 Created`	Компьютер успешно создан
`400 Bad Request`	Ошибка валидации данных
`401 Unauthorized`	Токен недействителен или истёк
`403 Forbidden`	Недостаточно прав для операции
`409 Conflict`	Превышен лимит лицензий
`500 Internal Server Error`	Внутренняя ошибка сервера

Пример запроса (curl)

curl -X POST https://<your-server>/api/v1/computers/ \
  -H "Authorization: Bearer <access-токен>" \
  -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": "1500.00",
    "pur_date": "2025-01-15",
    "guarantee": "3 года",
    "end_warranty": "2028-01-15",
    "prod_year": "2025",
    "domain": 3
  }'

Пример успешного ответа

Код состояния: 201 Created

{
  "id": 151
}

Пример ответа при ошибке валидации

Код состояния: 400 Bad Request

{
  "status": [
    "Выберите допустимое значение. 22 нет среди допустимых значений."
  ]
}

Пример ответа при превышении лимита

Код состояния: 409 Conflict

{
  "error_code": "free_limit",
  "message": "Превышен лимит компьютеров по лицензии"
}

GET /api/v1/computers/{pk}/

Получение данных отдельного компьютера по идентификатору.

Назначение

Используется для получения полной информации о конкретном компьютере.

HTTP-метод

GET

Параметры запроса

Параметр	Тип	Расположение	Описание
`pk`	integer	URL	Первичный ключ компьютера

Коды состояния HTTP

Код	Описание
`200 OK`	Данные успешно получены
`401 Unauthorized`	Токен недействителен или истёк
`403 Forbidden`	Недостаточно прав для операции
`404 Not Found`	Компьютер не найден

Пример запроса (curl)

curl -X GET https://<your-server>/api/v1/computers/151/ \
  -H "Authorization: Bearer <access-токен>"

Пример успешного ответа

Код состояния: 200 OK

{
  "id": 151,
  "dns_name": "ws-001.corp.local",
  "serial_number": "SN-2025-001",
  "inventory_number": "INV-2025-0001",
  "inventory_number2": null,
  "status": "Установленные",
  "name": "Dell XPS 15",
  "manufacturer": "Dell",
  "ce_type": "Ноутбук",
  "place": "Office 101",
  "user": "ivanov",
  "responsible": "ivanov",
  "date_added": "2025-01-15T10:30:00Z",
  "date_change": "2025-02-20T14:45:00Z",
  "price": 1500.00,
  "supplier": "Tech Supplier",
  "comment": "Новая рабочая станция",
  "pur_date": "2025-01-15",
  "guarantee": "3 года",
  "end_warranty": "2028-01-15",
  "prod_year": "2025",
  "domain": "corp.local"
}

Пример ответа при отсутствии ресурса

Код состояния: 404 Not Found

{
  "error_code": "not_found",
  "message": "Resource not found."
}

PATCH /api/v1/computers/{pk}/

Частичное обновление данных компьютера.

Назначение

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

HTTP-метод

PATCH

Параметры запроса

Тело запроса должно быть в формате JSON. Указываются только поля, требующие обновления.

Поле	Тип	Описание
`serial_number`	string	Серийный номер
`inventory_number`	string	Инвентарный номер
`inventory_number2`	string	Дополнительный инвентарный номер
`name`	integer	ID модели компьютера
`status`	integer	Статус (1–7)
`place`	integer	ID помещения
`user`	integer	ID пользователя
`responsible`	integer	ID ответственного
`dns_name`	string	Сетевое имя
`supplier`	integer	ID поставщика
`comment`	string	Комментарий
`price`	string	Цена (в формате "1500.00")
`pur_date`	string	Дата покупки (YYYY-MM-DD)
`guarantee`	string	Гарантия
`end_warranty`	string	Дата окончания гарантии (YYYY-MM-DD)
`prod_year`	string	Год выпуска
`domain`	integer	ID домена

Коды состояния HTTP

Код	Описание
`204 No Content`	Компьютер успешно обновлён
`400 Bad Request`	Ошибка валидации данных
`401 Unauthorized`	Токен недействителен или истёк
`403 Forbidden`	Недостаточно прав для операции
`404 Not Found`	Компьютер не найден

Пример запроса (curl)

curl -X PATCH https://<your-server>/api/v1/computers/151/ \
  -H "Authorization: Bearer <access-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Обновлённый комментарий",
    "status": 3,
    "price": "2000.00"
  }'

Пример успешного ответа

Код состояния: 204 No Content

(пустое тело ответа)

Пример обновления нескольких полей

curl -X PATCH https://<your-server>/api/v1/computers/151/ \
  -H "Authorization: Bearer <access-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "place": 10,
    "user": 25,
    "responsible": 25,
    "comment": "Перемещён в новый офис"
  }'

Пример ответа при ошибке валидации

Код состояния: 400 Bad Request

{
  "status": [
    "Выберите допустимое значение. 999 нет среди допустимых значений."
  ]
}

PUT /api/v1/computers/{pk}/

Полное обновление данных компьютера.

Назначение

Используется для полной замены данных компьютера. В отличие от PATCH, метод PUT требует предоставления всех обязательных полей. Поля, не указанные в запросе, могут быть сброшены или вызовут ошибку валидации.

HTTP-метод

PUT

Параметры запроса

Тело запроса должно быть в формате JSON и содержать все обязательные поля.

Поле	Тип	Обязательный	Описание
`serial_number`	string	Да	Серийный номер
`inventory_number`	string	Да	Инвентарный номер
`inventory_number2`	string	Нет	Дополнительный инвентарный номер
`name`	integer	Да	ID модели компьютера
`status`	integer	Да	Статус (1–7)
`place`	integer	Да	ID помещения
`user`	integer	Да	ID пользователя
`responsible`	integer	Да	ID ответственного
`dns_name`	string	Да	Сетевое имя
`supplier`	integer	Нет	ID поставщика
`comment`	string	Нет	Комментарий
`price`	string	Нет	Цена
`pur_date`	string	Нет	Дата покупки
`guarantee`	string	Нет	Гарантия
`end_warranty`	string	Нет	Дата окончания гарантии
`prod_year`	string	Нет	Год выпуска
`domain`	integer	Нет	ID домена

Коды состояния HTTP

Код	Описание
`204 No Content`	Компьютер успешно обновлён
`400 Bad Request`	Ошибка валидации или неполные данные
`401 Unauthorized`	Токен недействителен или истёк
`403 Forbidden`	Недостаточно прав для операции
`404 Not Found`	Компьютер не найден

Пример запроса (curl)

curl -X PUT https://<your-server>/api/v1/computers/151/ \
  -H "Authorization: Bearer <access-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN-2025-001",
    "inventory_number": "INV-2025-0001",
    "inventory_number2": "ACC-001",
    "name": 15,
    "status": 3,
    "place": 10,
    "user": 25,
    "responsible": 25,
    "dns_name": "ws-001.corp.local",
    "supplier": 5,
    "comment": "Полностью обновлённый компьютер",
    "price": "2000.00",
    "pur_date": "2024-06-01",
    "guarantee": "2 года",
    "end_warranty": "2026-06-01",
    "prod_year": "2024",
    "domain": 3
  }'

Пример ответа при отсутствии обязательных полей

Код состояния: 400 Bad Request

{
  "error_code": "incomplete_object"
}

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 https://<your-server>/api/v1/computers/151/ \
  -H "Authorization: Bearer <access-токен>"

Пример успешного ответа

Код состояния: 204 No Content

(пустое тело ответа)

Пример ответа при отсутствии ресурса

Код состояния: 404 Not Found

{
  "error_code": "not_found"
}

Статусы компьютеров

Система использует следующие статусы для компьютеров:

Код	Статус	Описание
1	Резерв	Компьютер в резерве
2	Установленные	Компьютер установлен и используется
3	Сломанные	Компьютер неисправен
4	В ремонте	Компьютер в ремонте
5	Списан	Компьютер списан
6	Списано	Компьютер списан (альтернативный статус)
7	Не распределено	Статус не определён

Журнал аудита

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

Типы событий

Событие	Тип события	Описание
Создание компьютера	`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 — домен

Обработка ошибок

Типовые ошибки

Ошибка	Причина	Решение
`400 Bad Request`	Неверный формат JSON или ошибка валидации	Проверьте тело запроса и поля
`401 Unauthorized`	Токен недействителен или истёк	Обновите токен доступа
`403 Forbidden`	Недостаточно прав	Обратитесь к администратору
`404 Not Found`	Ресурс не найден	Проверьте идентификатор объекта
`409 Conflict`	Превышен лимит лицензий	Докупите лицензии
`500 Internal Server Error`	Внутренняя ошибка сервера	Обратитесь к администратору

Формат ответов об ошибках

Ошибки валидации полей:

{
  "field_name": [
    "Описание ошибки поля"
  ]
}

Системные ошибки:

{
  "error_code": "код_ошибки",
  "extra": "Дополнительная информация"
}

Сценарии использования

Получение списка всех компьютеров

curl -X POST https://<your-server>/api/v1/computers/list/ \
  -H "Authorization: Bearer <access-токен>" \
  -H "Content-Type: application/json" \
  -d '{"size": 100}'

Поиск компьютеров по статусу и помещению

curl -X POST https://<your-server>/api/v1/computers/list/ \
  -H "Authorization: Bearer <access-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "status": "Резерв",
      "place": "Office A"
    },
    "sort": "name__name",
    "page": 1,
    "size": 20
  }'

Создание нового компьютера

curl -X POST https://<your-server>/api/v1/computers/ \
  -H "Authorization: Bearer <access-токен>" \
  -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 https://<your-server>/api/v1/computers/151/ \
  -H "Authorization: Bearer <access-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 4,
    "comment": "Отправлен в ремонт"
  }'

Удаление компьютера

curl -X DELETE https://<your-server>/api/v1/computers/151/ \
  -H "Authorization: Bearer <access-токен>"

Управление компьютерами

Назначение

Базовый URL API

Аутентификация

Права доступа

Конечные точки

POST /api/v1/computers/list/

Назначение

HTTP-метод

Параметры запроса

Формат запроса

Коды состояния HTTP

Пример запроса (curl)

Пример успешного ответа

Доступные поля для фильтрации

Пример фильтрации по нескольким полям

Доступные поля для сортировки

Пример ответа при ошибке пагинации

Пример ответа при неверном поле сортировки

POST /api/v1/computers/

Назначение

HTTP-метод

Параметры запроса

Формат запроса

Коды состояния HTTP

Пример запроса (curl)

Пример успешного ответа

Пример ответа при ошибке валидации

Пример ответа при превышении лимита

GET /api/v1/computers/{pk}/

Назначение

HTTP-метод

Параметры запроса

Коды состояния HTTP

Пример запроса (curl)

Пример успешного ответа

Пример ответа при отсутствии ресурса

PATCH /api/v1/computers/{pk}/

Назначение

HTTP-метод

Параметры запроса

Коды состояния HTTP

Пример запроса (curl)

Пример успешного ответа

Пример обновления нескольких полей

Пример ответа при ошибке валидации

PUT /api/v1/computers/{pk}/

Назначение

HTTP-метод

Параметры запроса

Коды состояния HTTP

Пример запроса (curl)

Пример ответа при отсутствии обязательных полей

DELETE /api/v1/computers/{pk}/

Назначение

HTTP-метод

Параметры запроса

Коды состояния HTTP

Пример запроса (curl)

Пример успешного ответа

Пример ответа при отсутствии ресурса

Статусы компьютеров

Журнал аудита

Типы событий

Отслеживаемые поля

Обработка ошибок

Типовые ошибки

Формат ответов об ошибках

Сценарии использования

Получение списка всех компьютеров

Поиск компьютеров по статусу и помещению

Создание нового компьютера

Частичное обновление статуса и комментария

Удаление компьютера

Рекомендации

Пагинация

Сортировка

Фильтрация

Безопасность