Публичное API Severcart

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

Назначение документации

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

REST API Severcart предоставляет возможности для:

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

Архитектура API

API построено по архитектуре REST и использует стандартные HTTP-методы для выполнения операций над ресурсами.

Версионирование

API использует версионирование через URL. На данный момент доступна версия v1:

/api/v1/

При выпуске новых версий предыдущие версии поддерживаются в соответствии с политикой совместимости.

Базовый URL

Все запросы к API выполняются относительно базового URL сервера Severcart:

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

Формат данных

• Запросы: JSON (application/json)
• Ответы: JSON (application/json)

Кодировка

Все данные передаются в кодировке UTF-8.

Доступные разделы API

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

Все конечные точки API требуют аутентификации с использованием JWT-токенов.

Получение токена

Для получения токена отправьте POST-запрос на конечную точку аутентификации:

curl -X POST https://<your-server>/api/v1/accounts/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "ваш_логин",
    "password": "ваш_пароль"
  }'

Использование токена

Полученный access-токен передаётся в заголовке Authorization:

curl -X GET https://<your-server>/api/v1/computers/1/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Время жизни токенов

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

HTTP-методы

API использует стандартные HTTP-методы для выполнения операций:

Идемпотентность

Идемпотентные операции могут быть выполнены многократно с одинаковым результатом. Это важно для реализации механизмов повторных попыток при сбоях сети.

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

API возвращает стандартные коды состояния HTTP:

Успешные запросы

Ошибки клиента

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

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

Заголовки

Обязательные заголовки для большинства запросов:

Content-Type: application/json
Authorization: Bearer <access-токен>

Тело запроса

Данные передаются в формате JSON:

{
  "field_name": "value",
  "another_field": 123
}

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

Успешные ответы

Структура успешного ответа зависит от конечной точки.

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

{
  "items": [
    {
      "id": 1,
      "name": "Компьютер 1"
    },
    {
      "id": 2,
      "name": "Компьютер 2"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 150,
    "pages": 8
  }
}

Пример ответа с данными ресурса:

{
  "id": 1,
  "dns_name": "pc-001.corp.local",
  "serial_number": "SN123456",
  "status": "Установленные"
}

Ответы с ошибками

Ошибки возвращаются в едином формате:

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

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

{
  "field_name": [
    "Описание ошибки первого поля",
    "Описание ошибки второго поля"
  ],
  "another_field": [
    "Описание ошибки"
  ]
}

Пагинация

Для конечных точек, возвращающих списки ресурсов, используется пагинация.

Параметры пагинации

Структура ответа

{
  "items": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 150,
    "pages": 8
  }
}

Пример запроса с пагинацией

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

Сортировка

Сортировка задаётся через параметр sort в теле запроса.

Направления сортировки

Примеры

Сортировка по возрастанию:

{
  "sort": "id"
}

Сортировка по убыванию:

{
  "sort": "-date_added"
}

Сортировка по вложенным полям:

{
  "sort": "name__manufacturer__name"
}

Фильтрация

Фильтрация задаётся через объект filter в теле запроса.

Пример фильтрации

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

Логика фильтрации

• Несколько фильтров комбинируются по логическому И
• Пустой объект {} возвращает все записи
• Текстовые фильтры поддерживают частичное совпадение

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

Стратегии повторных попыток

При получении ошибок 5xx рекомендуется реализовать механизм повторных попыток с экспоненциальной задержкой:

import time
import requests

def request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        if response.status_code < 500:
            return response
        time.sleep(2 ** attempt)  # Экспоненциальная задержка
    return response

Логирование ошибок

Рекомендуется логировать:

• Код состояния HTTP
• Тело ответа с ошибкой
• Временную метку
• Идентификатор запроса (если доступен)

Ограничения

Лимиты запросов

Лицензионные ограничения

Количество компьютеров в системе ограничено лицензией. При превышении лимитa создание новых записей возвращает ошибку 409 Conflict.

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

Рекомендации по защите токенов

1. Не сохраняйте токены в localStorage — используйте httpOnly cookies или безопасное серверное хранилище
2. Используйте HTTPS — все запросы должны выполняться только по защищённому протоколу
3. Регулярно обновляйте токены — используйте refresh-токен для получения новой пары
4. Отозывайте токены при завершении сеанса или компрометации

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

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

Примеры использования

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

# Получение первой страницы по 20 записей
curl -X POST https://<your-server>/api/v1/computers/list/ \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{}'

Пример 2: Создание компьютера

curl -X POST https://<your-server>/api/v1/computers/ \
  -H "Authorization: Bearer <токен>" \
  -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
  }'

Пример 3: Обновление статуса компьютера

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

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

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

Пример 5: Полная интеграция на Python

import requests

BASE_URL = "https://<your-server>/api/v1"

def get_token(username, password):
    response = requests.post(
        f"{BASE_URL}/accounts/token/",
        json={"username": username, "password": password}
    )
    response.raise_for_status()
    return response.json()["access"]

def get_computers(token, status=None):
    headers = {"Authorization": f"Bearer {token}"}
    data = {"filter": {}, "size": 100}
    if status:
        data["filter"]["status"] = status
    response = requests.post(
        f"{BASE_URL}/computers/list/",
        headers=headers,
        json=data
    )
    response.raise_for_status()
    return response.json()

def create_computer(token, computer_data):
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.post(
        f"{BASE_URL}/computers/",
        headers=headers,
        json=computer_data
    )
    response.raise_for_status()
    return response.json()

# Использование
token = get_token("admin", "password")
computers = get_computers(token, status="Резерв")
print(f"Найдено компьютеров в резерве: {len(computers['items'])}")

Поддержка и обратная связь

По вопросам работы API обращайтесь:

• Техническая поддержка: support@example.com
• Документация: https:///docs/

Связанные разделы

1. JWT-аутентификация — получение и использование токенов
2. API компьютеров — управление компьютерами
3. Настройка прав доступа — права и роли

История изменений