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

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

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

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

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

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

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

API Диадока предоставляет возможность получить информацию о:

  • многотитульном документе через ленту событий;

  • документе вместе с состоянием его документооборота через методы работы с документооборотом.

Базовая инструкция по отправке документа — на странице Отправка сообщения с документом.

Примечание

Методы GetDocument (V3), GetDocuments (V3) и GetDocumentsByMessageId не поддерживают работу с многотитульными документами: участники документооборота в них возвращаются в полях SenderBoxId, ProxyBoxId и RecipientBoxId.

Получение сообщений и шаблонов

Чтобы получить информацию о многотитульных документах, используйте методы:

Получение информации о документообороте

Чтобы получить многотитульный документ с состоянием его документооборота, используйте методы:

Из поля Documents в ответах методов список структур DocumentWithDocflowV5. Они хранят информацию о документах и полном состоянии их документооборота:

  • DocumentId — идентификатор документа;

  • LastEvent — последнее событие по документу;

  • DocumentInfo — информацию о документе в виде структуры DocumentInfoV5. Участники документооборота документа возвращаются в поле Participants в виде структур DocumentParticipantV2 — они заменяют отдельные поля SenderBoxId, ProxyBoxId и RecipientBoxId из прежних версий структур; участник со значением RepresentsCurrentPrincipal = 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. У каждого получателя запроса в RecipientDocflows свои ИоП, доставка и подтверждение оператора;

  • Revocation — аннулирование RevocationDocflowV5 с инициатором и списком ответов участников RevocationResponse;

  • OuterDocflows — внешние документообороты OuterDocflowV5, объединяющие описание процесса и его сущности StatusEntities;

  • TtGisFixation — документ для отмены сведений об отгрузке маркированных товаров.

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

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

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

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