С чего начать
Эта страница описывает работу с электронным заказом-заявкой (ЭЗЗ).
Порядок первых шагов
- Ознакомьтесь со статьями про авторизацию, порядок документооборота и устройство документооборота ЭЗЗ.
- Определите роли, в которых выступает ваша организация (подробнее — Роли организации).
- Подготовьте интеграционное решение и соберите справочник ящиков с API-ключами и доступами пользователей (подробнее — Подготовка интеграционного решения).
- Научитесь создавать документы (подробнее — Создание документов).
- Реализуйте чтение ленты событий по каждому ящику с фильтрами по типам документов.
- В событиях определяйте титулы и связывайте их с подписями по идентификатору
ParentEntityId(подробнее — Обработка идентификаторов). - Заведите соответствие «УИД —
MessageId» и группируйте по нему сущности заказа-заявки. - Реализуйте обработку титулов Т1 и Т2 (подробнее — Обработка потоков документов).
Как устроен документооборот ЭЗЗ
ЭЗЗ состоит из двух обязательных титулов:
- титул Т1 — титул грузоотправителя,
- титул Т2 — титул перевозчика.
Участники документооборота формируют все титулы до начала перевозки.
Роли организации
Каждая организация-участник документооборота ЭЗЗ играет свою роль в этом документообороте. От роли зависит, какие титулы организация подписывает и какой поток документов у нее появится.
Роли организации в заказе-заявке
| Роль | Участие в документообороте | Что подписывает |
|---|---|---|
| Грузоотправитель* | Участвует. Направляет заказ-заявку перевозчику. Получает титул Т2 | титул Т1 |
| Перевозчик | Участвует. Получает титул Т1, формирует титул Т2 и отправляет его грузоотправителю | титул Т2 |
* Если к перевозке привлекают экспедитора, титул Т1 подписывает он.
Стадии
Участники документооборота оформляют заказ-заявку до начала перевозки:
- титул Т1 — грузоотправитель направил заказ-заявку перевозчику,
- титул Т2 — перевозчик подтвердил заказ-заявку или отказал в нем.
Перевозка
Грузоотправитель подписывает титул Т1 и отправляет его перевозчику. Данные титула Т1 направляются в ГИС ЭПД. Перевозчик получает входящий титул Т1 и формирует в ответ титул Т2. Данные титула Т2 направляются в ГИС ЭПД.
В результате участники документооборота получают титулы:
- перевозчик получает титул Т1 с подписью грузоотправителя;
- грузоотправитель получает титул Т2: подтверждение заказа-заявки или отказ перевозчика.
Данные заказа-заявки можно передать в ЭТрН в атрибутах НомЗак, ДатаЗак, ИдЗак.
Подготовка интеграционного решения
Чтобы настроить интеграцию для обмена ЭЗЗ, нужно для каждой организации-участника документооборота получить следующие данные:
- Идентификатор ящика
BoxId: его можно получить методом GetMyOrganizations. Этот идентификатор постоянный для каждого ящика и не изменяется. - API-ключ.
- Лицензия, купленная для этого ящика.
- Учетная запись пользователя с доступом в ящик и возможностью авторизации по OIDC. Назначьте пользователю доступ к отдельным наборам ящиков организаций, а не ко всем ящикам сразу, или заведите техническую учетную запись.
Спроектируйте интеграционное решение следующим образом:
-
Заведите справочник организаций и их API-ключей.
-
Создайте единственную техническую учетную запись пользователя с доступом ко всем ящикам или реализуйте добавление и удаление пользователей, например, на случай найма/увольнения сотрудника. Подробнее — на странице Работа с сотрудниками.
-
Реализуйте обновление токена доступа с помощью Обновление токена.
к сведениюПри обновлении токена доступа с помощью
refresh_tokenвы получите новую пару токенов, и повторное подтверждение авторизации со стороны пользователя не потребуется. Подтверждение авторизации запрашивается только один раз — при первом выпуске токена. Подробнее — на странице Авторизация.
Создание документов
Чтобы создать ЭЗЗ:
- Изучите формат ЭЗЗ, утвержденный приказом ФНС России от 13.02.2023 № ЕД-7−26/108@.
- Создайте документ одним из следующих способов:
- в вашей учетной системе;
- с помощью метода генерации GenerateTitleXml; подробнее — на странице Работа с заказами-заявками.
При создании учитывайте тип, версию и функцию каждого титула.
Тип, версия и функция
Каждый титул ЭЗЗ в Диадоке имеет свой набор параметров, определяющих его поведение, — тип документа, версию и функцию. Отправитель документа задает их при создании документа в структуре 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.
Чтобы определить титул, к которому относится статус:
- Получите
ParentEntityIdсущностиEntityс типомOuterDocflow— это идентификатор родительской сущности в том же сообщении. - Найдите по идентификатору
ParentEntityIdродительскую сущность; обратите внимание, что она могла появиться в сообщении раньше, чем событие со статусом. - Используйте идентификатор сообщения
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 с подписью.
При обработке события:
- Получите идентификатор сообщения
MessageIdи идентификатор сущностиEntityIdтитула. - Вызовите метод GetEntityContent (V4) и загрузите XML-файл титула (необязательно).
- Дождитесь статуса ГИС ЭПД и сохраните
mt-id. Это значение укажите в элементеУИД_Зактитула Т2. - Сформируйте титул Т2 и отправьте его методом PostMessagePatch (V4).