С чего начать работу с ЭПЛ

Эта страница описывает работу с электронным путевым листом (ЭПЛ).

Порядок первых шагов

Для перевозчика

  1. Ознакомьтесь со статьями про авторизацию, порядок документооборота и устройство документооборота ЭПЛ.

  2. Определите роли, в которых выступает ваша организация (подробнее — Роли организации).

  3. Добавьте в вашу организацию сотрудников и водителей. Назначьте пользователям роли: медицинский работник, механик или водитель. Выполните этот шаг только в том случае, если часть ваших сотрудников будет работать с документооборотом ЭПЛ через веб-версию Диадок.Логистики (необязательно).

  4. Подготовьте интеграционное решение и соберите справочник ящиков с API-ключами и доступами пользователей (подробнее — Подготовка интеграционного решения).

  5. Научитесь создавать документы (подробнее — Создание документов).

  6. Реализуйте чтение ленты событий по каждому ящику с фильтрами по типам документов.

  7. Сохраняйте УИД путевого листа, идентификатор сообщения MessageId и идентификаторы сущностей EntityId (подробнее — Обработка идентификаторов).

  8. Реализуйте отправку титула Т1 и последовательную обработку обязательных титулов Т2—Т5 (подробнее — Обработка потоков документов).

  9. Добавьте обработку титула Т6, QR-кода и ошибок ГИС ЭПД (подробнее — QR-код и Статусы обработки в ГИС ЭПД).

Для медицинской организации

  1. Ознакомьтесь со статьями про авторизацию, порядок документооборота и устройство документооборота ЭПЛ.

  2. Определите роли, в которых выступает ваша организация (подробнее — Роли организации).

  3. Добавьте в вашу организацию сотрудников. Назначьте сотрудникам роль «Медицинский работник». Выполните этот шаг только в том случае, если часть ваших сотрудников будет работать с документооборотом ЭПЛ через веб-версию Диадок.Логистики (необязательно).

  4. Подготовьте интеграционное решение и соберите справочник ящиков с API-ключами и доступами пользователей (подробнее — Подготовка интеграционного решения).

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

  6. Научитесь создавать документы (подробнее — Создание документов).

  7. Реализуйте чтение ленты событий по каждому ящику с фильтрами по типам документов.

  8. Научитесь в ленте событий распознавать титулы Т1 и Т5 от перевозчика.

  9. Сохраняйте УИД путевого листа, идентификатор сообщения MessageId и идентификаторы сущностей EntityId (подробнее — Обработка идентификаторов).

Как устроен документооборот ЭПЛ

ЭПЛ состоит из пяти обязательных титулов и одного необязательного:

  • титул Т1 — особенности перевозки,

  • титул Т2 — предрейсовый медосмотр,

  • титул Т3 — технический осмотр,

  • титул Т4 — показания одометра перед рейсом,

  • титул Т5 — показания одометра после рейса,

  • титул Т6 — послерейсовый медосмотр.

Титул Т6 становится обязательным в том случае, если в титуле Т1 указан признак обязательного послерейсового медосмотра.

Роли организации

Каждая организация-участник документооборота ЭПЛ играет свою роль в этом документообороте. От роли зависит, какие титулы организация подписывает и какой поток документов у нее появится.

Роли организации в путевом листе

Роль

Участие в документообороте

Что подписывает

Перевозчик

Участвует. Организация-отправитель путевого листа. Осуществляет перевозку

титулы Т1, Т2*, Т3, Т4, Т5 и Т6*

Внешняя медицинская организация

Участвует. Проводит предрейсовый медосмотр. Послерейсовый медосмотр проводит в том случае, если он предусмотрен.

титулы Т2 и Т6

* Перевозчик не подписывает титулы Т2 и Т6 в том случае, если медосмотры проводит внешняя медицинская организация.

Примечание

Водитель не подписывает ЭПЛ. После подписания титула Т1 водитель может получить сведения по путевому листу, после подписания титула Т4 — QR-код для предъявления инспектору.

Стадии рейса

