С чего начать работу с железнодорожной накладной

Эта страница описывает работу с железнодорожной накладной.

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

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

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

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

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

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

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

7. После регистрации титула Т1 сохраните УИД из тега mt-id и используйте его для объединения титулов одной перевозки (подробнее — kl-id и mt-id).

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

9. Реализуйте обработку статусов регистрации титулов в ГИС ЭПД и событий об ошибках.

Как устроен документооборот железнодорожной накладной

Железнодорожная накладная состоит из пяти обязательных титулов, которые участники перевозки формируют, подписывают и отправляют последовательно. Диадок передает титулы в ГИС ЭПД, возвращает статусы их обработки и доставляет документы участникам.

• титул Т1 — информация грузоотправителя,

• титул Т2 — квитанция о приеме груза,

• титул Т3 — уведомление о прибытии,

• титул Т4 — сведения дорожной ведомости,

• титул Т5 — изменение финансового состояния.

Примечание

В Диадоке реализована работа только с обязательными титулами Т1—Т5. Необязательные титулы Т6—Т9 — переадресовка, сведения о составлении акта, перегрузка груза и (или) замена локомотива, отцепка вагонов — пока не поддерживаются.

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

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

Роли организации в железнодорожной накладной

Роль	Участие в документообороте	Что подписывает
Грузоотправитель	Участвует. Формирует и отправляет перевозчику титул Т1. По соглашению титул Т1 может направить перевозчик.	титул Т1*
Перевозчик	Участвует. Принимает груз, уведомляет о прибытии и оформляет финансовые итоги. По соглашению может направить титулы Т1 и Т4.	титулы Т2, Т3 и Т5; по соглашению титулы Т1 и Т4
Грузополучатель	Участвует. Получает комплект титулов Т1 и Т2, уведомление о прибытии и оформляет дорожную ведомость.	титул Т4*

* По соглашению титул Т1 может сформировать и подписать перевозчик вместо грузоотправителя, титул Т4 — перевозчик вместо грузополучателя.

Стадии

Участники документооборота оформляют железнодорожную накладную так:

• титул Т1 — грузоотправитель направил информацию о перевозке,

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

• титул Т3 — перевозчик уведомил грузополучателя о прибытии,

• титул Т4 — грузополучатель оформил дорожную ведомость,

• титул Т5 — перевозчик зафиксировал изменение финансового состояния.

Прием груза

Грузоотправитель подписывает титул Т1 и отправляет его перевозчику. По соглашению титул Т1 может направить перевозчик. Данные титула Т1 направляются в ГИС ЭПД. Перевозчик получает входящий титул Т1 и формирует в ответ титул Т2 — квитанцию о приеме груза. Данные титула Т2 направляются в ГИС ЭПД. После отправки титула Т2 грузополучатель получает комплект титулов Т1 и Т2.

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

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

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

• грузополучатель получает комплект титулов Т1 и Т2.

Прибытие и выдача груза

После прибытия груза перевозчик подписывает титул Т3 — уведомление о прибытии — и отправляет его грузополучателю. Данные титула Т3 направляются в ГИС ЭПД. Грузополучатель получает входящий титул Т3 и формирует в ответ титул Т4 — сведения дорожной ведомости. По соглашению титул Т4 может сформировать перевозчик. Данные титула Т4 направляются в ГИС ЭПД.

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

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

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

Финансовые итоги

После завершения перевозки перевозчик подписывает титул Т5 — изменение финансового состояния — и отправляет его грузоотправителю и грузополучателю. Данные титула Т5 направляются в ГИС ЭПД.

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

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

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

• API-ключ.

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

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

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

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

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

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

   Примечание

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

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

Чтобы создать железнодорожную накладную:

1. Изучите формат электронной транспортной железнодорожной накладной, утвержденный приказом ФНС России от 07.05.2026 № КЧ-1-26/297@, и требования к XML-файлам.

2. Сформируйте XML-файл титула в вашей учетной системе; подробнее — на странице Работа с железнодорожной накладной.

При создании учитывайте тип, версию и функцию каждого титула. Каждый титул отправляют отдельным сообщением методом PostMessage (V3).

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

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

Параметры титула железнодорожной накладной

Параметр	Описание	Доступные значения
TypeNamedId	Тип документа	LogisticsRailwayWaybill
Function	Функция титула в документообороте	reception_consignor — информация грузоотправителя (титул Т1); reception_carrier — квитанция о приеме груза (титул Т2); delivery_carrier — уведомление о прибытии груза (титул Т3); delivery_consignee — дорожная ведомость (титул Т4); cost_carrier — изменение финансового состояния (титул Т5).
Version	Версия документа	kl_rw_05_01_02

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

