Спецификация API Advantum TMS версия 1.3
Спецификация интерфейса взаимодействия между Advantum TMS (ООО «Адвантум») и информационной системой Компании-Клиента в рамках проекта подключения к ATMS
Термины и сокращения
Применительно к настоящему Документу применяются следующие термины:
Применительно к настоящему Документу применяются следующие сокращения:
Общие положения
Назначение документа
Настоящий документ определяет порядок обмена данными (электронными сообщениями) между Автоматизированной системой управления транспортом (далее — ATMS) компании ООО «Адвантум» и информационной системой Компании-Клиента (далее — ИС, ИС Предприятия).

Целью проекта интеграции двух систем является предоставление функционала (SaaS услуга) планирования, контроля и анализа выполнения рейсов на основе данных ИС Предприятия.
Назначения документа:

  • Описание архитектуры и интерфейса взаимодействия между ATMS и ИС с использованием PublicAPI ATMS;
  • Описание требований к предоставляемым (исходным и результирующим) данным, правил их формирования и передачи (получения и отдачи).
Требования к организации взаимодействия между информационными системами
Основные требования к организации взаимодействия между ATMS и ИС:

  • Процесс взаимодействия между информационными системами должен осуществляться исключительно посредством PublicAPI версии 1 (v1), предоставляемого ATMS;
  • Данные должны передаваться по протоколу HTTPS в виде электронных сообщений;
  • Информационное содержимое электронных сообщений должно формироваться в формате JSON.
Архитектура взаимодействия информационных систем
Взаимодействие информационных систем
Для осуществления обмена данными с различными информационными системами в рамках ATMS предоставляется общедоступный PublicAPI версии 1 (v1). Взаимодействие с PublicAPI осуществляется посредством GET и POST запросов по протоколу HTTPS. Информационное тело запроса представляет собой JSON-сообщение с данными. Авторизация осуществляется отдельным запросом на получение сессионного токена.
Основными информационными потоками, направляемыми из ИС Предприятия в ATMS, являются:

  • Основные справочные данные (первичное наполнение справочников актуальными данными, дальнейшие изменения содержимого справочников): справочник клиентов, справочник транспортных средств, справочники возможных точек погрузки и доставки и другие;
  • График недоступности ТС и график (смены) работы водителей;
  • Заявки на перевозку грузов и заявки на выполнение порожних рейсов, изменения в заявках;
  • Сведения из путевых листов;
  • Информация о назначении ТС и водителя на выполнение конкретной заявки. Далее по документу эти сведения будут называться рейсом (см. раздел «Термины и сокращения»). Информация об изменении маршрута.

Основными информационными потоками, направляемыми из ATMS в ИС Предприятия (по запросу), являются:

  • Описание рейсов, созданных в ИС Предприятия и переданных на контроль в ATMS;
  • Описание рейсов, созданных в ATMS по поступившим ранее заявкам. Описание рейсов также включает тайминги (фактические временные данные) о прохождении ТС точек рейса.

Также, пользователям Предприятия предоставляется доступ к интерфейсу ATMS для осуществления планирования рейсов, контроля их выполнения и формирования оперативных и аналитических отчетов.
Для осуществления полноценной интеграции двух систем с учетом целевой картины, включающей возможность планирования в ATMS рейсов на основании заявок, созданных в ИС Предприятия, в рамках работ по проекту допускается возможность доработки обеих информационных систем. Такие доработки выполняются в рамках отдельного договора, их описание выходит за рамки текущего документа.
Идентификация объектов в ATMS и в ИС Предприятия
В атрибутный состав большинства электронных сообщений, участвующих в обмене информацией между информационными системами, входят идентификаторы объектов (далее — ИД). В спецификации PublicAPI используются 2 термина: внутренний ИД и внешний ИД.

