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

Эта страница описывает работу с электронным заказом-заявкой (ЭЗЗ).

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

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

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

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

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

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

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

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

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

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

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

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

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

Участники документооборота формируют все титулы до начала перевозки.

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

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

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

Роль

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

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

Грузоотправитель*

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

титул Т1

Перевозчик

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

титул Т2

* Если к перевозке привлекают экспедитора, титул Т1 подписывает он.

Стадии

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

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

  • титул Т2 — перевозчик подтвердил заказ-заявку или отказал в нем.

Перевозка

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

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

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

  • грузоотправитель получает титул Т2: подтверждение заказа-заявки или отказ перевозчика.

Данные заказа-заявки можно передать в ЭТрН в атрибутах НомЗак, ДатаЗак, ИдЗак.

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

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

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

  • API-ключ.

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

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

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

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

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

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

    Примечание

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

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

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

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

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

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

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

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

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

Параметр

Описание

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

TypeNamedId

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

LogisticsOrderRequest

Function

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

default — заказ-заявка (титулы Т1 и Т2).

Version

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

zakzvper_05_01_01

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

MessageId и EntityId

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

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

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

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

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

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

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

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

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

Что хранить

Для чего

BoxId

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

MessageId

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

EntityId титула

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

mt-id

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

УИД_Зак

Указывать в последующих титулах ЭЗЗ. Значение должно совпадать во всех титулах одного заказа-заявки

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

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

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

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

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

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

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

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

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

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

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

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