Многотитульные документы
Раньше API Диадока работал только с одно-, двух- и трехтитульными документами. Но существуют многотитульные документы, которые могут содержать любое количество титулов в зависимости от их бизнес-сценария. Примером многотитульного документа является электронная транспортная накладная или поручение экспедитору. Чтобы работать с такими документами, в API реализованы отдельные версии методов.
Отправка документа нескольким участникам и их роли описаны на странице Многосторонние документы.
Определение количества титулов и участников
Перед отправкой или получением многотитульного документа определите количество его титулов и участников — они зависят от типа документа и вида документооборота:
- Получите тип документа и список его титулов методом GetDocumentTypes (V3). Инструкция о получении данных из метода
GetDocumentTypesприведена на странице Получение информации о типе документа. Для каждого титула зафиксируйте значениеTitleIndex— оно понадобится при отправке и получении титула. - Получите свойства вида документооборота методом GetWorkflowsSettings (V3). Свойства документооборота
DocumentWorkflowSettingsV3содержат ожидаемое поведение по титулам для каждого участника документооборота — они хранятся в структуреParticipantActionSettingV3с соответствующим номером титулаTitleIndex. - Определите участников документа и их роли. Роль указывайте в формате
namespace:name, напримерdefault:senderилиdefault:recipient. Список участников и ролей укажите при отправке документа в полеParticipantRolesструктуры DocumentAttachment. Подробнее о ролях — в разделе Роли участников.
Роли участников
Роль участника — машиночитаемая функция участника в бизнес-процессе. Роль записывается в формате namespace:name, например default:sender.
Для каждого типа и версии документа существует свой набор ролей — стандартный или специфический для этой версии. При отправке указанная роль участника обязательно должна входить в этот набор, иначе метод отправки вернет ошибку. Роль должна соответствовать реальной функции участника в документообороте: для отправителя документа укажите роль отправителя, для остальных участников — роли получателей.
Если для версии типа документа не настроен собственный набор ролей, для нее действует стандартный набор пространства имен default:
default:sender— отправитель документа.default:proxy— промежуточный получатель документа. При отправке многостороннего документа эту роль указать нельзя: такой документ нужно отправлять без промежуточного получателя.default:recipient— получатель документа.
Отдельно у некоторых версий есть роль default:viewer — наблюдатель. Она доступна для версий, в содержимом титула которых можно перечислить наблюдателей, — например, для заказа-заявки, поручения экспедитору, экспедиторской и складской расписки. Указывать эту роль при отправке документа нельзя: Диадок присваивает ее сам при отправке титула.
Получение списка ролей
В API Диадока не предусмотрен метод, с помощью которого можно было бы получить список ролей для типа и версии документа.
Чтобы узнать, какие роли допустимы для нужного типа и версии документа, получите любой документ этого типа и версии из ящика и посмотрите роли его участников. Методы API вернут роли, использованные в конкретном документе, в поле Role структуры DocumentParticipantV2. Например, у отправителя роль default:sender, у получателя — default:recipient:
- в методах GetDocument (V3), GetDocuments (V3) и GetDocumentsByMessageId — в поле
Participants[].Participant.Roleструктуры Document; - в методах GetDocflows (V5), SearchDocflows (V5), GetDocflowsByPacketId (V5) и GetDocflowEvents (V5) — в поле
DocumentInfo.Participants.Participants[].Roleструктуры DocumentWithDocflowV5, а также у автора титула и у участников каждого титула в структуре DocflowV5.
По участникам одного документа видны только те роли, которые в нем использовались. Это не значит, что остальные допустимые роли версии в этом документе нельзя использовать.
Если подходящего документа в ящике нет или в нем не нашлось нужной роли, уточните набор ролей для этой версии у оператора ЭДО.
Получение многотитульных документов
API Диадока предоставляет возможность получить информацию о:
- многотитульном документе через ленту событий;
- документе вместе с состоянием его документооборота через методы работы с документооборотом.
Базовая инструкция по получению документа — на странице Получение документов.
Методы GetDocument (V3), GetDocuments (V3) и GetDocumentsByMessageId возвращают структуру Document с полем Participants, но не содержат полного состояния многотитульного документооборота. Для работы с состоянием титулов используйте методы V5.
Получение сообщений и шаблонов
Чтобы получить информацию о многотитульных документах, используйте методы:
Из ответов методов получите структуры Message или Template. Участники документооборота документа хранятся в поле Document.Participants внутри сущностей сообщения — каждый элемент представлен структурой DocumentParticipantInfo.
Получение информации о документообороте
Чтобы получить многотитульный документ с состоянием его документооборота, используйте методы:
Из поля Documents в ответах методов список структур DocumentWithDocflowV5. Они хранят информацию о документах и полном состоянии их документооборота:
DocumentId— идентификатор документа;LastEvent— последнее событие по документу;DocumentInfo— информацию о документе в виде структуры DocumentInfoV5. Участники документооборота документа возвращаются в полеParticipantsв виде структур DocumentParticipantV2 — они заменяют отдельные поляSenderBoxId,ProxyBoxIdиRecipientBoxIdиз прежних версий структур; участник со значениемIsCurrentBox = trueпредставляет субъект текущего запроса;Docflow— состояние документооборота в виде новой структуры DocflowV5.
В структуре DocflowV5 в поле Titles хранится список документооборотов для каждого титула — как уже полученных, так и тех, которые требуется и возможно отправить. Вместо полей, привязанных к конкретным ролям (SenderTitle, ProxyResponse, RecipientResponse, RecipientReceipt и других из DocflowV4), каждый титул теперь описывается одинаково — структурой TitleDocflow:
TitleIndex— индекс слота титула, нумерация с нуля;Version— конкретная версия титула TitleVersionV5 — это важно для сценариев с несколькими версиями одного титула, например, при исправлениях ЭТрН;Author— автор титула в виде структуры DocumentParticipantV2;AuthorSigning— состояние подписи автора и результат операции в полеOperationResult;ParticipantDocflows— состояние каждого участника по отношению к титулу в виде структуры TitleParticipantDocflow с полями:TitleDelivery— доставка титула участнику, подтверждение оператора и роуминговое уведомление;Response— основной ответ участника на титул;Receipt— извещение о получении (ИоП) титула.
Помимо титулов, DocflowV5 содержит служебную информацию о документах:
AmendmentRequests— запросы на уточнение AmendmentRequestDocflowV5. Список формируется по всем титулам документа. Целевой титул определяется по полюTargetEntityId. У каждого получателя запроса вRecipientDocflowsсвои ИоП, доставка и подтверждение оператора;Revocation— аннулирование RevocationDocflowV5 с инициатором и списком ответов участниковRevocationResponse;OuterDocflows— внешние документообороты OuterDocflowV5, объединяющие описание процесса и его сущностиStatusEntities;TtGisFixation— документ для отмены сведений об отгрузке маркированных товаров.
В структуре DocumentParticipantV2 помимо BoxId, DepartmentId и Role доступны:
Type— транспортный тип участника (Sender,Recipient,Proxy): он описывает транспортную схему Диадока и не заменяет бизнес-роль участника из поляRole;Flags— признаки участника: роуминговый, трансграничный или иностранный;IsCurrentBox— признак того, что запрос к API выполнен от имени этого участника.