Внутренний ИД — уникальный целочисленный идентификатор, автоматически присваиваемый каждому объекту при его создании в ATMS. Уникальность обеспечивается в разрезе конкретного справочника, включая заявки, рейсы и их составляющие элементы. Внутренний ИД — основной идентификатор, позволяющий поддержать ссылочную целостность данных, а также позволяющий осуществлять операции обновления, удаления данных в ATMS и получения данных из ATMS. При любой успешной операции создания записи в ATMS посредством PublicAPI ответное сообщение содержит полное описание созданного объекта с указанием присвоенного ему идентификатору. В ИС Предприятия необходимо обеспечить хранение этих идентификаторов для дальнейшего использования в интеграционных потоках обмена информацией.

Внешний ИД — уникальный идентификатор объекта, используемый в ИС Предприятия. В качестве внешнего ИД предпочтительно использовать GUID, гарантирующего уникальность, не зависящую от способа ведения записи. Использование именно GUID не является обязательным требованием, за исключением сведений из путевых листов. Эта особенность связана со способом хранения путевых листов в ATMS и учетом того, что использование других форматов идентификаторов (например, номера путевого листа) может привести к нарушению уникальности в течение продолжительного периода времени (например, номера путевых листов в 1С в рамках года являются уникальными, но не уникальными в рамках нескольких лет).
Подготовительные действия, выполняемые службой Технической поддержки ATMS
Перед началом использования PublicAPI для передачи данных необходимо в системе ATMS провести первичную инициализацию, осуществляемую службой технической поддержки ATMS компании Адвантум. Эта работа включает в себя:

  • Добавление в ATMS нового Холдинга с присвоением ему внутреннего идентификатора, который передается ответственному лицу Предприятия. Этот идентификатор используется при обмене информацией посредством PublicAPI;
  • Автоматическое создание системных справочников с наполнением данными по умолчанию и возможной их корректировкой по согласованию сторон;
  • Добавление в ATMS в созданный Холдинг новой Организации-Перевозчика с присвоением ей внутреннего идентификатора ATMS (внутренний ИД).

Как отмечалось в разделе 3.1, для заведения нового Перевозчика необходимо предоставить технической поддержке его уникальный идентификатор (внешний ИД), используемый в ИС Предприятия. Если такого значения нет, то в качестве внешнего ИД Организации-Перевозчику будет присвоено значение в виде GUID, которое надо будет сохранить и использовать в дальнейшем при обмене информацией;

  • Наполнение в ATMS справочника типов пропусков на ТС (подробно описано в разделе 5.6);
  • Наполнить в ATMS справочник типов скоростных режимов, используемых Перевозчиком;
  • Создание пользователей в ATMS и предоставление их реквизитов ответственному лицу Предприятия. Под одним пользователем будет осуществляться авторизация в ATMS при работе с PublicAPI, под другим пользователем будет осуществляться авторизация в интерфейсной части ATMS.
Необходимые (обязательные) справочные данные (поток из ИС Предприятия в ATMS)
Поток из ИС Предприятия в ATMS
В текущем разделе перечислены справочники (справочные данные), необходимые для работы функционала планирования и контроля выполнения рейсов. Для каждого справочника, обновляемого посредством PublicAPI, приведены описания и обязательность атрибутов, правила их трансформации в ATMS (т.е. ETL), регламент обновления данных. Отдельно акцентируется внимание на важных моментах при передаче данных.

Подробное описание PublicAPI выходит за рамки документа и доступно отдельно по ссылке: https://atms.advantum.ru/public/swagger-ui.html. Основные правила авторизации и работы с PublicAPI приведены в Приложениях 1 и 2 настоящего документа.
Предположительный порядок выполнения работ специалистами ИС Предприятия:
Перевозчики
Справочник содержит перечень организаций-перевозчиков, входящих в Холдинг Предприятия.

Как отмечалось в разделе 4, первоначально организацию-перевозчика заводят специалисты технической поддержки. Предполагается наличие единственного перевозчика.

Если в рамках Холдинга у Предприятия существует несколько перевозчиков, то их можно завести посредством интерфейсного решения ATMS без использования PublicAPI. Эту операцию также могут выполнить специалисты технической поддержки.
Точки Перевозчика

