Руководство пользователя

Главная страница API

Для удобного доступа ко всем версиям API и документации используйте главную страницу API:

• Адрес: /api/ (или полный адрес вашего сервера, например https://ask.kivit.ru/api/)
• Доступ: Только для авторизованных пользователей с типом employee (сотрудники)
• Альтернативный доступ: Пункт меню "API" в разделе настроек (/settings/)

Требования для доступа:

• Необходимо быть залогиненным в системе
• Пользователь должен иметь тип "employee" (не "external" или другие типы)

На главной странице вы найдете:

• Ссылки на все версии API системы
• Прямой доступ к API эндпоинтам
• Ссылки на интерактивную документацию (Swagger UI, ReDoc)
• Ссылки на OpenAPI схему

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

Важно: Документация показывает все доступные эндпоинты и примеры, но для получения реальных данных необходимо использовать токен API с соответствующими разрешениями.

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

Для работы с API вам нужен токен. Важно: Просмотр документации не требует токена (достаточно быть авторизованным сотрудником), но для получения реальных данных через API токен обязателен.

Обратитесь к администратору системы с запросом на создание токена. Администратор создаст токен и предоставит вам:

• Сам токен (длинная строка символов)
• Информацию о том, к каким разделам системы у вас есть доступ
• Информацию о том, какие операции вы можете выполнять

Важно: Сохраните токен в безопасном месте. Токен показывается только один раз при создании.

Разница между документацией и данными:

• Документация -- доступна всем авторизованным сотрудникам, показывает структуру API, примеры запросов и ответов
• Реальные данные -- требуют токен API с соответствующими разрешениями на модели и методы

Основы работы с API

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

Все запросы к API выполняются по протоколу HTTP/HTTPS. Базовый адрес API:

https://ваш-домен.ru/api/v1/

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

В каждом запросе необходимо передавать токен в заголовке:

Authorization: Token ваш-токен-здесь

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

Все данные передаются и получаются в формате JSON. Заголовок запроса должен содержать:

Content-Type: application/json

Примеры запросов

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

GET /api/v1/tasks/
Authorization: Token ваш-токен

Ответ:

{
  "count": 150,
  "next": "https://ваш-домен.ru/api/v1/tasks/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "title": "Название задачи",
      "description": "Описание задачи",
      "executor": 5,
      "executor_name": "Иванов Иван Иванович",
      "duedate": "2024-12-31T23:59:59+03:00",
      "completed": false,
      "created_at": "2024-01-15T10:30:00+03:00"
    },
    ...
  ]
}

Получение информации о конкретной задаче

GET /api/v1/tasks/1/
Authorization: Token ваш-токен

Создание новой задачи

POST /api/v1/tasks/
Authorization: Token ваш-токен
Content-Type: application/json

{
  "title": "Новая задача",
  "description": "Описание новой задачи",
  "executor": 5,
  "duedate": "2024-12-31T23:59:59+03:00"
}

Обновление задачи

PATCH /api/v1/tasks/1/
Authorization: Token ваш-токен
Content-Type: application/json

{
  "completed": true,
  "completedate": "2024-01-20T15:00:00+03:00"
}

Удаление задачи

DELETE /api/v1/tasks/1/
Authorization: Token ваш-токен

Работа со списками

Пагинация

Списки разбиты на страницы. По умолчанию на странице 20 записей. Для перехода на следующую страницу используйте URL из поля next в ответе.

Для изменения размера страницы используйте параметр page_size:

GET /api/v1/tasks/?page_size=50

Фильтрация

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

Примеры:

• Задачи конкретного исполнителя:

GET /api/v1/tasks/?executor=5

• Незавершенные задачи:

GET /api/v1/tasks/?completed=false

• Задачи с дедлайном после определенной даты:

GET /api/v1/tasks/?duedate__gte=2024-01-01T00:00:00Z

• Несколько условий одновременно:

GET /api/v1/tasks/?executor=5&completed=false&duedate__gte=2024-01-01T00:00:00Z

Доступные операторы:

• exact -- точное совпадение (по умолчанию)
• icontains -- содержит текст (без учета регистра)
• gte -- больше или равно
• lte -- меньше или равно
• isnull -- проверка на пустое значение

Поиск

Поиск выполняется по нескольким полям одновременно. Используйте параметр search:

GET /api/v1/users/?search=Иванов

Система найдет всех пользователей, у которых в имени, фамилии, отчестве или email есть слово "Иванов".

Сортировка

Для сортировки используйте параметр ordering:

GET /api/v1/tasks/?ordering=-created_at

Минус перед именем поля означает сортировку по убыванию (от новых к старым), без минуса -- по возрастанию.

Сортировка по нескольким полям:

GET /api/v1/tasks/?ordering=-created_at,title

Работа с удаленными записями

Некоторые разделы поддерживают мягкое удаление. Удаленные записи по умолчанию не показываются. Чтобы их увидеть, используйте параметр include_deleted=true:

GET /api/v1/finance/charges/?include_deleted=true

Работа с файлами

Получение файлов

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

{
  "id": 1,
  "name": "Иванов Иван",
  "avatar": "/media/avatars/user.jpg",
  "avatar_url": "https://ваш-домен.ru/media/avatars/user.jpg"
}

Загрузка файлов

