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

Дополнение сообщения

Как правило, сообщение требует от получателя ответного действия для продолжения или завершения документооборота. Таким действием может быть отправка ответного документа или извещения о получении. Отправитель сообщения тоже может внести изменения в документооборот: например, предложить аннулирование или приложить корректировку исходного документа.

Дополнить сообщение — значит выполнить действие, связанное с документом в этом сообщении, добавив в цепочку документооборота еще один документ. С помощью дополнения можно выполнить следующие действия:

к сведению

Разные форматы документов предусматривают разный набор возможных дополнений: какие-то документы требуют ответного титула, а какие-то — подпись или извещение о получении. Особенности поведения документа можно узнать по его виду документооборота.

В дополнениях к сообщению хранятся все служебные документы и подтверждения оператора. Одно сообщение может содержать неограниченное количество дополнений к исходному документу. Подробнее механизм работы с сообщением описан на странице Обмен документами в Диадоке.

Дополнить существующее сообщение с документом можно с помощью метода 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.

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

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

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