API получения показаний по одометру и уровню топлива

Проблематика вопроса: зачастую клиенты фиксируют данные приходящие от Систем мониторинга транспорта в каких-либо собственных информационных системах. Например, это может логистическая система, или собственная 1С.

Решение: интеграция с информационной системой компании при помощи API получения показаний по одометру и топливу. API поможет решить следующие задачи:

• Формирование путевых листов. При помощи данных из API можно сформировать путевой лист, например, в 1С.
• Фиксация данных в различных системах оптимизации работы автопарков.
• Локальное хранение данных в собственных информационных системах.
• Анализ работы автопарка.

Общий принцип работы:

1. Авторизация;
2. Запрос доступных объектов мониторинга;
3. Построение статистики по показаниям одометра;
4. Построение статистики по уровню топлива.

Документация : доступна в интерфейсе Swagger : https://developers.scout-gps.ru/swagger/ui/index#/

Авторизация

Для того, чтобы воспользоваться API требуется выполнить аутентификацию. POST-метод api/auth/token предназначен для получения токена авторизации по данным Вашей учетной записи на сервере СКАУТ-365.

Для получения токена необходимо сделать POST запрос по адресу: https://api.scout-gps.ru/api/auth/token следующего вида:

grant_type=password&username=demo&password=demo&locale=ru&client_id=facac5c1-f966-4ed3-ada2-00cea620cb78

В блоке username необходимо указать логин учетной записи на СКАУТ-365, в блоке  password —  логин учетной записи. Для примера выше следует заменить поля demo на свои учетные записи. Остальные параметры следует оставить без изменений.

Для авторизации через Swagger необходимо вызвать диалоговое окно авторизации. Сделать это можно нажав пункт меню  Expand Operations  в любом из доступных методов API (Рисунок 1).

Рисунок 1 —  Главная страница Swagger

В правой части раскрывшейся области требуется нажать на иконку с восклицательным знаком (Рисунок 2). 

Рисунок 2 —  Вызов окна аутентификации

Нажатие на эту иконку вызовет окно аутентификации (Рисунок 3).

Рисунок 3 —  Диалоговое окно авторизации

В поля User и Password требуется ввести логин и пароль учётной записи пользователя ПО СКАУТ-Платформа. В выпадающем списке Type необходимо выбрать Basic auth, а в полях ClientId и Secret ввести строку scout-online . 

Запрос списка доступных объектов мониторинга

Для того, чтобы получить данные по показаниям одометра или уровню топлива, используя API, в запросе требуется передать уникальный идентификатор объекта мониторинга (Рисунок 4):

Рисунок 4 —  Уникальный идентификатор передаваемый в запрос

Чтобы определить этот уникальный идентификатор после запроса на авторизацию требуется воспользоваться методами Units или Terminals (Рисунок 5): 

Рисунок 5 — Методы Units и Terminals

С описанием запроса, которые требуется направить сервису, чтобы получить список объектов мониторинга, доступных учётной записи, можно раскрыв описание метода Units в Swagger (Рисунок 6). Для отправки запроса требуется нажать кнопку "Try it out!" ( ).

Рисунок 6  — Метод Units

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

Метод  /statistics/odometer   возвращает данные по пробегу за запрошенный интервал. В зависимости от запроса ответ может быть детализирован с точностью до суток внутри заданного интервала. 

По каждому интервалу, выводимому в ответе, сервис выводит либо данные пробега по одометру, либо данные пробега по навигации.

Решает он это следующим образом:

• Рассчитывается показания по одометру на начало интервала beginOdometrKm;
• Рассчитываются показания по одометру на конец периода endOdometrKm;
• Рассчитывается пробег по навигации NavigationKm;
• Рассчитывается пробег по одометру OdometrKm (по текущей логике он может быть не равен арифметической разнице (endOdometrKm – beginOdometrKm).

С дополнительными особенностями, которые накладываются на обработку данных, получаемых при помощи API можно ознакомиться в статье Особенности обработки статистики по показаниям одометра в API Одометр и топливо.

Метод доступен по адресу: https://api.scout-gps.ru/statistics/odometer

Запрос имеет следующие параметры:

Пример строки запроса: 
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer токен авторизации' 'httрs: //арi.sсоut-gps.ru/statistics/odometer?unitID=123456&beginDateTime=2017%2F01%2F01 &endDateTime=2017%2F01%2F01&olsonId=Europe%2FMoscow&interval=day'  

С ответами от сервиса можно ознакомиться по ссылке: Ответы на запросы к API Одометр и топливо.

Построение статистки по уровню топлива

Этот метод возвращает по заданному транспортному средству уровень топлива в зависимости от следующих параметров:

• на начало и конец каждых полных суток;
• только на начало и конец заданного периода.

Метод доступен по адресу:  https://api.scout-gps.ru/statistics/fuel

Параметры запроса описаны в таблице:

Пример строки запроса:
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer токен авторизации' 'httрs: //api.scout-gps.ru/statistics/fuel?unitID=123456&beginDateTime=2017%2F01%2F01&endDateTime=2017%2F01%2F01&olsonId=Europe%2FMoscow&interval

С ответами от сервиса можно ознакомиться по ссылке: Ответы на запросы к API Одометр и топливо.