Перейти к основному содержимому

API

Система ГАЛАКТИКА предоставляет REST API для интеграции внешних систем — приложений, диспетчерских платформ, биллинга и других сервисов, которым нужен программный доступ к данным мониторинга: объектам, геозонам, водителям, событиям, отчётам и истории движения.

Раздел адресован разработчикам, создающим интеграцию с Системой. Он описывает общие принципы работы с API и содержит список методов с их назначением. Точные схемы запросов и ответов приведены в интерактивной документации Swagger, которая поставляется вместе с API и доступна по адресу /api/docs на сервере API — например, nav.gpspos.ru/api/docs.

Как начать​

  1. Получите у администратора вашей компании или у провайдера услуг мониторинга ПО ГАЛАКТИКА логин и пароль пользователя с доступом к API, а также адрес сервера API. В примерах этого раздела используется адрес nav.gpspos.ru; у вашей компании он может отличаться. Порядок включения API в интерфейсе описан в разделе Инструменты API.
  2. Получите токен доступа — см. Авторизация.
  3. Выполните первые запросы по примерам на странице Быстрый старт.
  4. Найдите нужный метод в разделе Методы API и уточните его схему в Swagger UI (/api/docs).

Остальные страницы раздела: Методы API — перечень доступных методов, Ошибки и коды ответов — формат ошибок и коды состояния HTTP.

Что доступно через API​

  • пользователи;
  • команды и шаблоны команд;
  • компании;
  • водители и группы водителей;
  • ключи водителей и группы ключей;
  • штрафы водителей;
  • смены водителей;
  • события и настройки событий;
  • геозоны и группы геозон;
  • объекты и группы объектов;
  • текущее состояние объектов — позиции, показания датчиков, приложенные ключи;
  • история объектов — треки, суточная статистика, смены водителей;
  • отчёты и шаблоны отчётов;
  • файлы, полученные с устройств, — фотографии и видео;
  • геокодер.

Методы, соответствующие каждой из перечисленных сущностей, приведены на странице Методы API.

Общие принципы​

  • Базовый путь — в типовой установке, где веб-интерфейс и API работают на одном домене, методы располагаются под /api/ относительно адреса сервера, например https://nav.gpspos.ru/api/Objects; Swagger — под /api/docs. Префикс /api/ задаётся обратным прокси-сервером: при развёртывании API на отдельном хосте или порте методы доступны от корня (/Objects). Базовый адрес уточняется у администратора.
  • Авторизация — JWT-токен, полученный по логину и паролю пользователя. Токен передаётся в заголовке Authorization: Bearer <токен> и действует 30 минут — см. Авторизация.
  • Права доступа — методы API возвращают данные в рамках тех же прав доступа, что и веб-интерфейс: пользователю доступны только те объекты, геозоны и данные, которые ему разрешены (см. Права доступа). Отдельной учётной записи для API с расширенными правами не предусмотрено; состав прав задаётся в панели управления.
  • Формат ошибок — при ошибке API возвращает JSON вида { "Status": "FAIL", "ErrorMessage": "..." } (в отдельных случаях — с дополнительным полем Args со списком аргументов ошибки) и соответствующий код состояния HTTP. Подробнее — в разделе Ошибки и коды ответов.
  • Ограничение частоты запросов — по умолчанию не более 20 запросов за 60 секунд с одного клиента (скользящее окно). Значение задаётся в настройках сервера и на конкретной установке может отличаться. См. Ограничение частоты запросов.
  • Модель данных — сущности и поля, которые возвращает API, соответствуют понятиям, описанным в остальных разделах документации; термины приведены в Глоссарии.

Соглашения​

  • Формат времени — во всех полях, связанных с позициями, треком, историей и интервалами отчётов (Time, ServerTime, From, Till и т. п.), время передаётся как число миллисекунд, прошедших с 1 января 1970 года 00:00:00 UTC (Unix-время в миллисекундах), — и в запросе, и в ответе. Отдельные поля с датой создания сущности (например, CreateDate) возвращаются строкой в формате ISO 8601; тип конкретного поля указан в Swagger UI.
  • Часовой пояс — время передаётся в UTC. В веб-интерфейсе то же значение отображается в часовом поясе, настроенном у пользователя.
  • Именование полей — поля в теле запросов и ответов записываются с заглавной буквы (ObjectId, AccessToken, ErrorMessage), как указано в Swagger UI.
  • Тело запроса — методы POST и PUT принимают JSON и требуют заголовок Content-Type: application/json. Исключение составляет загрузка файлов, использующая multipart/form-data.
  • Идентификаторы — Id объектов, геозон, водителей и других сущностей уникальны в пределах одной установки Системы и не переносятся между серверами. Для объектов предусмотрен поиск по IMEI.
  • Постраничная выдача — списочные методы возвращают весь доступный пользователю список одним ответом; параметры постраничности не поддерживаются.

Ограничения​