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

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

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

Примечание

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

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

Дополнить существующее сообщение с документом можно с помощью метода PostMessagePatch (V3) или PostMessagePatch (V4), передав в нем структуру MessagePatchToPost или MessagePatchToPostV2, заполненную следующими данными:

  • BoxId — идентификатор ящика, в котором находится исходное сообщение.

  • MessageId — идентификатор сообщения, к которому относится дополнение.

  • сущность дополнения — данные, которыми нужно дополнить существующее сообщение:

    • RecipientTitles — ответный титул на документ.

    • Signatures — подпись под документом.

    • RequestedSignatureRejections — отказ в подписи под документом.

    • Receipts — извещение о получении документа.

    • CorrectionRequests — запрос уточнения или корректировки.

    • ResolutionRequests — запрос согласования.

    • Resolutions — согласование документа.

    • RevocationRequests — предложение об аннулировании.

    • UniversalMessages — универсальное сообщение.

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

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

Также для некоторых типов документов нужно самостоятельно заполнить метаданные. Инструкция о получении списка доступных и обязательных метаданных приведена на странице Получение информации о типе документа.

Примечание

Обратите внимание, что API Диадока не создает файл подписи, его нужно сгенерировать самостоятельно.

Отправка ответного титула

Инструкция по созданию ответного титула приведена в разделе Генерация последующих титулов.

Чтобы отправить подписанный ответный титул, в теле запроса метода PostMessagePatch (V3) или PostMessagePatch (V4) передайте структуру MessagePatchToPost или 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

Пример тела запроса метода 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 — идентификатор сообщения, к которому относится дополнение;

  • UniversalMessages — вложенная структура для передачи XML-файлов универсальных сообщений:

    • ParentEntityId — идентификатор документа, к которому относится универсальное сообщение;

    • CodeGroup — группа кода универсального сообщения, которая определяет назначение универсального сообщения: извещение о получении, уведомление об уточнении или отказ в подписи.

    • UniversalMessageContent — содержимое XML-файла универсального сообщения, сконвертированное в Base64-строку;

    • Labels — метки (необязательно).

Примечание

На время переходного периода вместе с универсальным сообщением нужно передать соответствующий служебный документ текущего формата. Это значит, что помимо данных в поле UniversalMessages нужно передать данные в одном из полей — Receipts, CorrectionRequests или XmlSignatureRejections.

Пример тела запроса метода PostMessagePatch с универсальным сообщением:

{
    "BoxId": "{{boxId}}",
    "MessageId": "bbcedb0d-ce34-4e0d-b321-3f600c920935",
    "Receipts": [
        {
            "ParentEntityId":"30cf2c07-7297-4d48-bc6f-ca7a80e2cf95&",
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2l...LDQudC7Pg==",      // содержимое XML-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz"      // содержимое файла подписи в кодировке base-64
            }
        }
    ],
    "UniversalMessages": [
        {
            "ParentEntityId":"30cf2c07-7297-4d48-bc6f-ca7a80e2cf95&",
            "CodeGroup": "Receipt",
            "UniversalMessageContent": 
            {
            	"Content": "PD94bWwgdmVyc2l...LDQudC7Pg=="  // содержимое XML-файла в кодировке base-64
            }
        }
    ]
}

Метод вернет в ответе отправленное универсальное сообщение, представленное структурой MessagePatch.

Отправка извещения о получении

Инструкция по созданию извещения о получении приведена в разделе Генерация извещения о получении.

Чтобы отправить подписанное извещение о получении, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:

  • BoxId — идентификатор ящика, в котором находится исходное сообщение;

  • MessageId — идентификатор сообщения, к которому относится дополнение;

  • Receipts — вложенная структура для передачи XML-файлов извещений о получении:

    • ParentEntityId — идентификатор документа, к которому относится извещение;

    • SignedContent.Content — содержимое XML-файла извещения, сконвертированное в Base64-строку;

    • SignedContent.Signature — содержимое файла подписи извещения, сконвертированное в Base64-строку;

    • Labels — метки (необязательно).

Пример тела запроса метода PostMessagePatch с извещением о получении:

{
    "BoxId": "{{boxId}}",
    "MessageId": "bbcedb0d-ce34-4e0d-b321-3f600c920935",
    "Receipts": [
        {
            "ParentEntityId":"30cf2c07-7297-4d48-bc6f-ca7a80e2cf95&",
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2l...LDQudC7Pg==",      // содержимое XML-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz"      // содержимое файла подписи в кодировке base-64
            },
            "Comment": "Подписание извещения о получении счета-фактуры",
            "Label": "label"
        }
    ]
}

Метод вернет в ответе отправленное извещение о получении, представленное структурой MessagePatch.

Отправка уведомления об уточнении

Инструкция по созданию уведомления об уточнении приведена в разделе Генерация уведомления об уточнении.

Чтобы отправить подписанное уведомление об уточнении, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:

  • BoxId — идентификатор ящика, в котором находится исходное сообщение;

  • MessageId — идентификатор сообщения, к которому относится дополнение;

  • CorrectionRequests — вложенная структура для передачи XML-файлов уведомлений об уточнении:

    • ParentEntityId — идентификатор документа, к которому относится уведомление;

    • SignedContent.Content — содержимое XML-файла уведомления, сконвертированное в Base64-строку;

    • SignedContent.Signature — содержимое файла подписи уведомления, сконвертированное в Base64-строку;

    • Labels — метки (необязательно).

