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

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

XSD-схемы служебных документов приведены в разделе XSD-схемы.

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

Отправить документ с подписью в исходящем сообщении можно с помощью метода PostMessage (V3).

В теле запроса метода нужно передать структуру MessageToPost. Структура должна содержать идентификаторы ящиков участников документооборота и набор отправляемых документов:

• FromBoxId — идентификатор ящика отправителя. Можно указать только тот ящик, к которому у пользователя есть доступ с текущим авторизационным токеном.

• ToBoxId — идентификатор ящика получателя.

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

  • SignedContent.Content — XML-файл документа.

  • SignedContent.Signature — файл подписи.

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

  • TypeNamedId — тип документа.

  • Function — функция документа.

  • Version — версия документа.

  • SignedContent.PowerOfAttorneyToPost — машиночитаемая доверенность (МЧД). Указать ее можно следующими способами:

    • указать регистрационный номер МЧД в формате GUID, ИНН доверителя и ИНН представителя во вложенной структуре PowerOfAttorneyToPost.PowerOfAttorneyFullId в полях RegistrationNumber, IssuerInn и RepresentativeInn соответственно,

    • использовать признак PowerOfAttorneyToPost.UseDefault = true, если у сотрудника установлена МЧД по умолчанию;

    • передать файл доверенности и подпись к ней во вложенной структуре PowerOfAttorneyToPost.Contents; файл передается в поле Content, подпись — в поле Signature.

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

Примечание

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

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

{
    "FromBoxId": "{{boxId_sender}}",
    "ToBoxId": "{{boxId_recipient}}",
    "DocumentAttachments": [
        {
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0...NC50Ls+",        // содержимое XML-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvcNAQcCoIIN1jCCDdIA...kA9MJfsplqgW",        // содержимое файла подписи в кодировке base-64
                {
                    "PowerOfAttorney":
                    "FullId":
                    {
                        "RegistrationNumber": "{{registrationNumber}}",
                        "IssuerInn": "{{issuerInn}}"
                    },
                },
            },
            "TypeNamedId": "{{documentTypeName}}",
            "Function": "{{function}}",
            "Version": "{{version}}"
        }
    ]
}

В ответе метод вернет отправленное сообщение в виде структуры Message.

После вызова метода PostMessage в ящике отправителя формируется:

• цепочка документооборота и информация о связанных с ней документах,

• событие о появлении сообщения.

В ящике получателя эта информация появится с некоторой задержкой: это связано с асинхронной передачей информации из ящика отправителя в ящик получателя. То есть успешный вызов метода PostMessage (V3) гарантирует лишь появление исходящего сообщения в ящике отправителя.

Не отправляйте формализованные документы размером более 3 Мб. Это может увеличить время обработки документа и завершиться ошибкой.

Для отправляемых документов размером более 500 Кб рекомендуем использовать полку документов.

Отложенная отправка

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

• документы перед отправкой нужно согласовать с другими сотрудниками;

• документ перед отправкой нужно дополнить данными, как в случае с маркированными товарами;

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

Для отложенной отправки в структуре MessageToPost установите признак DelaySend. При вызове метода PostMessage (V3) документ с этим признаком будет сохранен в разделе исходящих документов. Такой документ называется исходящим неотправленным документом.

Если вы планируете перед отправкой отредактировать документ, используйте настройки редактирования. Для этого в поле MessageToPost.DocumentAttachment.EditingSettingId укажите значение идентификатора настройки редактирования, полученного у вашего менеджера.

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

Если никаких действий с документом больше не требуется, его можно отправить с подписью в исходящем сообщении с помощью метода PostMessagePatch (V4). Подписание неотправленного документа основной подписью равносильно его отправке.

Исходящий неотправленный документ можно найти с помощью метода GetDocuments (V3). Для этого в запросе используйте фильтр DocumentStatus = WaitingForSenderSignature.

У исходящего неотправленного документа есть ограничения:

• под таким документом не может быть подписи или запроса на подпись по доверенности,

• нельзя изменить содержимое документа и реквизиты получателя, за исключением документов с настройками редактирования.

Отличия исходящего неотправленного документа от других сущностей приведено в таблице.

Создание черновика

Метод PostMessage (V3) можно использовать для создания черновиков — сообщений, содержащих документы без подписей к ним.

Чтобы создать черновик, укажите признак IsDraft в структуре MessageToPost при создании сообщения. Такое сообщение будет загружено на сервер, но задание на отправку сообщения получателю формироваться не будет.

Для формирования подписей к документам и отправки сообщения на основе черновика используйте метод SendDraft.

Шаблон, черновик или неотправленный документ

Используйте шаблон, черновик или исходящий неотправленный документ в подходящих для этого сценариях. Ниже в таблице приведены различия этих сущностей.

Различия черновика, шаблона и исходящего неотправленного документа

	Шаблон	Черновик	Исходящий неотправленный документ
Свойства	Сообщение без подписей. На его основе можно создать один или несколько документов — в зависимости от настроек. С шаблоном можно работать в своем ящике или отправить контрагенту.	«Заготовка» документа, т.е. сущность, на основе которой можно создать один документ.	Уже готовый к отправке документ, сохраненный в разделе «Исходящие». Имеет статус «Требуется подписать и отправить».
Где хранится	в ящике отправителя или получателя	в ящике отправителя	в ящике отправителя
Можно ли редактировать перед отправкой	да, если указаны настройки редактирования	нет	да, если указаны настройки редактирования
Что будет после отправки	в зависимости от настроек: если шаблон одноразовый, то он будет удален после создания документа; если шаблон многоразовый, то он продолжит существовать после создания документа.	черновик будет удален	будет отправлен контрагенту