6. API

6.1. Создание сообщения

POST /api/new_min_report_data/

Создаёт сообщение с необязательными вложениями. Тело запроса передаётся в формате JSON.

6.1.1. Заголовки

Content-Type: application/json
Authorization: ApiKey <ключ> — API-ключ для интеграции.
X-Environment-Mode — режим работы. Значение test включает проверку без создания сообщения; если заголовок отсутствует или пуст, используется test. Любое другое непустое значение создаёт сообщение, например production.

В тестовом режиме проверяются обязательные поля, дата, подразделение и Base64-вложения. Ссылка file_url не загружается и не проверяется.

6.1.2. Поля запроса

date — обязательная дата сообщения в формате YYYY-MM-DD.
name — обязательное имя автора.
text — обязательный текст сообщения.
department — необязательный ID подразделения: целое число или строка из цифр. Если поле не задано, имеет другой формат или подразделение не найдено, используется подразделение с ID 1.
file_url — необязательная ссылка на один файл.
files — необязательный список файлов; каждый элемент содержит имя name и Base64-содержимое content.
attachments — необязательный список файлов в формате клиента; каждый элемент содержит имя name и Base64-содержимое content_base64.

Имя файла должно быть непустым, не длиннее 250 символов, без пути и не может быть равно . или ... Содержимое должно быть строкой стандартного Base64; допускается префикс data:...;base64,. Если у элемента задано поле encoding, его значение должно быть base64. Поля mime_type и size можно передать для совместимости, но они не используются для сохранения и не проверяются.

Можно одновременно передать file_url, files и attachments. Содержимое Base64 заменяется на [redacted] в истории запросов.

6.1.3. Пример запроса

POST /api/new_min_report_data/ HTTP/1.1
Content-Type: application/json
Authorization: ApiKey <ключ>
X-Environment-Mode: production

{
  "date": "2026-09-18",
  "name": "Автор",
  "text": "Описание сообщения",
  "department": 1,
  "file_url": "https://example.com/report.pdf",
  "files": [
    {"name": "report.txt", "content": "SGVsbG8="}
  ],
  "attachments": [
    {
      "name": "attachment.txt",
      "mime_type": "text/plain",
      "size": 5,
      "encoding": "base64",
      "content_base64": "SGVsbG8="
    }
  ]
}

Формат attachments соответствует формату вложений клиента, но остальные поля клиентского документа автоматически не преобразуются: обязательные date, name и text должны быть переданы в описанном выше виде.

6.1.4. Ответы

В рабочем режиме при успешном создании возвращается HTTP 200:

{"msg": "Report created id=123", "report_id": 123}

При ошибке загрузки файла по ссылке или сохранения вложения сообщение всё равно создаётся, обработка остальных файлов продолжается, а HTTP 200 содержит описание ошибки в msg вместе с report_id. Клиенту необходимо проверять msg, если важно убедиться, что все файлы сохранены.

В тестовом режиме при успешной проверке возвращается HTTP 200 без report_id:

{"msg": "Test mode: validation successful"}

Если обязательные поля отсутствуют, дата или Base64-вложения некорректны, возвращается HTTP 400 с описанием ошибки в msg; сообщение не создаётся. Если подходящее подразделение не найдено и подразделение с ID 1 отсутствует, возвращается HTTP 500 с msg: Department id=1 not found in database.

6.2. Передача данных о полёте

POST /api/new_flight_data/

Создаёт запись о полёте в программе анализа полётной информации (FDM). Тело запроса передаётся в формате JSON.

6.2.1. Заголовки

Content-Type: application/json
Authorization: ApiKey <ключ> — API-ключ для интеграции.
X-Environment-Mode — режим работы. Только значение prod записывает данные в основную базу; при отсутствии или пустом значении используется test. Любое значение, отличное от prod, выполняет только проверку данных.

Важно

В тестовом режиме полёты и записи справочников не создаются и не изменяются; тестовая база не требуется. Результат проверки не гарантирует успешного сохранения в рабочем режиме. История запросов сохраняется в основной базе для запросов с корректным ключом и распознанным JSON, но проверка существующего полёта не выполняется.

6.2.2. Поля запроса

id — идентификатор конкретной записи о полёте во внешней системе.
dep_date и arr_date — даты вылета и прибытия в формате YYYY-MM-DD.
flight — объект с полями id и name: идентификатор номера рейса во внешней системе и номер рейса. flight.id идентифицирует номер рейса, а не конкретный полёт.
route_fact — массив пунктов фактического маршрута в порядке следования. Каждый пункт содержит id аэропорта во внешней системе, name и строки кодов code1, code2, code3. Неиспользуемые коды передаются как пустые строки.
pilot1 и pilot2 — номера первого и второго пилотов во внешней системе. Можно передавать целым числом или строкой, в том числе с буквами и ведущими нулями. Строковые значения сохраняются без изменения: например, "00123" и 123 обозначают разных пилотов.
aircraft — объект с полями id и name: идентификатор и обозначение воздушного судна во внешней системе.
stewards — необязательный массив непустых строк с номерами бортпроводников, например ["123", "456"]. Пробелы по краям удаляются; номер после удаления пробелов не должен превышать 250 символов.

Все поля, кроме stewards, обязательны. Идентификаторы id в примере передаются числами. Номера пилотов используются для поиска или создания пилотов в справочнике. Бортпроводники также создаются в справочнике при отсутствии, но с самой записью FDM не связываются.

Идентификаторы передаются строкой или целым числом. Длина идентификаторов, имён и кодов не должна превышать 250 символов; такие же ограничения действуют для сформированных названия аэропорта с кодами и строки маршрута. Пустые номера пилотов допускаются. Для организации Smartavia номер рейса должен содержать не менее трёх последовательных цифр.

При обработке создаются отсутствующие ВС и аэропорты по их идентификаторам интеграции, а также рейс по его номеру. Названия ВС и аэропортов и маршрут рейса могут обновляться. Фактический маршрут записи формируется из названий пунктов, разделённых `` – ``.

6.2.3. Пример запроса

POST /api/new_flight_data/ HTTP/1.1
Content-Type: application/json
Authorization: ApiKey <ключ>
X-Environment-Mode: test

{
  "id": 1001,
  "dep_date": "2026-09-18",
  "arr_date": "2026-09-18",
  "flight": {"id": 42, "name": "AB-123"},
  "route_fact": [
    {"id": 1, "name": "Аэропорт отправления", "code1": "", "code2": "AAA", "code3": ""},
    {"id": 2, "name": "Аэропорт назначения", "code1": "", "code2": "BBB", "code3": ""}
  ],
  "pilot1": "00123",
  "pilot2": 456,
  "aircraft": {"id": 12, "name": "RA-12345"},
  "stewards": ["789", "790"]
}

6.2.4. Ответы

В тестовом режиме при успешной проверке возвращается HTTP 200:

{"msg": "Test mode: validation successful", "mode": "test"}

При успешной обработке в режиме prod возвращается HTTP 200 с полями msg и mode. В msg перечисляются созданные записи справочников; если создавать записи не потребовалось, строка может быть пустой.

Если полёт с таким id уже найден в основной базе, повторная запись не создаётся; возвращается HTTP 200 с одним полем msg:

{"msg": "Запись с integration_id=1001 уже существует. "}

Проверка дубликатов выполняется только в режиме prod. При ошибке проверяемых полей возвращается HTTP 400 с описанием в msg; при неверном ключе — HTTP 401 с {"msg": "Invalid Key"}.