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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • титул Т1 — титул заказчика транспортно-экспедиционных услуг,

  • титул Т2 — титул экспедитора,

  • титул Т3 — опциональный титул заказчика на отзыв поручения.

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

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

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

Роль

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

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

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

Участвует. Направляет поручение экспедитору. Получает титул Т2

титул Т1, при необходимости титул Т3

Экспедитор

Участвует. Получает титул Т1, формирует титул Т2 и отправляет его заказчику

титул Т2

Стадии

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

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

  • титул Т2 — экспедитор подтвердил поручение,

  • титул Т3 — заказчик отозвал поручение (необязательно).

Формат поручения экспедитору не предусматривает отказ экспедитора. Если экспедитор не подтверждает поручение, он не формирует титул Т2.

Выдача поручения

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

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

Подтверждение поручения

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

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

Если экспедитор не подтверждает поручение, он не формирует титул Т2. Отказа экспедитора формат не предусматривает.

Отзыв поручения

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

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

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

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

  • API-ключ.

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

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

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

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

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

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

    Примечание

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

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

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

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

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

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

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

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

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

Параметр

Описание

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

TypeNamedId

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

LogisticsForwardingOrder

Function

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

default — поручение экспедитору (титулы Т1—Т3).

Version

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

kl_porek_wt3_05_02_01

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

MessageId и EntityId

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

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

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

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

Титул Т1 создается как новое сообщение. Титулы Т2 и Т3 — дополнения к этому сообщению: их отправляют методом PostMessagePatch (V4). У титулов Т1—Т3 один идентификатор MessageId. Сущности подписи и статусов ссылаются на титул через идентификатор ParentEntityId.

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". Это значение указывают в элементе УИД_ПорЭксп последующих титулов поручения. Для нового титула Т1 поле необязательно. Подробнее о статусах ГИС ЭПД — в разделе Информация о статусе обработки.

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

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

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

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

Что хранить

Для чего

BoxId

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

MessageId

Получать комплект титулов и его статусы. У титулов Т1—Т3 один MessageId

EntityId титула

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

mt-id

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

УИД_ПорЭксп

Указывать в последующих титулах ПЭ. Значение должно совпадать во всех титулах одного поручения. Для нового титула Т1 поле необязательно

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. Получите ParentEntityId сущности Entity с типом OuterDocflow — это идентификатор родительской сущности в том же сообщении.

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

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

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

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

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

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

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

Когда экспедитор подпишет титул Т2, в ленте появится событие с тем же идентификатором MessageId. Оно будет содержать сущности Attachment и Signature.

При отзыве поручения сформируйте титул Т3 и отправьте его методом PostMessagePatch (V4). Затем обработайте статусы его доставки и регистрации в ГИС ЭПД.

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

Входящий поток: экспедитор

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

Экспедитор может подтвердить поручение титулом Т2 или не отвечать на входящий титул Т1. Отказа экспедитора формат не предусматривает: титул отказа не формируйте.

Если экспедитор подтверждает поручение, при обработке события:

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

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

  3. Дождитесь статуса ГИС ЭПД и сохраните mt-id. Это значение укажите в элементе УИД_ПорЭксп титула Т2.

  4. Сформируйте титул Т2 и отправьте его методом PostMessagePatch (V4).

  5. Отслеживайте последующие события: статусы ГИС ЭПД и, при необходимости, входящий титул Т3 об отзыве поручения.