Путевой лист проходит две стадии:

  • Стадия до рейса:

    • титул Т1 — перевозчик указал особенности перевозки,

    • титул Т2 — водитель прошел предрейсовый медосмотр,

    • титул Т3 — транспортное средство прошло технический осмотр,

    • титул Т4 — зафиксированы показания одометра перед рейсом.

  • Стадия после рейса:

    • титул Т5 — зафиксированы показания одометра после рейса,

    • титул Т6 — водитель прошел послерейсовый медосмотр.

До рейса

Перед рейсом перевозчик подписывает титул Т1. Медработник проводит предрейсовый медосмотр водителя и подписывает титул Т2. Если водителей несколько, медработник подписывает титул Т2 для каждого из них. Если водитель не прошел медосмотр, медработник подписывает уведомление об уточнении: после этого весь ЭПЛ будет аннулирован, и его нужно будет оформить заново. Подробнее в разделе Обработка потоков документов.

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

Одометрист подписывает титул Т4. Подписанные титулы Т1—Т4 автоматически направляются в ГИС ЭПД. После этого водитель начинает рейс.

После рейса

После рейса одометрист подписывает титул Т5. Медработник формирует и подписывает титул Т6 в том случае, если послерейсовый медосмотр предусмотрен.

Смена водителя в рейсе

Если на длительном рейсе без заезда в гараж меняется водитель, одометрист подписывает титул Т5 и ЭПЛ закрывается. Для нового водителя оформляют новый ЭПЛ со ссылкой на предыдущий документ:

  • перевозчик подписывает титул Т1,

  • медработник подписывает титул Т2,

  • одометрист подписывает титул Т4.

Титулы Т1, Т2 и Т4 нового ЭПЛ направляются в ГИС ЭПД, и новый водитель продолжает рейс. После рейса одометрист подписывает титул Т5. Медработник подписывает титул Т6 в том случае, если послерейсовый медосмотр предусмотрен.

Подготовка интеграционного решения

Чтобы настроить интеграцию для обмена ЭПЛ, нужно для каждой организации-участника документооборота получить следующие данные:

  • Идентификатор ящика BoxId: его можно получить методом GetMyOrganizations. Этот идентификатор постоянный для каждого ящика и не изменяется.

  • API-ключ.

  • Лицензия, купленная для этого ящика.

  • Учетная запись пользователя с доступом в ящик и возможностью авторизации по OIDC. Назначьте пользователю доступ к отдельным наборам ящиков организаций, а не ко всем ящикам сразу, или заведите техническую учетную запись.

Спроектируйте интеграционное решение следующим образом:

  1. Заведите справочник организаций и их API-ключей.

  2. Создайте единственную техническую учетную запись пользователя с доступом ко всем ящикам или реализуйте добавление и удаление пользователей, например, на случай найма/увольнения сотрудника. Подробнее — на странице Работа с сотрудниками.

  3. Реализуйте обновление токена доступа с помощью refresh_token.

    Примечание

    При обновлении токена доступа с помощью refresh_token вы получите новую пару токенов, и повторное подтверждение авторизации со стороны пользователя не потребуется. Подтверждение авторизации запрашивается только один раз — при первом выпуске токена. Подробнее — на странице Авторизация.

Создание документов

Чтобы создать ЭПЛ:

  1. Изучите формат ЭПЛ, утвержденный приказом ФНС России от 17.02.2023 № ЕД-7−26/116@.

  2. Создайте документ одним из следующих способов:

При создании учитывайте тип, версию и функцию каждого титула.

Тип, версия и функция

Каждый титул ЭПЛ в Диадоке имеет свой набор параметров, определяющих его поведение, — тип документа, версию и функцию. Отправитель документа задает их при создании документа в структуре DocumentAttachment. Получить эти значения для существующего документа можно из структуры Document.

Параметры титула ЭПЛ

Параметр

Описание

Доступные значения

TypeNamedId

Тип документа

LogisticsEpl

Function

Функция титула в документообороте

ShippingTerms — особенности перевозки (титул Т1);

CheckupBefore — предрейсовый медосмотр (титул Т2);

TechInspection — технический осмотр (титул Т3);

OdometerBefore — показания одометра перед рейсом (титул Т4);

OdometerAfter — показания одометра после рейса (титул Т5);

