Перейти к содержанию

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

Документация описывает работу с 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
  • Регулярно обновляйте токены доступа