Skip to content

API

Jump to bottom
n0pashkov edited this page Mar 2, 2025 · 1 revision

API документация

Система заявок предоставляет REST API для взаимодействия с ней. Все эндпоинты API доступны по базовому пути /api/v1/.

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

Для доступа к большинству эндпоинтов API требуется аутентификация с использованием JWT токена. Токен должен быть передан в заголовке Authorization в формате Bearer <token>.

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

POST /api/v1/token

Тело запроса:

{
  "username": "string",
  "password": "string"
}

Ответ:

{
  "access_token": "string",
  "token_type": "bearer"
}

Пользователи

Получение списка пользователей (только для администраторов)

GET /api/v1/users/

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

  • skip (int, опционально): количество пропускаемых записей (для пагинации)
  • limit (int, опционально): максимальное количество возвращаемых записей

Ответ:

[
  {
    "id": 1,
    "email": "user@example.com",
    "username": "string",
    "full_name": "string",
    "is_active": true,
    "role": "user"
  }
]

Создание нового пользователя (только для администраторов)

POST /api/v1/users/

Тело запроса:

{
  "email": "user@example.com",
  "username": "string",
  "password": "string",
  "full_name": "string",
  "role": "user"
}

Ответ:

{
  "id": 1,
  "email": "user@example.com",
  "username": "string",
  "full_name": "string",
  "is_active": true,
  "role": "user"
}

Получение информации о текущем пользователе

GET /api/v1/users/me/

Ответ:

{
  "id": 1,
  "email": "user@example.com",
  "username": "string",
  "full_name": "string",
  "is_active": true,
  "role": "user"
}

Получение информации о пользователе по ID

GET /api/v1/users/{user_id}

Ответ:

{
  "id": 1,
  "email": "user@example.com",
  "username": "string",
  "full_name": "string",
  "is_active": true,
  "role": "user"
}

Обновление пользователя

PUT /api/v1/users/{user_id}

Тело запроса:

{
  "email": "user@example.com",
  "username": "string",
  "password": "string",
  "full_name": "string",
  "role": "user"
}

Ответ:

{
  "id": 1,
  "email": "user@example.com",
  "username": "string",
  "full_name": "string",
  "is_active": true,
  "role": "user"
}

Деактивация пользователя (только для администраторов)

DELETE /api/v1/users/{user_id}

Ответ:

{
  "id": 1,
  "email": "user@example.com",
  "username": "string",
  "full_name": "string",
  "is_active": false,
  "role": "user"
}

Заявки

Получение списка заявок

GET /api/v1/tickets/

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

  • skip (int, опционально): количество пропускаемых записей (для пагинации)
  • limit (int, опционально): максимальное количество возвращаемых записей
  • status (string, опционально): фильтр по статусу заявки
  • priority (string, опционально): фильтр по приоритету заявки
  • category (string, опционально): фильтр по категории оборудования

Ответ:

[
  {
    "id": 1,
    "title": "string",
    "description": "string",
    "status": "new",
    "priority": "medium",
    "category": "string",
    "created_at": "2023-01-01T00:00:00",
    "updated_at": "2023-01-01T00:00:00",
    "user_id": 1,
    "assigned_to": null
  }
]

Создание новой заявки

POST /api/v1/tickets/

Тело запроса:

{
  "title": "string",
  "description": "string",
  "priority": "medium",
  "category": "string"
}

Ответ:

{
  "id": 1,
  "title": "string",
  "description": "string",
  "status": "new",
  "priority": "medium",
  "category": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "user_id": 1,
  "assigned_to": null
}

Получение заявки по ID

GET /api/v1/tickets/{ticket_id}

Ответ:

{
  "id": 1,
  "title": "string",
  "description": "string",
  "status": "new",
  "priority": "medium",
  "category": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "user_id": 1,
  "assigned_to": null
}

Обновление заявки

PUT /api/v1/tickets/{ticket_id}

Тело запроса:

{
  "title": "string",
  "description": "string",
  "priority": "high",
  "status": "in_progress",
  "category": "string",
  "assigned_to_id": 2
}

Ответ:

{
  "id": 1,
  "title": "string",
  "description": "string",
  "status": "in_progress",
  "priority": "high",
  "category": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "user_id": 1,
  "assigned_to": 2
}

Назначение заявки агенту

PUT /api/v1/tickets/{ticket_id}/assign/{agent_id}

Ответ:

{
  "id": 1,
  "title": "string",
  "description": "string",
  "status": "assigned",
  "priority": "medium",
  "category": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "user_id": 1,
  "assigned_to": 2
}

Изменение статуса заявки

PUT /api/v1/tickets/{ticket_id}/status/{status}

Ответ:

{
  "id": 1,
  "title": "string",
  "description": "string",
  "status": "completed",
  "priority": "medium",
  "category": "string",
  "created_at": "2023-01-01T00:00:00",
  "updated_at": "2023-01-01T00:00:00",
  "user_id": 1,
  "assigned_to": 2
}

Комментарии

Получение комментариев к заявке

GET /api/v1/tickets/{ticket_id}/comments/

Ответ:

[
  {
    "id": 1,
    "text": "string",
    "created_at": "2023-01-01T00:00:00",
    "ticket_id": 1,
    "author_id": 1
  }
]

Добавление комментария к заявке

POST /api/v1/tickets/{ticket_id}/comments/

Тело запроса:

{
  "text": "string"
}

Ответ:

{
  "id": 1,
  "text": "string",
  "created_at": "2023-01-01T00:00:00",
  "ticket_id": 1,
  "author_id": 1
}

Удаление комментария

DELETE /api/v1/comments/{comment_id}

Ответ:

{
  "success": true,
  "message": "Comment deleted successfully"
}

Коды ошибок

Код Описание
400 Неверный запрос
401 Не авторизован
403 Доступ запрещен
404 Ресурс не найден
422 Ошибка валидации
500 Внутренняя ошибка сервера

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

Пример авторизации и создания заявки

import requests

# Авторизация
auth_response = requests.post(
    "http://localhost:8000/api/v1/token",
    json={"username": "user", "password": "password"}
)
token = auth_response.json()["access_token"]

# Создание заявки
headers = {"Authorization": f"Bearer {token}"}
ticket_response = requests.post(
    "http://localhost:8000/api/v1/tickets/",
    headers=headers,
    json={
        "title": "Не работает принтер",
        "description": "Принтер HP в кабинете 101 не печатает",
        "priority": "medium",
        "category": "Принтеры и МФУ"
    }
)
print(ticket_response.json())

Clone this wiki locally