CheckupAfter — послерейсовый медосмотр (титул Т6).

Version

Версия документа

kl_epl_05_01_01

Обработка идентификаторов

MessageId и EntityId

Для работы с ЭПЛ в ящике организации нужны два идентификатора — MessageId и EntityId. Это идентификаторы документа в Диадоке. С помощью этих идентификаторов можно найти документ в ящике, сформировать ответный титул или выполнить другие действия с документом.

Каждое сообщение Message — отдельный пакет с набором сущностей Entity. Сущностью может быть документ, подпись, машиночитаемая доверенность (МЧД) и другие объекты.

Идентификатор сообщения MessageId идентифицирует сообщение, а не отдельный документ. После отправки сообщения сохраните его: по нему можно получить все данные сообщения методом GetMessage (V6).

Идентификаторы сущности EntityId уникальны в каждом ящике. У каждого получателя при появлении новой сущности возникают собственные события. События из ящика отправителя в ящик получателя не передаются.

Примечание

Не используйте идентификатор сообщения MessageId для группировки титулов одного ЭПЛ. Все титулы находятся в разных сообщениях.

kl-id и mt-id

Для работы с ЭПЛ в учетных системах отслеживайте и другие идентификаторы — kl-id и mt-id:

  • kl-id — внутренний идентификатор перевозки. Он совпадает с идентификатором сообщения MessageId титула Т1 независимо от того, кто отправил титул. У исходящих документов этот тег указан первым.

  • mt-id — УИД_ПЛ, общий идентификатор перевозки; он связывает все титулы, события и документы в Диадоке и Минтрансе.

Они хранятся в Диадоке как пользовательские данные документа — в поле DocumentInfo.CustomData сущности документа, которая в свою очередь входит в состав сообщения Message. Поле CustomData содержит список тегов CustomDataItem с полями Key и Value. У документов одного путевого листа в Key Диадок записывает kl-id (для исходящих документов) и mt-id (для входящих документов).

До формирования титула Т1 получите УИД из пула Минтранса и укажите его в обязательном элементе УИД_ПЛ XML-файла титула Т1. Это же значение укажите в элементе УИД_ПЛ всех последующих титулов этого путевого листа. В поле DocumentInfo.CustomData тег с Key = mt-id содержит подтвержденное значение элемента УИД_ПЛ.

Подробнее про возможные теги ЭПЛ — в разделе Пользовательские данные (теги).

Хранение идентификаторов

Для обработки ЭПЛ сохраните в учетной системе идентификаторы:

Идентификаторы ЭПЛ

Что хранить

Для чего

BoxId

Читать нужную ленту событий и получать документы

MessageId

Получать комплект титулов и его статусы

EntityId титула

Скачать XML и связать подпись или статус с титулом

mt-id

Связать статусы ГИС ЭПД с ЭПЛ в учетной системе

УИД_ПЛ

Указывать в последующих титулах ЭПЛ. Значение должно совпадать во всех титулах одного путевого листа

IndexKey последнего события

Продолжить чтение ленты без пропусков

Сохраните идентификатор УИД_ПЛ и используйте его для группировки титулов, событий и статусов ГИС ЭПД, даже если титулы находятся в разных сообщениях.

Статусы обработки в ГИС ЭПД

Статус обработки титула во внешнем документообороте хранится в сущности Entity с полями:

  • EntityType = Attachment,

  • AttachmentType = OuterDocflow.

Поле Entity.OuterDocflow содержит структуру OuterDocflowInfo. В ней хранятся:

  • DocflowNamedId — идентификатор внешнего документооборота;

  • Status — статус обработки титула;

  • дополнительные данные в Status.Details, в том числе mt-id и kl-id.

Если обработка завершилась с ошибкой, Entity.OuterDocflow.Status.Type будет иметь значение Error. Код и текст ошибки можно найти в элементах Entity.OuterDocflow.Status.Details.

Чтобы определить титул, к которому относится статус:

  1. Получите ParentEntityId сущности Entity с типом OuterDocflow — это идентификатор родительской сущности в том же сообщении.

  2. Найдите по идентификатору ParentEntityId родительскую сущность; обратите внимание, что она могла появиться в сообщении раньше, чем событие со статусом.

  3. Используйте идентификатор сообщения MessageId события, чтобы получить сообщение методом GetMessage (V6).

