Многосторонние документы
Раньше 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— получатель документа.
- укажите данные о типе документа, полученные с помощью метода GetDocumentTypes (V3):
Поля 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 и содержит участника, состояние доставки ему титула, его ответ на титул и извещение о получении.
См. также
Инструкции: