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

Многосторонние документы

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

На текущий момент в API Диадока поддерживается единственный многосторонний документ — многосторонний договор (multilateral_contract_01_01).

к сведению

Функциональность недоступна по умолчанию. Чтобы получить возможность отправлять многосторонние документы, обратитесь к менеджеру или в техническую поддержку.

Участник документа — это ящик организации или физического лица либо подразделение. У участника есть определенная роль в бизнес-процессе.

Сведения об участниках Диадок возвращает в поле Participants структуры Document, а состояние документооборота по каждому титулу — в структуре DocflowV5.

к сведению

Работа с многотитульными документами описана на странице Многотитульные документы.

Отправка многостороннего документа

Отправить многосторонний документ через API Диадока можно методом PostMessage (V3), передав в запросе данные участников документооборота. Полная инструкция об отправке документа приведена в разделе Отправка документа.

Чтобы отправить многосторонний документ, вызовите метод PostMessage (V3) и заполните в структуре MessageToPost:

  • FromBoxId — ящик отправителя;
  • FromDepartmentId — подразделение отправителя, если документ отправляет подразделение;
  • DocumentAttachments — документы сообщения, представленные структурой DocumentAttachment:
    • укажите данные о типе документа, полученные с помощью метода GetDocumentTypes (V3):
      • TypeNamedId = Contract;
      • Function = default;
      • Version = multilateral_contract_01_01.
    • в каждом документе заполните поле ParticipantRoles — список участников документа и их ролей. Элемент списка ParticipantRoles представлен структурой DocumentParticipantRoleInfo:
      • BoxId — ящик участника;
      • DepartmentId — подразделение участника. Если поле не заполнено, участник действует от головного подразделения;
      • Role — роль участника. Подробнее про роли — в разделе Роли участников. Для многосторонних документов доступны только стандартные роли:
        • default:sender — отправитель документа;
        • default:recipient — получатель документа.

Поля ToBoxId, ToDepartmentId, ProxyBoxId и ProxyDepartmentId не заполняйте: участников сообщения Диадок определяет по спискам участников документов.

В одном сообщении можно отправить документы с разными наборами участников.

Документ и подписи к нему Диадок доставляет в ящики всех участников документооборота, поэтому каждый участник видит полный список участников документа и ответы остальных участников. Каждому участнику документооборота будут доставлены документы и подписи всех участников.

При заполнении участников руководствуйтесь следующими правилами:

  • укажите роль каждого участника;
  • в списке участников документа укажите отправителя и хотя бы одного получателя;
  • если вид документооборота документа не поддерживает нескольких получателей, укажите в документе только одного получателя помимо отправителя;
  • каждый ящик можно указать в документе только один раз;
  • роли default:proxy и default:viewer при отправке документа указывать нельзя;
  • в сообщении может быть не больше 30 участников.

Пример тела запроса метода PostMessage:

{
"FromBoxId": "{{boxId_sender}}",
"DocumentAttachments": [
{
"SignedContent": {
"Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0...NC50Ls+", // содержимое XML-файла в кодировке base-64
"Signature": "MIIN5QYJKoZIhvcNAQcCoIIN1jCCDdIA...kA9MJfsplqgW" // содержимое файла подписи в кодировке base-64
},
"NeedRecipientSignature": true,
"TypeNamedId": "Contract",
"Function": "default",
"Version": "multilateral_contract_01_01",
"ParticipantRoles": [
{
"BoxId": "{{boxId_sender}}",
"Role": "default:sender"
},
{
"BoxId": "{{boxId_recipient1}}",
"Role": "default:recipient"
},
{
"BoxId": "{{boxId_recipient2}}",
"DepartmentId": "{{departmentId_recipient2}}",
"Role": "default:recipient"
}
]
}
]
}

Ограничения на отправку:

  • многосторонние документы нельзя отправить во внутреннем сообщении или в сообщении с промежуточным получателем;
  • получателями многостороннего документа не могут быть роуминговые и трансграничные организации: метод вернет ошибку;
  • черновики и шаблоны пока не поддерживают многосторонние документы.

Отправка из подразделения

Если нужно отправить документ от подразделения, заполните FromDepartmentId в структуре MessageToPost и укажите тот же идентификатор в поле DepartmentId участника с ролью default:sender в списке ParticipantRoles:

Пример тела запроса метода PostMessage для отправки из подразделения:

