Общая информация

Задача продукта

  • Экономия на топливе за счет выбора лучших заправок на пути.
  • Оптимизация маршрута с учетом плана остановок на АЗС.
  • Повышение управляемости маршрута за счет событий и пересчетов в реальном времени.

Построение маршрута без телематики

Взаимодействие с платформой возможно при построении оптимального маршрута без использования телематики:

  • строится оптимальный маршрут;
  • возвращается план заправок и остановок;

Подключение сервиса телематики (опционально)

В платформу можно добавить сервис телематики и получать в удобном виде:

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

Следование по маршруту

Функция следования по маршруту помогает:

  • своевременно остановиться на нужной АЗС;
  • рассчитывать в реальном времени параметры заправки и движения;
  • получать уведомления о ключевых событиях по маршруту;
  • обновлять план остановок при изменении условий в пути.

Авторизация для интеграции по API

Для интеграции по API нужно:

  1. Получить статический секрет у команды платформы.
  2. Передавать его в заголовке Authorization как Bearer token в каждом запросе.

Пример:

Authorization: Bearer <STATIC_SECRET>

Интеграция с E1

Платформа поддерживает подключение E1 Public API (https://publicapi.e1-card.ru) для использования данных E1 при расчете маршрутов и планов заправок.

Интеграция подключается на уровне организации через POST /organizations/{organizationId}/integrations. Для E1 нужно передать тип интеграции E1PublicApi и учетные данные доступа.

Пример запроса:

{
  "type": "E1PublicApi",
  "username": "user@mail.com",
  "password": "12345"
}

После добавления интеграции E1 для организации в расчетах будут использоваться АЗС и цены из E1. Скидки, добавленные через API /discounts, для такой организации при расчете использоваться не будут.

Простой сценарий интеграции

Если интеграция ограничивается регистрацией клиента и последующим расчетом плана заправок, базовый сценарий выглядит так:

sequenceDiagram
    participant Partner as Партнер
    participant OptimalRouteApi as OptimalRoute API

    Note over Partner,OptimalRouteApi: Шаг 1. Регистрация организации клиента
    Partner->>+OptimalRouteApi: POST /organizations<br/>externalOrganizationId = client-id-partner
    OptimalRouteApi-->>-Partner: 201/200<br/>organizationId + externalOrganizationId

    Note over Partner,OptimalRouteApi: Шаг 2. Расчет плана заправок
    Partner->>+OptimalRouteApi: POST /fuel-plans<br/>organizationId, route, stations,<br/>allowedProducts, tankCapacity,<br/>initialFuel, minimumFuel, fuelConsumption
    OptimalRouteApi-->>-Partner: 200 OK<br/>fuel plan с рекомендованными остановками и объемами заправки

Что важно в этом сценарии

  1. Партнер один раз регистрирует организацию клиента через POST /organizations.
  2. В ответе платформа возвращает organizationId - внутренний идентификатор организации в платформе.
  3. При каждом вызове POST /fuel-plans нужно передавать именно organizationId, полученный на шаге регистрации.
  4. externalOrganizationId нужен для связи с идентификатором клиента в системе партнера и повторной идемпотентной регистрации.

Глоссарий

  • Партнер - интегрирующаяся компания, которая вызывает API платформы.
  • Клиент партнера - компания, для которой партнер строит расчет и от имени которой работает с платформой.
  • Организация - сущность в платформе, которая соответствует клиенту партнера.
  • externalOrganizationId - идентификатор клиента в системе партнера или внешней системе интегратора.
  • organizationId - внутренний идентификатор организации в платформе Optimal Route; используется в запросах POST /fuel-plans, /stations, /discounts и других API, где нужен контекст клиента.
  • План заправок (fuel plan) - результат расчета API POST /fuel-plans: набор рекомендованных остановок на АЗС, объемов заправки и расчетных параметров по маршруту.
  • Маршрут (route) - маршрут в запросе POST /fuel-plans, передаваемый как polyline и multiplier для декодирования.
  • Станции-кандидаты (stations) - список АЗС, доступных для расчета плана заправок.
  • Разрешенные продукты (allowedProducts) - список видов топлива, которые допустимы для расчета.

Добавление автомобиля в платформу

Для получения информации о местоположении автомобиля и возможности начать сценарий сопровождения по маршруту нужно подключить интеграцию телематики для организации, получить список автомобилей и сохранить параметры выбранного автомобиля.

sequenceDiagram
    participant Partner as Партнер
    participant OrganizationsApi as Organizations API
    participant VehicleApi as Vehicles API

    Note over Partner,OrganizationsApi: Шаг 1. Подключение сервиса телематики
    Partner ->>+ OrganizationsApi: POST /organizations/{organizationId}/integrations<br/>
    OrganizationsApi -->>- Partner: 200 OK

    Note over Partner,VehicleApi: Шаг 2. Получение автомобилей организации
    Partner ->>+ VehicleApi: GET /vehicles?organizationId={organizationId}
    VehicleApi -->>- Partner: 200 OK<br/>vehicles: id, parameters, ...

    Note over Partner,VehicleApi: Шаг 3. Сохранение параметров выбранного автомобиля
    Partner ->>+ VehicleApi: POST /vehicles/{vehicleId}/parameters
    VehicleApi -->>- Partner: 200 OK

Сценарий взаимодействия при слежении по маршруту

sequenceDiagram
    participant Partner as Партнер
    participant RouteGuidanceAPI as RouteGuidance API
    participant VehicleApi as Vehicle API
    participant OptimalRouteApi as OptimalRoute API

    alt Сопровождение в пути
        Partner ->>+ RouteGuidanceAPI: {vehicleId} нужно поехать по маршруту через выбранные точки
        RouteGuidanceAPI ->> Partner: ок
        alt Построение маршрута
        RouteGuidanceAPI->>OptimalRouteApi: Построение оптимального маршрут по выбранным параметрам
        OptimalRouteApi->>RouteGuidanceAPI: {optimalRouteId}
        RouteGuidanceAPI -->> Partner: Маршрут посчитан
        end

        loop Каждую минуту
            RouteGuidanceAPI ->>+ VehicleApi: Получение данных о телематике ТС
            VehicleApi ->>- RouteGuidanceAPI: Данные телематики ТС
        end
        RouteGuidanceAPI -->> Partner: Водитель подъезжает к заправке
        RouteGuidanceAPI -->> Partner: Пересчитан маршрут (сошел с маршрута/не хватает топлива)
        RouteGuidanceAPI ->>- Partner: Водитель доехал в конечную точку
    end

    alt Запрос актуальной телематики
        Partner ->> VehicleApi: {vehicleId} дай текущую информацию по ТС
        VehicleApi ->> Partner: Данные телематики ТС
    end

    alt Получение информации по маршруту
        Partner->>OptimalRouteApi: Получение информации по маршруту
        OptimalRouteApi->>Partner: {optimalRoute}
    end

Чтение и передача полилинии

  1. Полилиния принимается и отдается в сжатом lossy формате Google polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm)
  2. Вместе с полилинией принимается и отдается параметр polylineMultiplier, который обозначает точность кодирования координат. Обычно это 10e5 (иногда 10e6, т.к. координаты дорог в городах требуют большой точности).
  3. Часто в библиотеках точность принимается не в виде степени 10, а в виде числа знаков (5/6 и т.д.). Иногда библиотека не дает задавать этот параметр, и тогда скорее всего используется стантартный 10e5.
  4. Существует множество библиотек для работы с полилиниями для любых языков. Рекомендуемые варианты для некоторых из них:
    1. JS: @mapbox/polyline или @googlemaps/polyline-codec
    2. C#: Polyliner.Net
    3. Go: twpayne/go-polyline
    4. Python: frederickjansen/polyline