ПРОТОКОЛ ИНФОРМАЦИОННОГО ВЗАИМОДЕЙСТВИЯ
Между Системой представления планов полетов по сети Интернет и телефонной сети связи общего пользования и внешними приложениями сторонних разработчиков (API)
Версия 1.3.10-rc.35
1. Общие положения
1.1 Назначение
Настоящий Протокол информационного взаимодействия (далее – Протокол, API) определяет порядок информационного взаимодействия между Системой представления планов полетов по сети Интернет и телефонной сети связи общего пользования (далее – СППИ) и внешними приложениями сторонних разработчиков (далее – Сторонние приложения) при выполнении Сторонними приложениями следующих функций:
- Авторизация.
- Получение списка поданных ранее планов ИВП для запрашиваемого пользователя СППИ (логина) на заданный диапазон времени.
- Получение детальных данных по определенному, ранее поданному плану, принадлежащему авторизовавшемуся пользователю СППИ.
- Тестирование текста подаваемого плана ИВП (FPL, SHR, SPW).
- Подача корректных планов: FPL, SHR, SPW.
- Подача корректных сообщений по поданным ранее планам: CHG, DLA, CNL, DEP, ARR.
- Подача корректных представления на издание ВР и МР.
- Выгрузка актуальной информации об ограничениях на ИВП.
- Общие. В настоящем документе приведен перечень доступных функций. Более подробная спецификация в формате OpenAPI Specification (Swagger) размещена по адресу https://api.ivprf.ru/swagger.
1.2 Порядок внесения изменений в Протокол
Изменения в Протокол вносятся по согласованию сторон и оформляются путём издания новой редакции документа.
1.3 Дополнительная документация
- Токены - JWT.
- Авторизация и аутентификация - Bearer Authentication
- Транспортный протокол - HTTP 1.1.
1.4 Порядок информационного взаимодействия
Взаимодействие происходит путем обращения Стороннего приложения к специализированному веб-сервису СППИ через сеть Интернет по протоколу REST поверх протокола HTTPS.
1.5 Авторизация и аутентификация
Для подключения к API оставьте свою заявку на sppi@matfmc.ru. Запросы, связанные с получением или записью данных в систему СППИ авторизуются посредством API-ключа (Secret Key), передающегося в заголовке Secret-Key.
Параметр авторизации пользователя указывается в заголовке Autorization, значение которого формируется как «Bearer AccessToken» (также см. Bearer Authentication).
Перед выполнением веб-сервисом СППИ любого запроса выполняются проверки:
- Проверка подписи токена
- Сравнение expired_at из payload токена с текущим временем
- Получение разрешений, необходимых для выполнения операции в списке выше
- Дополнительные проверки авторизации метода, если они есть
1.6 Использование refresh токенов
Refresh токен не может быть использован повторно и должен быть удален после окончания срока его действия.
1.7 Пагинация
Пагинация передается в виде двух параметров:
- limit, отвечает за количество объектов получаемого ресурса
- offset, отвечает за количество объектов, которые необходимо пропустить в данном запросе
Некоторыми функциями могут быть реализованы следующий возможности:
- В ответ на массовый запрос ресурса может прийти total, которой будет обозначать общее количество ресурса, доступное для получения по данному запросу (с учетом фильтра)
- Минимальное значение limit равно 1, а максимальное значение равно 100
1.8 Ошибки
При взаимодействии между СППИ и Сторонними приложениями используются стандартные http коды для описания ошибок, согласно стандарту транспортного протокола HTTP 1.1 + WebDav.
1.9 Максимальное количество подключений
Максимальное количество подключений внешними приложениями сторонних разработчиков к СППИ ограничено 3(тремя) за одну секунду.
2. Функции
Перечень доступных по API функций определяются правами доступа учетной записи СППИ, которые используются при авторизации API.
2.1 Авторизация
2.1.1 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| POST | /auth/tokens | Получение токенов аутентификации. |
| POST | /auth/tokens/refresh | Получение токенов аутентификации по refresh token |
2.2 Получение списка поданных ранее планов ИВП для запрашиваемого пользователя СППИ (логина)
2.2.1 Статусы
Список статусов:
- draft
- on_processing
- approved
- rejected
- canceled
- in_flight
- done Статус по умолчанию (при создании): draft.
2.2.2 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| GET | /plans/fpl | Получение списка планов FPL пользователя |
| GET | /plans/fpl/{id} | Получение плана FPL по идентификатору |
| GET | /plans/shr | Получение списка планов SHR пользователя |
| GET | /plans/spw | Получение списка планов SPW пользователя |
2.3 Получение детальных данных по определенному, ранее поданному плану, принадлежащему авторизовавшемуся пользователю СППИ
Для получения детальных данных по плану необходимо воспользоваться функциями раздела 2.2, передав id интересующего плана в качестве параметра фильтрации.
2.4 Тестирование текста подаваемого плана ИВП (FPL, SHR, SPW)
2.4.1 Статусы
Статусы планов соответствуют 2.2.1
2.4.2 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| GET | /plans/fpl/{id}/test | Тестирование текста подаваемого плана FPL |
| GET | /plans/shr/{id}/test | Тестирование текста подаваемого плана SHR |
| GET | /plans/spw/{id}/test | Тестирование текста подаваемого плана SPW |
2.5 Подача корректных планов: FPL, SHR, SPW
2.5.1 Статусы
Статусы планов соответствуют 2.2.1
2.5.2 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| POST | /plans/fpl | Создание плана FPL |
| POST | /plans/shr | Создание плана SHR |
| POST | /plans/spw | Создание плана SPW |
| POST | /plans/fpl/{id}/send | Отправка плана FPL |
| POST | /plans/shr/{id}/send | Отправка плана SHR |
| POST | /plans/spw/{id}/send | Отправка плана SPW |
2.6 Подача корректных сообщений по поданным ранее планам: CHG, DLA, CNL, DEP, ARR
2.6.1 Статусы
Статусы планов соответствуют 2.2.1
2.6.2 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| PATCH | /plans/fpl/{id}/chg | Отправка CHG на FPL |
| PATCH | /plans/fpl/{id}/dla | Отправка DLA на FPL |
| PATCH | /plans/fpl/{id}/cnl | Отправка CNL на FPL |
| PATCH | /plans/fpl/{id}/dep | Отправка DEP на FPL |
| PATCH | /plans/fpl/{id}/arr | Отправка ARR на FPL |
| PATCH | /plans/shr/{id}/cnl | Отправка CNL на SHR |
| PATCH | /plans/shr/{id}/dep | Отправка DEP на SHR |
| PATCH | /plans/shr/{id}/arr | Отправка ARR на SHR |
| PATCH | /plans/spw/{id}/cnl | Отправка CNL на SPW |
| PATCH | /plans/spw/{id}/dep | Отправка DEP на SPW |
| PATCH | /plans/spw/{id}/arr | Отправка ARR на SPW |
2.7 Подача корректных представлений на издание ВР и МР
2.7.1 Статусы
Список статусов:
- draft
- on_processing
- approved
- rejected
- canceled Статус по умолчанию (при создании): draft.
2.7.2 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| POST | /submissions | Создание представления |
| GET | /submissions/{id}/send | Отправка представления |
2.8 Выгрузка актуальной информации об ограничениях на ИВП
2.8.1 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| GET | /ani/restriction-zones | Получение списка ограничений на ИВП |
2.9 Получение списка аэродромов
2.9.1 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| GET | /ani/aerodromes | Получение списка аэродромов |
2.10 Прочие
2.10.1 Реализуемые функции
| Метод | Путь | Выполняемое действие |
|---|---|---|
| GET | /common/current-time | Получение текущего времени сервера |
| GET | /plans/history/{sid} | Получение истории по сообщениям |
| GET | /submissions/{id}/history | Получение истории преставления |