В ATMS при создании рейсов (в автоматическом или ручном режиме) при выборе наиболее подходящего ТС определяется текущее местонахождение всех ТС. Местонахождение определяется или на основе телематических данных, поступающих от мобильного блока, установленного на ТС, или на основе зафиксированного в системе местоположения ТС (например, ТС на ремонте в конкретной точке или в АТП). Справочник «Точки перевозчика» и служит для перечисления возможных мест «базирования» ТС Предприятия:


  • АТП (или возможные места расположения ТС, с которых они отправляются в рейс);
  • Центры по обслуживанию и ремонту ТС Предприятия.

Регламент передачи информации: первоначальная инициализация, при занесении новой точки (объекта) в ИС Предприятия, при изменении одного из атрибутов описания точки (ранее экспортированной в ATMS) в ИС Предприятия.

Минимальный атрибутный состав (полный атрибутный состав см. в спецификации PublicAPI)
Пример создания записи:

[{
  "externalId": "355",
  "carrierId": 3,
  "name": "Санкт-Петербург",
  "address": "г.Санкт-Петербург, Октябрьская набережная, 56",
  "lat": 59.88294785,
  "lon": 30.4517795529929
}]
  • При указании физического адреса точки важно обеспечить правильность и полноту его указания: адрес должен быть указан с точностью до дома/владения/строения.

Замечания по механизму обмена данными:

  • При успешной операции создания записи в ATMS ответное сообщение содержит полное описание созданных объектов с указанием присвоенных им внутренних ИД. В ИС Предприятия необходимо обеспечить хранение этих идентификаторов для дальнейшего использования в интеграционных потоках обмена информацией.
Дивизионы (подразделения)
В ATMS водители и ТС распределяются по логическим подразделениям (т.е. согласно организационной структуре) Предприятия-Холдинга (именно Холдинга, а не Перевозчика). Для хранения этой структуры используется текущий справочник.

В некоторых случаях состав подразделений Предприятия может одинаково отражаться как в текущем справочнике, так и в справочнике «Точки перевозчика» (см. раздел 5.2), особенно если последний содержит только перечень АТП. В этом случае в ИС Предприятия возможно ведение общего справочника с объединенным набором атрибутов.

Регламент передачи информации: первоначальная инициализация, при занесении нового дивизиона в ИС Предприятия, при изменении одного из атрибутов описания дивизиона (ранее экспортированного в ATMS) в ИС Предприятия.
Полный атрибутный состав
Пример создания записи:

[{
"externalId": "36734",
"carrierId": "2",
"name": "Санкт-Петербург",
"carrierPointId": "222"
}]
Необходимо обратить внимание
  • Если на Предприятии не используется разнесение водителей и ТС по различным подразделениям, то такое разнесение необходимо создать искусственно, создав единственный дивизион.

Замечания по механизму обмена данными:


  • При успешной операции создания записи в ATMS ответное сообщение содержит полное описание созданного объекта с указанием присвоенному ему внутреннему ИД. В ИС Предприятия необходимо обеспечить хранение этого идентификатора для дальнейшего использования в интеграционных потоках обмена информацией.
Марки транспортных средств
Справочник содержит перечень марок ТС, используемых Предприятием.

Регламент передачи информации: первоначальная инициализация, при занесении новой марки ТС в ИС Предприятия, при изменении наименования марки ТС (ранее экспортированной в ATMS) в ИС Предприятия.
Полный атрибутный состав
Пример создания записи:

[{
"externalId": "24",
"carrierId": 2,
"name": "LADA"
}]

Замечания по механизму обмена данными:


  • Перед первичной инициализацией данных необходимо проверить корректность используемых в ИС Предприятия наименований марок ТС, в случае отсутствия наименований — заполнить их. Кроме того, при первичной инициализации и последующих обменах данными предпочтительно наименования марок ТС приводить к верхнему регистру. Такой подход позволяет осуществлять дополнительную проверку уникальности и упрощает в дальнейшем использование справочных данных в интерфейсе ATMS.

  • При успешной операции создания записи в ATMS ответное сообщение содержит полное описание созданного объекта с указанием присвоенному ему внутреннему ИД. В ИС Предприятия необходимо обеспечить хранение этого идентификатора для дальнейшего использования в интеграционных потоках обмена информацией