Пример тела запроса метода PostMessagePatch с уведомлением об уточнении:

{
    "BoxId": "{{boxId}}",
    "MessageId": "4366e677-38a1-4c42-ad60-caebfdbaed0f",
    "CorrectionRequests": [
        {
            "ParentEntityId": "e33d3903-6125-4542-9548-73000b94d852",
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2l...LDQudC7Pg==",      // содержимое XML-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz"      // содержимое файла подписи в кодировке base-64
            },
            "Labels": "label"
        }
    ]
}

Метод вернет в ответе отправленное уведомление об уточнении, представленное структурой MessagePatch.

Отправка предложения об аннулировании

Инструкция по созданию предложения об аннулировании приведена в разделе Генерация предложения об аннулировании.

Чтобы отправить подписанное предложение об аннулировании, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:

  • BoxId — идентификатор ящика, в котором находится исходное сообщение;

  • MessageId — идентификатор сообщения, к которому относится дополнение;

  • RevocationRequests — вложенная структура для передачи XML-файлов предложений об аннулировании:

    • ParentEntityId — идентификатор документа, к которому относится предложение;

    • SignedContent.Content — содержимое XML-файла предложения об аннулировании, сконвертированное в Base64-строку;

    • SignedContent.Signature — содержимое файла подписи предложения об аннулировании, сконвертированное в Base64-строку;

    • Labels — метки (необязательно).

Пример тела запроса метода PostMessagePatch с предложением об аннулировании:

{
    "BoxId": "{{boxId}}",
    "MessageId": "e9d6b396-934f-4ab5-801a-212c2bc0e1f8",
    "RevocationRequests": [
        {
            "ParentEntityId": "07946392-8e2c-4df5-9b13-97b8b329befe",
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2l...LDQudC7Pg==",      // содержимое XML-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz"      // содержимое файла подписи в кодировке base-64
            }
        }
    ]
}

Метод вернет в ответе отправленное предложение об аннулировании, представленное структурой MessagePatch.

Отправка отказа от подписи и отказа от предложения об аннулировании

Инструкция по созданию отказа в подписи приведена в разделе Генерация отказа от подписи и отказа от предложения об аннулировании.

Чтобы отправить отказ, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:

  • BoxId — идентификатор ящика, в котором находится исходное сообщение;

  • MessageId — идентификатор сообщения, к которому относится дополнение;

  • XmlSignatureRejections — вложенная структура для передачи XML-файлов отказов:

    • ParentEntityId — идентификатор предложения об аннулировании или документа, к которому относится отказ;

    • SignedContent.Content — содержимое XML-файла отказа, сконвертированное в Base64-строку;

    • SignedContent.Signature — содержимое файла подписи отказа, сконвертированное в Base64-строку;

    • Labels — метки (необязательно).

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

{
    "BoxId": "{{boxId}}",
    "MessageId": "3815fb36-aabe-4588-8fe7-a1a33154278c",
    "XmlSignatureRejections": [
        {
            "ParentEntityId": "33ba16c68-cc54-4b25-b81c-0e79134e219d",
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2l...LDQudC7Pg==",      // содержимое XML-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz"      // содержимое файла подписи в кодировке base-64
            }
        }
    ]
}

Метод вернет в ответе отправленный отказ, представленный структурой MessagePatch.

Отправка документа для отмены сведений об отгрузке маркированных товаров

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

Инструкция по созданию документа для отмены сведений об отгрузке маркированных товаров приведена в разделе Генерация документа для отмены сведений об отгрузке маркированных товаров.

Чтобы отправить документ, в теле запроса метода PostMessagePatch (V4) передайте структуру MessagePatchToPostV2, заполненную следующими данными:

  • BoxId — идентификатор ящика, в котором находится исходное сообщение;

  • MessageId — идентификатор сообщения, к которому относится дополнение;

  • TtGisFixationCancellationRequests — вложенная структура для передачи документов для отмены сведений об отгрузке маркированных товаров:

    • DocumentId — идентификатор документа, содержащего маркированные товары, сведения об отгрузке которых необходимо отменить;

    • SignedContent.Content — содержимое JSON-файла документа для отмены сведений об отгрузке, сконвертированное в Base64-строку;

    • SignedContent.Signature — содержимое файла подписи документа для отмены сведений об отгрузке, сконвертированное в Base64-строку.

Пример тела запроса метода PostMessagePatch с документом для отмены сведений об отгрузке маркированных товаров:

{
    "BoxId": "{{boxId}}",
    "MessageId": "d94982e8-7eb9-4993-8c52-41c14e3fc3a8",
    "TtGisFixationCancellationRequests": [
        {
            "DocumentId": "05ea290d-9aa1-4291-a87b-d30be9ccf5b7",
            "SignedContent":
            {
                "Content": "eyJpbm4iOiI2MT...F8wMCJ9",      // содержимое JSON-файла в кодировке base-64
                "Signature": "MIIMtAYJKoZIhvc...KW1oPlA=="      // содержимое файла подписи в кодировке base-64
            }
        }
    ]
}

Метод вернет в ответе отправленный документ, представленный структурой MessagePatch.