Для загрузки файлов используйте формат multipart/form-data. Пример загрузки вложения к задаче:

POST /api/v1/tasks/attachments/
Authorization: Token ваш-токен
Content-Type: multipart/form-data

task=1
file=@путь/к/файлу.pdf

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

При возникновении ошибки система вернет ответ с кодом ошибки и описанием:

{
  "error": "Validation error",
  "details": {
    "title": ["Это поле обязательно."],
    "duedate": ["Некорректный формат даты."]
  }
}

Основные коды ошибок:

• 400 Bad Request -- ошибка валидации данных
• 401 Unauthorized -- неверный или отсутствующий токен
• 403 Forbidden -- недостаточно прав для выполнения операции
• 404 Not Found -- запрашиваемый объект не найден
• 429 Too Many Requests -- превышен лимит запросов
• 500 Internal Server Error -- внутренняя ошибка сервера

Использование документации

Доступ к документации

Документация API доступна несколькими способами:

1. Через главную страницу API:
2. Адрес: /api/
3. Доступ: Только для авторизованных пользователей с типом employee
4. Требуется вход в систему через веб-интерфейс
5. Через пункт меню в настройках:
6. Перейдите в раздел "Настройки" (/settings/)
7. В левом меню выберите пункт "API"
8. Это приведет на главную страницу API
9. Прямые ссылки на форматы документации:
10. Swagger UI: /api/v1/schema/swagger-ui/
11. ReDoc: /api/v1/schema/redoc/
12. OpenAPI схема: /api/v1/schema/

Важно: Все форматы документации требуют авторизации и типа пользователя "employee".

Главная страница API

На главной странице отображаются карточки для каждой версии API с прямыми ссылками на:

• API эндпоинты -- список всех доступных эндпоинтов
• OpenAPI схему -- машинно-читаемую схему API
• Swagger UI -- интерактивный интерфейс для тестирования
• ReDoc -- альтернативный интерфейс документации

Форматы документации

1. Swagger UI -- /api/v1/schema/swagger-ui/

• Позволяет просматривать все доступные эндпоинты
• Показывает примеры запросов и ответов
• Важно: Для выполнения запросов с реальными данными необходимо использовать токен API
• ReDoc -- /api/v1/schema/redoc/

• Альтернативный интерфейс документации
• Удобен для чтения и поиска
• Показывает полную структуру API
• OpenAPI схема -- /api/v1/schema/

• Машинно-читаемая схема API в формате JSON/YAML
• Можно использовать для генерации клиентских библиотек
• Полезна для автоматизации и интеграции

Примечание: Документация показывает все эндпоинты и примеры, но для получения реальных данных необходимо использовать токен API с соответствующими разрешениями на модели и методы.

Типичные сценарии использования

Сценарий 1: Получение списка незавершенных задач пользователя

GET /api/v1/tasks/?executor=5&completed=false&ordering=-duedate
Authorization: Token ваш-токен

Сценарий 2: Создание заявки в сервис-деске

POST /api/v1/servicedesk/requests/
Authorization: Token ваш-токен
Content-Type: application/json

{
  "title": "Проблема с принтером",
  "message": "Принтер не печатает",
  "client": 10,
  "type": "uuid-типа-заявки",
  "priority": "uuid-приоритета"
}

Сценарий 3: Получение информации о проекте с этапами

GET /api/v1/projects/uuid-проекта/
Authorization: Token ваш-токен

Затем получить этапы проекта:

GET /api/v1/projects/milestones/?project=uuid-проекта
Authorization: Token ваш-токен

Сценарий 4: Поиск контакта в CRM

GET /api/v1/crm/contacts/?search=Иванов
Authorization: Token ваш-токен

Сценарий 5: Получение страниц базы знаний по категории

GET /api/v1/kb/pages/?categories=uuid-категории
Authorization: Token ваш-токен

Интеграция с внешними системами

API можно использовать для интеграции с различными внешними системами:

• 1С -- синхронизация данных о сотрудниках, начислениях, проектах
• Биллинговые системы -- передача данных об услугах и счетах
• Системы мониторинга -- автоматическое создание заявок при обнаружении проблем
• Мобильные приложения -- доступ к данным системы с мобильных устройств
• Веб-приложения -- интеграция с другими веб-системами

Рекомендации по использованию

1. Кэшируйте данные -- не запрашивайте одни и те же данные повторно, используйте кэширование на стороне вашего приложения
2. Используйте фильтрацию -- всегда используйте фильтры для получения только нужных данных
3. Обрабатывайте ошибки -- обязательно обрабатывайте все возможные ошибки в вашем коде
4. Соблюдайте лимиты -- не превышайте установленные лимиты на количество запросов
5. Используйте правильные методы -- используйте PATCH для частичного обновления, PUT для полного
6. Проверяйте права -- перед выполнением операций проверяйте, что у вас есть необходимые права

Получение помощи

Если у вас возникли вопросы или проблемы при работе с API:

1. Проверьте интерактивную документацию -- там есть примеры для большинства операций
2. Проверьте формат запроса -- убедитесь, что заголовки и данные переданы правильно
3. Проверьте права доступа -- убедитесь, что ваш токен имеет необходимые права
4. Обратитесь к администратору системы -- он может проверить настройки токена и помочь с решением проблемы