Модели транспортных средств
В ATMS справочник моделей ТС, используемых Предприятием, является основой для контроля расхода топлива согласно нормативам. Также модель ТС является обязательным справочным атрибутом в описании транспортного средства.

Регламент передачи информации: первоначальная инициализация, при занесении новой модели ТС в ИС Предприятия, при изменении одного из атрибутов описания модели ТС (ранее экспортированной в ATMS) в ИС Предприятия.
Минимальный атрибутный состав (полный атрибутный состав см. в спецификации PublicAPI)
Пример создания записи:

[{
"externalId": "2474",
"brandId": "8",
"name": "NIVA",
"vehicleType": "WAGON",
"fuelConsumption": 0
}]
Необходимо обратить внимание

В ИС Предприятия может не существовать отдельных справочников марок и моделей ТС. Указание марок/моделей ТС может вестись в виде обычных текстовых полей, причем необязательных для заполнения. В этом случае возникает необходимость доработки ИС Предприятия для приведения данных к единому классификатору и последующей стандартизации данных.

Замечания по механизму обмена данными:


  • Перед первичной инициализацией данных необходимо проверить корректность используемых в ИС Предприятия наименований моделей ТС, в случае отсутствия наименований — заполнить их. Кроме того, при первичной инициализации и последующих обменах данными предпочтительно наименования моделей ТС приводить к верхнему регистру. Такой подход позволяет осуществлять дополнительную проверку уникальности и упрощает в дальнейшем использование справочных данных в интерфейсе ATMS.

  • При успешной операции создания записи в ATMS ответное сообщение содержит полное описание созданного объекта с указанием присвоенному ему внутреннему ИД. В ИС Предприятия необходимо обеспечить хранение этого идентификатора для дальнейшего использования в интеграционных потоках обмена информацией.
Типы пропусков на ТС
При передаче в ATMS описания ТС (см. раздел 5.7) допускается передача информации о действующих пропусках, выданных на данное ТС. При этом для пропуска необходимо указать его тип, основываясь на справочник ATMS. Таким образом, справочник «Типы пропусков на ТС» содержит перечень типов пропусков на ТС, используемых Предприятием.

Обмен информацией посредство PublicAPI отсутствует. Предполагается единовременная загрузка данных при подключении Предприятия к ATMS и получения внутренних идентификаторов для каждого загруженного типа пропуска. Для этого необходимо подготовить перечень типов пропусков, используемых на ТС, в виде уникальных аббревиатур, например, «ТТК», «МКАД» и др. и передать его специалистам технической поддержки ATMS. Кроме того, после заполнения справочника необходимо в ИС Предприятия сохранить внутренний ИД каждого типа пропуска для дальнейшего использования в интеграционных потоках обмена информацией.
Транспортные средства
Справочник содержит перечень ТС, используемых Предприятием, с установленным телематическим оборудованием, с которого поступают телематические данные и которое подписано на передачу этих данных в систему ATMS.

Регламент передачи информации: первоначальная инициализация, при занесении нового ТС в ИС Предприятия, при изменении одного из атрибутов описания ТС (ранее экспортированного в ATMS) в ИС Предприятия, при отключении (не физическом удалении) ТС.
Минимальный атрибутный состав (полный атрибутный состав см. в спецификации PublicAPI)
Пример создания записи для тягача:

{
  "externalId": "24571",
  "gosNumber": "Y965OE799",
  "autoPlanned": true,
  "modelId": 143,
  "carrierDivisionId": 5,
  "carrierOrganizationId": 2,
  "hired": false,
  "type": "TRUCK_TRACTOR",
  "bodyType": "AWNING",
  "tonnage": 1,
  "factTonnage": 1,
  "active": true,
  "passes": [
    {
      "typeId": 2,
      "number": "t123",
      "issuedBy": "ttt",
      "issuedDate": "2021-01-01",
      "expirationDate": "2023-02-01",
      "active": true
    },
    {
      "typeId": 3,
      "number": "q123",
      "issuedBy": "qqq",
      "issuedDate": "2021-03-01",
      "expirationDate": "2023-03-01",
      "active": true
    }
  ]
}
Пример создания записи для тягача:

