Перейти к основному содержимому

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

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

к сведению

Отправка документа нескольким участникам и их роли описаны на странице Многосторонние документы.

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

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

  1. Получите тип документа и список его титулов методом GetDocumentTypes (V3). Инструкция о получении данных из метода GetDocumentTypes приведена на странице Получение информации о типе документа. Для каждого титула зафиксируйте значение TitleIndex — оно понадобится при отправке и получении титула.
  2. Получите свойства вида документооборота методом GetWorkflowsSettings (V3). Свойства документооборота DocumentWorkflowSettingsV3 содержат ожидаемое поведение по титулам для каждого участника документооборота — они хранятся в структуре ParticipantActionSettingV3 с соответствующим номером титула TitleIndex.
  3. Определите участников документа и их роли. Роль указывайте в формате 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:

По участникам одного документа видны только те роли, которые в нем использовались. Это не значит, что остальные допустимые роли версии в этом документе нельзя использовать.

Если подходящего документа в ящике нет или в нем не нашлось нужной роли, уточните набор ролей для этой версии у оператора ЭДО.

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

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 выполнен от имени этого участника.

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года