С чего начать
Эта страница описывает работу с электронной транспортной накладной (ЭТрН).
Порядок первых шагов
- Ознакомьтесь со статьями про авторизацию, порядок документооборота и устройство документооборота ЭТрН.
- Определите роли, в которых выступает ваша организация (подробнее — Роли организации).
- Подготовьте интеграционное решение и соберите справочник ящиков с API-ключами и доступами пользователей (подробнее — Подготовка интеграционного решения).
- Научитесь создавать документы (подробнее — Создание документов).
- Реализуйте чтение ленты событий по каждому ящику с фильтрами по типам документов. Примеры событий — на странице Лента событий для ЭТрН.
- В событиях определяйте титулы и связывайте их с подписями по идентификатору
ParentEntityId(подробнее — Обработка идентификаторов). - Заведите соответствие «УИД —
MessageId» и группируйте по нему сущности перевозки. - Реализуйте обработку обязательных титулов Т1—Т4 (подробнее — Обработка потоков документов).
- При необходимости реализуйте обработку необязательных титулов Т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. Назначьте пользователю доступ к отдельным наборам ящиков организаций, а не ко всем ящикам сразу, или заведите техническую учетную запись.
Спроектируйте интеграционное решение следующим образом:
-
Заведите справочник организаций и их API-ключей.
-
Создайте единственную техническую учетную запись пользователя с доступом ко всем ящикам или реализуйте добавление и удаление пользователей, например, на случай найма/увольнения сотрудника. Подробнее — на странице Работа с сотрудниками.
-
Реализуйте обновление токена доступа с помощью Обновление токена.
к сведениюПри обновлении токена доступа с помощью
refresh_tokenвы получите новую пару токенов, и повторное подтверждение авторизации со стороны пользователя не потребуется. Подтверждение авторизации запрашивается только один раз — при первом выпуске токена. Подробнее — на странице Авторизация.
Создание документов
Чтобы создать ЭТрН:
- Изучите формат ЭТрН, утвержденный приказом ФНС России от 09.12.2021 № ЕД-7−26/1065@.
- Создайте документ одним из следующих способов:
- в вашей учетной системе;
- с помощью метода генерации 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, в его ящике появляются:
- Новый документ с новым идентификатором
MessageId— он общий для титулов Т3 и Т4. - События о вложениях и подписях.
- Событие, которое связывает титул Т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.
Чтобы определить титул, к которому относится статус:
- Получите
ParentEntityIdсущностиEntityс типомOuterDocflow— это идентификатор родительской сущности в том же сообщении. - Найдите по идентификатору
ParentEntityIdродительскую сущность; обратите внимание, что она могла появиться в сообщении раньше, чем событие со статусом. - Используйте идентификатор сообщения
MessageIdсобытия, чтобы получить сообщение методом GetMessage (V6).
Идентификатор MessageId идентифицирует все сообщение, а не отдельный документ. Конкретный титул нужно определить по родительской сущности ParentEntityId.
Обработка потоков документов
Исходящий поток: лицо, осуществляющее погрузку
Организация в роли лица, осуществляющего погрузку, (ЛОП) отправляет исходящие титулы Т1. При отправке Диадок присваивает перевозке идентификатор kl-id. Он совпадает с MessageId.
Дальше настройте обработку так:
- Сохраните идентификатор сообщения
MessageId. По нему можно получить текущий статус перевозки в полеEntity.OuterDocflowструктуры OuterDocflowInfo. Чтобы обновить статусы без чтения ленты событий, вызовите метод GetMessage (V6) для каждого сохраненногоMessageId. - Дождитесь события, в котором ГИС ЭПД присвоит УИД. Прочитайте
mt-id, как описано в разделе kl-id и mt-id, и сохраните его в вашей учетной системе. - Обрабатывайте события о подписании. Когда перевозчик подпишет титул, в ленте появится событие с тем же
MessageId. Оно будет содержать сущностиAttachmentиSignature. При необходимости загрузите файлы. - Свяжите титулы Т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в ящике отправителя.