С чего начать работу с ЭТрН

Эта страница описывает работу с электронной транспортной накладной (ЭТрН).

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

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

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

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

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

5. Реализуйте чтение ленты событий по каждому ящику с фильтрами по типам документов. Примеры событий — на странице Лента событий для ЭТрН.

6. В событиях определяйте титулы и связывайте их с подписями по идентификатору ParentEntityId (подробнее — Обработка идентификаторов).

7. Заведите соответствие «УИД — MessageId» и группируйте по нему сущности перевозки.

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

9. При необходимости реализуйте обработку необязательных титулов Т5—Т8 и обработку событий об ошибках.

Как устроен документооборот ЭТрН

ЭТрН состоит из четырех обязательных и четырех необязательных титулов. Обязательные титулы попарно делятся на два двухтитульных документа:

• титулы Т1 и Т2 — документ погрузки,

• титулы Т3 и Т4 — документ выгрузки.

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

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

Роли организации в перевозке

Роль	Участие в документообороте	Что подписывает
Грузоотправитель*	Участвует, только если совпадает с лицом, осуществляющим погрузку (ЛОП). Иначе вместо него указывается лицо, осуществляющее погрузку.	титул Т1, если совпадает с лицом, осуществляющим погрузку; при необходимости титул Т6
Лицо, осуществляющее погрузку*	Участвует. Отпускает груз со склада отгрузки, указывается в разделе 8 ЭТрН.	титул Т1
Заказчик	Не участвует. Выступает заказчиком перевозки в схеме с экспедитором.	—
Перевозчик	Участвует. Транспортная компания, фактически выполняющая перевозку.	титулы Т2 и Т4; при необходимости титулы Т5, Т7 и Т8
Грузополучатель	Участвует. Адресат груза, лицо, фактически принимающее выгрузку.	титул Т3
Наблюдатель**	Не участвует. Получает копию перевозки.	—

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

** Наблюдатель — любая организация, которая будет получать свои титулы ЭТрН. Диадок принимает в одном документе не больше 100 наблюдателей. Подробнее про работу с наблюдателями — в разделе Добавление наблюдателей в титулы.

Стадии перевозки

Перевозка состоит из двух основных стадий:

• Стадия погрузки:

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

  • титул Т2 — началась перевозка.

• Стадия выгрузки:

  • титул Т3 — выгружено полностью, частично или с отказом в приемке,

  • титул Т4 — перевозка завершена.

Кроме основных стадий между погрузкой и выгрузкой в некоторых случаях может присутствовать стадия переадресовки и эстафеты. А также кроме перечисленных титулов ЭТрН может содержать необязательные титулы стоимости (Т5 и Т6).

Погрузка

При погрузке грузоотправитель подписывает титул Т1 и отправляет его перевозчику. Перевозчик получает входящий титул Т1 и формирует в ответ титул Т2.

В результате участники документооборота получают титулы:

• грузоотправитель получает титул Т2 с подписью перевозчика: погрузка завершена, перевозка началась;

• грузополучатель и наблюдатели получают входящий комплект из титулов Т1 и Т2 после того, как перевозчик подпишет титул Т2.

Выгрузка

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

В результате участники документооборота получают титулы:

• грузополучатель получает титул Т4 с подписью перевозчика;

• грузоотправитель и наблюдатели получают комплект из титулов Т3 и Т4 с подписями.

Название стадии для этого комплекта зависит от того, что грузополучатель указал в титуле Т3, и может иметь одно из следующих значений:

• «Перевозка завершена»,

• «Груз принят частично»,

• «Груз не принят».

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

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

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

• API-ключ.

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

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

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

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

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

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

   Примечание

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

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

Чтобы создать ЭТрН:

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

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

   • в вашей учетной системе;

   • с помощью метода генерации GenerateTitleXml; подробнее — на странице Генерация формализованного документа.

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

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

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

Параметры титула ЭТрН

Параметр	Описание	Доступные значения
TypeNamedId	Тип документа	LogisticsWaybill
Function	Функция титула в документообороте	reception — прием груза (титулы Т1 и Т2); delivery — выдача груза (титулы Т3 и Т4); relay — смена транспортного средства, прицепа или водителя (титул Т8); readdress — переадресовка (титул Т7); cost — сведения о стоимости (титулы Т5 и Т6); fwd — пересланный титул. Грузополучатель получает титулы Т1 и Т2. Наблюдатель получает титулы Т1—Т4, Т7 и Т8. Титулы Т5 и Т6 наблюдатель не получает.
Version	Версия документа	kl_trn_mt_05_01

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

MessageId и EntityId

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

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

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

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

Идентификаторы сообщения MessageId для входящего и исходящего документа обычно одинаковые. Исключение — титулы с Function = fwd: это Т1 и Т2 — в ящике грузополучателя и Т1—Т4, Т7 и Т8 — в ящике наблюдателя. Их идентификаторы MessageId отличаются от MessageId в ящике отправителя. У титулов Т1 и Т2 один MessageId, а у титулов Т3 и Т4 — другой.