{
"FromBoxId": "{{boxId_sender}}",
"FromDepartmentId": "{{departmentId_sender}}",
"DocumentAttachments": [
{
"SignedContent": {
"Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0...NC50Ls+", // содержимое XML-файла в кодировке base-64
"Signature": "MIIN5QYJKoZIhvcNAQcCoIIN1jCCDdIA...kA9MJfsplqgW" // содержимое файла подписи в кодировке base-64
},
"NeedRecipientSignature": true,
"TypeNamedId": "LogisticsWaybill",
"Function": "reception",
"Version": "kl_trn_mt_05_02_01",
"ParticipantRoles": [
{
"BoxId": "{{boxId_sender}}",
"DepartmentId": "{{departmentId_sender}}",
"Role": "default:sender"
},
{
"BoxId": "{{boxId_recipient1}}",
"Role": "default:recipient"
}
]
}
]
}

Значения FromDepartmentId и DepartmentId участника-отправителя должны совпадать — по ним Диадок сопоставляет участника документа с отправителем сообщения. Если значения не совпадают, метод вернет ошибку 400 (Bad Request).

Если FromDepartmentId не заполнен, отправитель действует от головного подразделения. В этом случае оставьте DepartmentId у участника-отправителя пустым или укажите 00000000-0000-0000-0000-000000000000.

Получение участников документа

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

Методы возвращают участников документа в поле Participants структуры Document.

Участников документа также возвращают методы, которые получают сообщения и события:

Каждый элемент поля Participants представлен структурой DocumentParticipantInfo:

  • Participant — участник документа в виде структуры DocumentParticipantV2 с полями BoxId, DepartmentId, Role, Type, Flags и IsCurrentBox;
  • RecipientResponseStatus — статус ответного действия получателя из перечисления RecipientResponseStatus.

Пример фрагмента тела ответа метода GetDocuments:

{
"Participants": [
{
"Participant": {
"BoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"Role": "default:sender",
"Flags": {
"IsRoaming": false,
"IsCrossborder": false,
"IsForeign": false
},
"Type": "Sender",
"IsCurrentBox": true
},
"RecipientResponseStatus": "RecipientResponseStatusUnknown"
},
{
"Participant": {
"BoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"Role": "default:recipient",
"Flags": {
"IsRoaming": false,
"IsCrossborder": false,
"IsForeign": false
},
"Type": "Recipient",
"IsCurrentBox": false
},
"RecipientResponseStatus": "WaitingForRecipientSignature"
}
]
}

В этом примере у отправителя статус RecipientResponseStatusUnknown: поле RecipientResponseStatus Диадок заполняет только для получателя и промежуточного получателя. Подпись отправителя смотрите в поле SenderSignatureStatus структуры Document или в поле AuthorSigning структуры TitleDocflow. Статус получателя WaitingForRecipientSignature означает, что он еще не ответил на документ.

Если в поле IsCurrentBox указано значение true, то это значит, что участник документооборота представляет ящик, от имени которого отправлен запрос.

Методы GetDocflows (V5), SearchDocflows (V5), GetDocflowsByPacketId (V5) и GetDocflowEvents (V5) возвращают состояние документооборота по титулам документа. Подробнее про работу с состоянием каждого участника по титулу — на странице Многотитульные документы.

Статус многостороннего документа

Статус документа указан в поле DocflowStatus структуры Document и в структуре DocflowV5. Ответы участников на титул указаны в поле Response структуры TitleParticipantDocflow.

Пока документ не подписан всеми участниками, документооборот не считается завершенным: для уже подписавших участников статус будет иметь значение TitleParticipantResponseStatusSigned, а для остальных участников — TitleParticipantResponseStatusWaiting.

Документооборот может быть завершен в следующих случаях:

  • документ подписали все участники;
  • кто-то из участников отказался от подписи.

Аннулирование для многосторонних документов пока не поддерживается.

Ответные действия участников

Каждый участник документооборота работает с документом в своем ящике и действует от своего имени. Это значит, что автор ответного титула или подписи зависит от ящика, от имени которого вызван метод, и специально указывать участника в дополнении к сообщению не нужно.

Ответить по документу можно с помощью метода PostMessagePatch (V4):

Отправить извещение о получении для многостороннего документа нельзя.

Методы работы с документооборотом возвращают состояние участников по каждому титулу в поле ParticipantDocflows структуры TitleDocflow. Каждый элемент списка представлен структурой TitleParticipantDocflow и содержит участника, состояние доставки ему титула, его ответ на титул и извещение о получении.


См. также

Инструкции:

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

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

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