Многотитульные документы

Раньше API Диадока описывал документооборот через фиксированные роли — отправитель, промежуточный получатель и конечный получатель. Такая модель подходила для работы с одно-, двух- и трехтитульными документами. Но существуют многотитульные документы, которые могут содержать любое количество титулов в зависимости от их бизнес-сценария. Примером многотитульного документа является электронная транспортная накладная или поручение экспедитору. Чтобы работать с такими документами, в API реализованы отдельные версии методов: на этой странице инструкция по их использованию.

Определение количества титулов и участников

Перед отправкой или получением многотитульного документа определите количество его титулов и участников — они зависят от типа документа и вида документооборота:

  1. Получите тип документа и список его титулов методом GetDocumentTypes (V3). Инструкция о получении данных из метода GetDocumentTypes приведена на странице Получение информации о типе документа. Для каждого титула зафиксируйте значение TitleIndex — оно понадобится при отправке и получении титула.

  2. Получите свойства вида документооборота методом GetWorkflowsSettings (V3). Свойства документооборота DocumentWorkflowSettingsV3 содержат ожидаемое поведение по титулам для каждого участника документооборота — они хранятся в структуре ParticipantActionSettingV3 с соответствующим номером титула TitleIndex.

Получение многотитульных документов

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 с полями:

Помимо титулов, DocflowV5 содержит служебную информацию о документах:

В структуре DocumentParticipantV2 помимо BoxId, DepartmentId и Role доступны:

  • Type — транспортный тип участника (Sender, Recipient, Proxy): он описывает транспортную схему Диадока и не заменяет бизнес-роль участника из поля Role;

  • Flags — признаки участника: роуминговый, трансграничный или иностранный;

  • IsCurrentBox — признак того, что запрос к API выполнен от имени этого участника.