MessageId и EntityId

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

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

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

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

Каждый титул железнодорожной накладной создается как новое сообщение. Сущности подписи и статусов ссылаются на титул через идентификатор ParentEntityId.

Примечание

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

kl-id и mt-id

Для работы с железнодорожной накладной в учетных системах отслеживайте идентификаторы kl-id, mt-id и УИД_ТрНЖд:

• kl-id — внутренний идентификатор перевозки в Логистике; его можно использовать для поиска документов в конкретном ящике;

• mt-id — уникальный идентификатор транспортной железнодорожной накладной. ГИС ЭПД присваивает его после регистрации титула Т1;

• УИД_ТрНЖд — тот же уникальный идентификатор в XML-файле титула по формату ФНС.

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

После регистрации титула Т1 в ГИС ЭПД в ленте появится событие с обновленным состоянием документа. УИД_ТрНЖд будет записан в DocumentInfo.CustomData в теге с Key = "mt-id". Это значение указывают в элементе УИД_ТрНЖд всех следующих титулов железнодорожной накладной. Каждый титул железнодорожной накладной передается отдельным сообщением: для связи документов одной перевозки используйте mt-id и kl-id. Подробнее о статусах ГИС ЭПД — в разделе Информация о статусе обработки.

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

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

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

Идентификаторы железнодорожной накладной

Что хранить	Для чего
BoxId	Читать нужную ленту событий и получать документы
MessageId	Получать информацию по каждому сообщению и статусы титула
EntityId титула	Скачать XML и связать подпись или статус с титулом
mt-id	Связать статусы ГИС ЭПД с железнодорожной накладной в учетной системе
УИД_ТрНЖд	Указывать в последующих титулах железнодорожной накладной. Значение должно совпадать во всех титулах одной железнодорожной накладной
IndexKey последнего события	Продолжить чтение ленты без пропусков

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

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

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

• EntityType = Attachment,

• AttachmentType = OuterDocflow.

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

• DocflowNamedId — идентификатор внешнего документооборота; статусы ГИС ЭПД можно определить по значению DocflowNamedId = KlMt;

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

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

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

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

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

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

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

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

Событие со статусом может появиться позже самого титула. Поэтому при обработке ленты сохраняйте такие события и запрашивайте сообщение повторно, если родительская сущность еще не поступила.

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

В железнодорожной накладной титулы распределяются по подписантам. Все титулы одной железнодорожной накладной связывает идентификатор УИД_ТрНЖд.

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

Грузоотправитель формирует, подписывает и отправляет перевозчику титул Т1. По соглашению титул Т1 может сформировать перевозчик.

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

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

Грузоотправитель получает от перевозчика титул Т2 — квитанцию о приеме груза, от грузополучателя — титул Т4 — сведения дорожной ведомости, после завершения перевозки — от перевозчика титул Т5 — изменение финансового состояния.

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

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

Перевозчик получает от грузоотправителя титул Т1.

Чтобы сформировать титул Т2, используйте элемент УИД_ТрНЖд, атрибут ИдФайл и подпись титула Т1. Перевозчик формирует, подписывает и отправляет грузоотправителю титул Т2 — квитанцию о приеме груза. После отправки титула Т2 грузополучатель получает комплект титулов Т1 и Т2.

Затем перевозчик формирует, подписывает и отправляет грузополучателю титул Т3 — уведомление о прибытии.

Перевозчик получает от грузополучателя титул Т4 — сведения дорожной ведомости. Если это предусмотрено соглашением с грузополучателем, перевозчик формирует титул Т4 самостоятельно.

После завершения перевозки перевозчик формирует, подписывает и отправляет грузоотправителю и грузополучателю титул Т5 — изменение финансового состояния.

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

Входящий и исходящий поток: грузополучатель

Грузополучатель после отправки перевозчиком титула Т2 получает комплект титулов Т1 и Т2. После прибытия груза получает от перевозчика титул Т3 — уведомление о прибытии.

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

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

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

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

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

Грузополучатель формирует, подписывает и отправляет перевозчику титул Т4 — сведения дорожной ведомости. Если это предусмотрено соглашением с перевозчиком, титул Т4 формирует перевозчик. После завершения перевозки грузополучатель получает от перевозчика титул Т5 — изменение финансового состояния.

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