Когда грузополучатель формирует и отправляет титул Т3, в его ящике появляются:

1. Новый документ с новым идентификатором MessageId — он общий для титулов Т3 и Т4.

2. События о вложениях и подписях.

3. Событие, которое связывает титул Т3 с титулом Т1 по идентификаторам УИД_ТрН и ИдФайл из XML-файла предыдущего титула Т2.

После подписания титула Т3 он поступает перевозчику с тем же MessageId. В этом же сообщении перевозчик формирует и подписывает титул Т4.

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 в ГИС ЭПД в ленте появится событие с обновленным состоянием документа. УИД_ТрН будет записан в DocumentInfo.CustomData в теге с Key = "mt-id". Это значение указывается в поле УИД_ТрН всех титулов перевозки. Подробнее о статусах ГИС ЭПД — в разделе Информация о статусе обработки.

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

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

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

Идентификаторы ЭТрН

Что хранить	Для чего
BoxId	Читать нужную ленту событий и получать документы
MessageId	Получать комплект титулов и его статусы. У титулов Т1 и Т2 один MessageId, у титулов Т3 и Т4 — другой
EntityId титула	Скачать XML и связать подпись или статус с титулом
kl-id	Связать документы перевозки в ответе метода GetDocflowEvents
mt-id	Группировать сущности и события перевозки
УИД_ТрН	Указывать во всех титулах перевозки, кроме Т1. По этому значению можно определить, к какой записи в учетной системе относится обновление
IndexKey последнего события	Продолжить чтение ленты без пропусков

Сохраните идентификатор mt-id и используйте его для группировки сущностей и событий перевозки.

Создайте соответствие «УИД — MessageId». По УИД_ТрН можно определить, к какой записи в учетной системе относится обновление.

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

Статус обработки титула во внешнем документообороте хранится в сущности 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.

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

Исходящий поток: лицо, осуществляющее погрузку

Организация в роли лица, осуществляющего погрузку, (ЛОП) отправляет исходящие титулы Т1. При отправке Диадок присваивает перевозке идентификатор kl-id. Он совпадает с MessageId.

Дальше настройте обработку так:

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

2. Дождитесь события, в котором ГИС ЭПД присвоит УИД. Прочитайте mt-id, как описано в разделе kl-id и mt-id, и сохраните его в вашей учетной системе.

3. Обрабатывайте события о подписании. Когда перевозчик подпишет титул, в ленте появится событие с тем же MessageId. Оно будет содержать сущности Attachment и Signature. При необходимости загрузите файлы.

4. Свяжите титулы Т3 и Т4 с перевозкой. У них будет другой идентификатор MessageId, но тот же УИД_ТрН. Соответствие «УИД — MessageId» поможет определить, к какой перевозке относится обновление.

Необязательно отслеживать все сущности: определите события, которые важны для вашей организации.

Если ЛОП выступает только грузоотправителем, оно получит титул Т3 вместе с титулом Т4 после подтверждения выгрузки перевозчиком. Стадия сразу получит одно из названий: «Перевозка завершена», «Груз принят частично» или «Груз не принят».

Грузоотправитель получает входящий титул Т5 с тем же MessageId, что и у перевозчика.

Метод GetDocflows (V5) по известным идентификаторам документов MessageId и EntityId возвращает актуальную информацию о документообороте этих документов. Поэтому при запросе только документа с титулами Т1 и Т2 не отобразится изменение статуса титула Т3, включая подпись грузополучателя. Чтобы отслеживать появление и изменения документа с титулами Т3 и Т4 и необязательные титулы Т5—Т8, вызовите метод GetDocflowEvents (V5) и свяжите документы перевозки по kl-id. Также можно использовать ленту событий.

Если интеграция уже использует kl-status, можно отслеживать значение этого тега. Тег обновляется автоматически только на документе приемки груза — титулах Т1 и Т2. В событиях появления или изменения титулов Т3—Т8 актуального kl-status не будет. Проверьте, что интеграционное решение обрабатывает нужные значения статуса и пустое значение. Если нужно различать частичную приемку и полный отказ или получать состояние каждого титула, дополнительно анализируйте титулы Т3 и Т4 и события из ответа метода GetDocflowEvents (V5). Подробнее про тег kl-status — в разделе Пользовательские данные (теги).

Входящий поток: грузополучатель, перевозчик и наблюдатель

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

Какой идентификатор MessageId получит входящий титул — зависит от роли:

• Перевозчик получает титулы Т1 и Т3 с тем же MessageId, что и у отправителя.

• Грузополучатель получает титулы Т1 и Т2 с Function = fwd. Их MessageId отличается от MessageId в ящике грузоотправителя.

• Наблюдатель получает копии титулов Т1—Т4, Т7 и Т8 с Function = fwd. Их MessageId отличается от MessageId в ящике отправителя.