{
  "externalId": "24571",
  "gosNumber": "Y965OE799",
  "autoPlanned": true,
  "modelId": 143,
  "carrierDivisionId": 5,
  "carrierOrganizationId": 2,
  "hired": false,
  "type": "TRUCK_TRACTOR",
  "bodyType": "AWNING",
  "tonnage": 1,
  "factTonnage": 1,
  "active": true,
  "passes": [
    {
      "typeId": 2,
      "number": "t123",
      "issuedBy": "ttt",
      "issuedDate": "2021-01-01",
      "expirationDate": "2023-02-01",
      "active": true
    },
    {
      "typeId": 3,
      "number": "q123",
      "issuedBy": "qqq",
      "issuedDate": "2021-03-01",
      "expirationDate": "2023-03-01",
      "active": true
    }
  ]
}
Пример обновления записи (удален один пропуск и добавлен новый – регулируется наличием/отсутствием атрибута «id»):

{
  "id": 2857,
  "active": true,
  "bodyType": "AWNING",
  "carrierDivisionId": 5,
  "carrierOrganizationId": 2,
  "externalId": "24571",
  "factTonnage": 10,
  "gosNumber": "Y965OE799",
  "hired": false,
  "modelId": 143,
  "tiltCoverDismantlingType": "BACK",
  "tonnage": 105,
  "type": "TRUCK_TRACTOR",
  "passes": [
    {
      "id": 1274,
      "active": true,
      "expirationDate": "2023-02-01",
      "issuedBy": "ttt",
      "issuedDate": "2021-01-01",
      "number": "t123",
      "typeId": 2
    },
    {
      "active": true,
      "expirationDate": "2025-03-01",
      "issuedBy": "qqq",
      "issuedDate": "2021-03-01",
      "number": "q123",
      "typeId": 1
    }
  ]
}
Необходимо обратить внимание
  • Во многих ИС Предприятий при описании ТС указание марки и модели ТС является не обязательным и зачастую представляет совмещенное текстовое поле. В ATMS напротив, атрибут марка и модель ТС являются неотъемлемыми (обязательными) свойствами ТС и поддерживаются в виде справочников. Поэтому предварительно необходимо обратить особое внимание на разделы 5.4 и 5.5. Таким образом, при первичной инициализации данных необходимо убедиться, что в ИС Предприятия для всех ТС указаны марка и модель.

  • В справочник должны заносится (передаваться посредством PublicAPI) только ТС с установленным телематическим оборудованием, с которого поступают телематические данные и которое подписано на передачу этих данных в систему ATMS.

  • В ATMS все водители распределены между дивизионами (см. раздел 5.3). Если в ИС Предприятия не поддерживается такое разделение, то необходимо его ввести искусственно, например, отнести все ТС к одному дивизиону.

Замечания по механизму обмена данными:


  • При успешной операции создания записи в ATMS ответное сообщение содержит полное описание созданного объекта с указанием присвоенному ему внутреннему ИД, а также присвоенные внутренние ИД для каждого пропуска. В ИС Предприятия необходимо обеспечить хранение этих идентификаторов для дальнейшего использования в интеграционных потоках обмена информацией.

  • Для осуществления изменения описания ТС необходимо предварительно получить текущее описание ТС (по внутреннему ИД ТС в ATMS), внести в него необходимые изменения и затем передать в виде обновления. При этом необходимо обратить внимание на установленные по умолчанию значения необязательных атрибутов (и без необходимости не изменять присвоенные значения). Также необходимо уделить внимание вложенному массиву пропусков на ТС: каждый пропуск на ТС приобретает отдельный атрибут «Внутренний ИД», который необходимо сохранять в ИС Предприятия. Кроме того, не указание пропуска или не указание «id» пропуска автоматически означает при передаче данных его удаление в ATMS.