Идентификатор MessageId идентифицирует все сообщение, а не отдельный документ. Конкретный титул нужно определить по родительской сущности ParentEntityId.

QR-код

После регистрации документа ГИС ЭПД может прислать статус QR. В событии будет вложение Attachment с идентификатором сущности QR-кода. У вложения есть атрибут Attachment.Entity.EntityId.

Чтобы скачать QR-код, вызовите метод GetEntityContent (V4) для этого идентификатора EntityId. В ответе придет бинарное содержимое GIF-файла. QR-код можно передать в приложение водителя или показать на экране мобильного устройства для предъявления инспектору.

Обработка потоков документов

В ЭПЛ титулы распределяются по подписантам. Все титулы одного путевого листа связывает идентификатор УИД_ПЛ.

Исходящий поток: перевозчик

Перевозчик — организация-отправитель путевого листа. Он формирует и отправляет:

  • титул Т1 — условия и особенности перевозки;

  • титул Т3 — технический осмотр;

  • титул Т4 — показания одометра перед рейсом;

  • титул Т5 — показания одометра после рейса;

  • титулы Т2 и Т6 — предрейсовый и послерейсовый медосмотр. Эти титулы перевозчик формирует и отправляет только в том случае, если сам проводит медосмотры.

Перед формированием титула Т1 получите УИД из пула Минтранса и укажите его в элементе УИД_ПЛ. Используйте этот же УИД в следующих титулах путевого листа.

После отправки каждого титула сохраните его идентификатор сообщения MessageId и идентификатор сущности EntityId. По идентификатору сообщения MessageId метод GetMessage (V6) возвращает сообщение и статусы обработки титула в поле Entity.OuterDocflow. Чтобы обновить статусы вручную, вызовите этот метод для каждого сохраненного идентификатора MessageId.

Для ЭПЛ не используйте тег kl-id как идентификатор путевого листа и не сопоставляйте его с идентификатором сообщения MessageId.

Обрабатывайте события о появлении титула, подписи, статуса ГИС ЭПД и QR-кода. Необязательно отслеживать все сущности: определите события, которые важны для вашей организации.

Исходящий поток: внешняя медицинская организация

Внешняя медицинская организация может проводить медосмотры и отправлять:

  • титул Т2 — предрейсовый медосмотр;

  • титул Т6 — послерейсовый медосмотр, в том случае, если он обязателен.

Чтобы сформировать титул Т2, используйте элемент УИД_ПЛ, атрибут ИдФайл и подпись титула Т1.

Чтобы сформировать титул Т6, используйте эти данные из титула Т5. Если водителей несколько, создайте отдельные титулы Т2 и Т6 для каждого водителя.

Сохраняйте идентификатор сообщения MessageId, идентификатор сущности EntityId, атрибут ИдФайл и подпись каждого титула. Используйте эти данные для обработки статусов и формирования следующего титула.

Если водитель или водители не прошли предрейсовый медосмотр по титулу Т2, медработник подписывает уведомление об уточнении (УоУ). Если водителей несколько, медработник подписывает УоУ для каждого из них. Если хотя бы один из водителей не прошел медосмотр, документооборот ЭПЛ будет закрыт.

Входящий поток

Организация получает входящий титул в том случае, если он адресован в ее ящик. Появление входящего титула фиксируется как событие.

При обработке события:

  1. Получите идентификатор сообщения MessageId и идентификатор сущности EntityId титула.

  2. Вызовите метод GetEntityContent (V4) и загрузите XML-файл титула (необязательно).

  3. Сохраните элемент УИД_ПЛ, атрибут ИдФайл и подпись титула.

  4. Получите и сохраните статус ГИС ЭПД из поля Entity.OuterDocflow.

Каждый титул ЭПЛ обрабатывайте отдельно. Не рассчитывайте, что несколько титулов находятся в одном сообщении или имеют общий идентификатор MessageId. Для группировки титулов, событий и статусов одного путевого листа используйте идентификатор УИД_ПЛ.