Дополнение сообщения
Как правило, сообщение требует от получателя ответного действия для продолжения или завершения документооборота. Таким действием может быть отправка ответного документа или извещения о получении. Отправитель сообщения тоже может внести изменения в документооборот: например, предложить аннулирование или приложить корректировку исходного документа.
Дополнить сообщение — значит выполнить действие, связанное с документом в этом сообщении, добавив в цепочку документооборота еще один документ. С помощью дополнения можно выполнить следующие действия:
- отправить ответный титул,
- отправить ответную подпись,
- подтвердить получение документа,
- запросить уточнение или корректировку документа,
- запросить согласование документа,
- согласовать документ,
- аннулировать документ,
- отказать в предложении об аннулировании документа,
- отказать в подписи документа,
- отменить сведения об отгрузке маркированных товаров,
- изменить теги документа.
Разные форматы документов предусматривают разный набор возможных дополнений: какие-то документы требуют ответного титула, а какие-то — подпись или извещение о получении. Особенности поведения документа можно узнать по его виду документооборота.
В дополнениях к сообщению хранятся все служебные документы и подтверждения оператора. Одно сообщение может содержать неограниченное количество дополнений к исходному документу. Подробнее механизм работы с сообщением описан на странице Обмен документами в Диадоке.
Дополнить существующее сообщение с документом можно с помощью метода PostMessagePatch (V4), передав в нем структуру MessagePatchToPostV2, заполненную следующими данными:
BoxId— идентификатор ящика, в котором находится исходное сообщение.MessageId— идентификатор сообщения, к которому относится дополнение.- сущность дополнения — данные, которыми нужно дополнить существующее сообщение:
RecipientTitles— ответный титул на документ.Signatures— подпись под документом.XmlSignatureRejections— отказ в подписи под документом или от предложения об аннулировании.CustomDataPatches— операции с тегами документа.Receipts— извещение о получении документа.CorrectionRequests— запрос уточнения или корректировки.ResolutionRequests— запрос согласования.Resolutions— согласование документа.RevocationRequests— предложение об аннулировании.UniversalMessages— универсальное сообщение.TtGisFixationCancellationRequests— документ для отмены сведений об отгрузке маркированных товаров.
Все возможные варианты дополнения сообщения перечислены в структуре MessagePatchToPostV2.
Также для некоторых типов документов нужно самостоятельно заполнить метаданные. Инструкция о получении списка доступных и обязательных метаданных приведена на странице Получение информации о типе документа.
Обратите внимание, что API Диадока не создает файл подписи, его нужно сгенерировать самостоятельно.
Отправка ответного титула
Инструкция по созданию ответного титула приведена в разделе Генерация последующих титулов.
Чтобы отправить подписанный ответный титул, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:
BoxId— идентификатор ящика, в котором находится исходное сообщение.MessageId— идентификатор сообщения, к которому относится дополнение.RecipientTitles— вложенная структура для передачи XML-файла ответного титула на документ:ParentEntityId— идентификатор первого титула документа (титула отправителя).SignedContent.Content— XML-файл документа.SignedContent.Signature— файл подписи.NeedReceipt— запрос извещения о получении документа отправителем; если принимает значениеtrue, то отправитель первого титула документа будет обязан сформировать и отправить извещение о получении после получения титула получателя. Возможность запросить извещение о получении зависит от вида документооборота.
Пример HTTP-запроса метода PostMessagePatch с ответным титулом:
POST /V3/PostMessagePatch HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Content-Type: application/json; charset=utf-8
Accept: application/json
Пример тела запроса метода PostMessagePatch с ответным титулом:
{
"BoxId": "{{boxId}}",
"MessageId": "bbcedb0d-ce34-4e0d-b321-3f600c920935",
"RecipientTitles": [
{
"ParentEntityId":"30cf2c07-7297-4d48-bc6f-ca7a80e2cf95&",
"SignedContent":
{
"Content": "PD94bWwgdmVyc2l...LDQudC7Pg==", // содержимое XML-файла в кодировке base-64
"Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz" // содержимое файла подписи в кодировке base-64
}
}
]
}
Метод вернет в ответе отправленный титул, представленный структурой MessagePatch.
В результате работы метода сообщение будет обновлено в ящиках всех участников документооборота. В ящике получателя обновление может произойти с задержкой.
Отправка подписи под документом
Требования к файлу электронной подписи приведены на странице Подпись.
Подпись отправляют по документам, ответным действием по которым является подпись, а не ответный титул: например, по неформализованным документам с запросом подписи получателя. Подпись формируется под исходным содержимым документа, само содержимое при этом не меняется.
Чтобы отправить подпись, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:
BoxId— идентификатор ящика, в котором находится исходное сообщение;MessageId— идентификатор сообщения, к которому относится дополнение;Signatures— вложенная структура для передачи подписей под документами:ParentEntityId— идентификатор сущности документа, под которым ставится подпись;Signature— содержимое файла подписи, сконвертированное в Base64-строку;SignWithTestSignature— признак того, что документ должен быть подписан тестовой подписью (необязательно);Labels— метки (необязательно).
Пример тела запроса метода PostMessagePatch с подписью под документом:
{
"BoxId": "{{boxId}}",
"MessageId": "3815fb36-aabe-4588-8fe7-a1a33154278c",
"Signatures": [
{
"ParentEntityId": "33ba16c68-cc54-4b25-b81c-0e79134e219d",
"Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz" // содержимое файла подписи в кодировке base-64
}
]
}
Метод вернет в ответе отправленную подпись, представленную структурой MessagePatch.
Отправка запроса на согласование документа
Запрос на согласование отправляют в том случае, когда нужно запросить согласование документа у других сотрудников. В запросе укажите, кому он адресован и какое действие нужно выполнить.
Чтобы отправить запрос, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:
BoxId— идентификатор ящика, в котором находится исходное сообщение;MessageId— идентификатор сообщения, к которому относится дополнение;ResolutionRequests— вложенная структура для передачи запросов на согласование или подпись. Каждый элемент списка представлен структурой ResolutionRequestAttachment:InitialDocumentId— идентификатор документа, для которого формируется запрос;Type— тип запроса, принимает значения из перечисления ResolutionRequestType:ApprovementRequest— запрос на согласование,SignatureRequest— запрос на подпись,ApprovementSignatureRequest— запрос на согласующую подпись;TargetUserId— идентификатор сотрудника, которому направляется запрос. Заполните поле, если запрос адресован сотруднику;TargetDepartmentId— идентификатор подразделения, куда направляется запрос. Заполните поле, если запрос адресован подразделению;Comment— комментарий к запросу, длина не более 500 символов;Labels— метки (необязательно).
В структуре заполните только одно поле — TargetUserId или TargetDepartmentId.
Пример тела запроса метода PostMessagePatch с запросом на согласование:
{
"BoxId": "{{boxId}}",
"MessageId": "094faf38-ea15-445c-8d25-ae809fac84be",
"ResolutionRequests": [
{
"InitialDocumentId": "d882c756-1d72-4103-aedd-f3009aa76509", // идентификатор документа, для которого формируется запрос
"Type": "ApprovementRequest", // тип запроса: согласование или подпись
"TargetUserId": "24c669be-6dbc-48c4-8249-33f96232e2fa", // идентификатор сотрудника, которому направляется запрос
"Comment": "Согласуйте, пожалуйста, счет на оплату",
"Labels": ["resolution"]
}
]
}
Метод вернет в ответе отправленный запрос, представленный структурой MessagePatch.
Отправка согласования документа
В служебном документе по согласованию сотрудник сообщает свое решение по документу: его можно согласовать или отказать в согласовании. В комментарии к согласованию можно оставить пояснение для сотрудника, который отправил запрос.
Чтобы отправить согласование, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:
BoxId— идентификатор ящика, в котором находится исходное сообщение;MessageId— идентификатор сообщения, к которому относится дополнение;Resolutions— вложенная структура для передачи согласований. Каждый элемент списка представлен структурой ResolutionAttachment:InitialDocumentId— идентификатор согласуемого документа;ResolutionType— тип действия, принимает значения из перечисления ResolutionType:Approve— согласовать документ,Disapprove— отказать в согласовании,UndefinedResolutionType— отменить последнее согласование текущего пользователя;Comment— комментарий к согласованию или отказу в согласовании, длина не более 5000 символов;Labels— метки (необязательно).
Пример тела запроса метода PostMessagePatch с согласованием документа:
{
"BoxId": "{{boxId}}",
"MessageId": "27ff22ad-64a6-4e01-9017-914744a5d264",
"Resolutions": [
{
"InitialDocumentId": "b58abd6b-20aa-4c3a-a794-a3dafc69169a", // идентификатор согласуемого документа
"ResolutionType": "Approve", // согласовать документ
"Comment": "Согласовано",
"Labels": ["resolution"]
}
]
}
Метод вернет в ответе отправленное согласование, представленное структурой MessagePatch.
Отправка служебных документов
Служебные документы отправляют так же, как и остальные дополнения, — методом PostMessagePatch (V4). Инструкция по отправке каждого служебного документа приведена в разделе отправки на странице работы с этим документом:
- Отправка извещения о получении,
- Отправка уведомления об уточнении,
- Отправка предложения об аннулировании,
- Отправка отказа в подписи и отказа от предложения об аннулировании,
- Отправка универсального сообщения,
- Отправка документа для отмены сведений об отгрузке маркированных товаров.
Изменение тегов документа
С помощью дополнения к сообщению можно добавить, изменить или удалить теги документа. Изменять теги может любая сторона документооборота.
Чтобы изменить теги, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:
BoxId— идентификатор ящика, в котором находится исходное сообщение;MessageId— идентификатор сообщения, к которому относится дополнение;CustomDataPatches— вложенная структура для передачи операций с тегами. Каждый элемент списка представлен структурой CustomDataPatch:ParentEntityId— идентификатор документа, теги которого нужно изменить;Operation— тип операции, принимает значения из перечисленияCustomDataPatchOperation:Set— добавить новый тег или изменить существующий,Remove— удалить тег;Key— название тега;Value— значение тега. В операцииRemoveзначение игнорируется.
За одно дополнение можно передать не более 15 операций с тегами.
Пример тела запроса метода PostMessagePatch с изменением тегов документа:
{
"BoxId": "{{boxId}}",
"MessageId": "1eef4942-6f95-4db0-a9f6-56efe992e2ec",
"CustomDataPatches": [
{
"ParentEntityId": "857c9b5b-4231-4e91-8ae7-c81836258372", // идентификатор документа, теги которого нужно изменить
"Operation": "Set", // добавить тег или изменить существующий
"Key": "Номер_договора",
"Value": "DOC2356"
},
{
"ParentEntityId": "857c9b5b-4231-4e91-8ae7-c81836258372",
"Operation": "Remove", // удалить тег
"Key": "Subdivision"
}
]
}
Метод вернет в ответе отправленное дополнение, представленное структурой MessagePatch.