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

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

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

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

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

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

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

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

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

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

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

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

  8. Реализуйте обработку титула экспедитора (подробнее — Обработка потоков документов).

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

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

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

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

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

Роли организации в экспедиторской расписке

Роль

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

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

Экспедитор

Участвует. Получает груз для перевозки, формирует и отправляет экспедиторскую расписку заказчику

титул экспедитора

Заказчик транспортно-экспедиционных услуг

Участвует. Получает подписанную экспедиторскую расписку

—

Стадии

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

  • титул экспедитора — экспедитор получил груз для перевозки и направил расписку заказчику.

Выдача расписки

Экспедитор получает груз для перевозки, подписывает титул экспедитора и отправляет его заказчику. Данные титула направляются в ГИС ЭПД.

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

  • заказчик получает титул экспедитора с подписью экспедитора.

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

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

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

  • API-ключ.

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

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

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

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

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

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

    Примечание

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

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

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

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

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

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

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

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

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

Параметр

Описание

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

TypeNamedId

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

LogisticsForwardingReceipt

Function

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

default — экспедиторская расписка (титул экспедитора).

Version

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

kl_fr_05_01_02

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

MessageId и EntityId

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

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

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

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

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

Для входящей экспедиторской расписки заказчик получает подписанный титул и события о связанных сущностях. Для обработки документа связывайте подписи и статусы с титулом по ParentEntityId.

kl-id и mt-id

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

  • kl-id — внутренний идентификатор документа;

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

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

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

После регистрации титула в ГИС ЭПД в ленте появится событие с обновленным состоянием документа. УИД_ЭкспР будет записан в DocumentInfo.CustomData в теге с Key = "mt-id". Подробнее о статусах ГИС ЭПД — в разделе Информация о статусе обработки.

При замене экспедиторской расписки укажите УИД заменяемого документа в элементе УИД_ПредЭкспР. Если ГИС ЭПД вернет ответ об ошибке, экспедитор формирует новую экспедиторскую расписку с исправлениями и заполняет элементы ИспрФО, ИдИсхФайл и УИД_ЭкспР.

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

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

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

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

Что хранить

Для чего

BoxId

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

MessageId

Получать титул и его статусы

EntityId титула

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

mt-id

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

УИД_ЭкспР

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

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

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

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

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

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

  2. Читайте ленту событий. Статус регистрации экспедиторской расписки в ГИС ЭПД будет передан в сущности OuterDocflow.

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

  4. После успешной регистрации прочитайте в деталях статуса mt-id и сохраните его в учетной системе. Как прочитать mt-id, описано в разделе kl-id и mt-id.

  5. Если статус имеет тип Error, обработайте код и текст ошибки из Status.Details.

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

Входящий поток: заказчик

Заказчик получает подписанный титул экспедитора от экспедитора. Ответный титул не требуется.

Настройте обработку так:

  1. В ленте событий определяйте появление входящей экспедиторской расписки.

  2. Получите сообщение по MessageId методом GetMessage (V6), распознайте титул и связанную с ним подпись.

  3. Сохраняйте MessageId, УИД экспедиторской расписки и связь с документом в учетной системе.

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

  5. При необходимости отслеживайте статусы обработки документа в ГИС ЭПД. Связывайте статусы с титулом по ParentEntityId.