Отправка сообщения с документом
Обмен документами между контрагентами происходит внутри сообщения. Подробнее механизм работы с сообщением описан на странице Обмен документами в Диадоке.
XSD-схемы служебных документов приведены в разделе XSD-схемы.
Отправка документа
Перед отправкой документа можно предварительно проверить правильность указанных параметров сообщения, чтобы убедиться в отсутствии ошибок. Для этого можно воспользоваться методом CanPostMessage. В него нужно передать параметры отправляемого сообщения, но без документов и подписей — в виде структуры MessageToPostPrototype. Метод проверит, верно ли указаны параметры и не приведет ли вызов метода отправки к каким-либо ошибкам. Если в результате проверки будут обнаружены ошибки или предупреждения, метод вернет их в структуре MessageValidationResult.
Отправить документ с подписью в исходящем сообщении можно с помощью метода PostMessage (V3).
В теле запроса метода нужно передать структуру MessageToPost. Структура должна содержать идентификаторы ящиков участников документооборота и набор отправляемых документов:
FromBoxId— идентификатор ящика отправителя. Можно указать только тот ящик, к которому у пользователя есть доступ с текущим авторизационным токеном.ToBoxId— идентификатор ящика получателя — для одно- или двухтитульных документов.DocumentAttachment— вложенная структура DocumentAttachment для передачи XML-файла документа:SignedContent.Content— XML-файл документа.SignedContent.Signature— файл подписи.NeedRecipientSignature— признак того, что под документом требуется подпись получателя.TypeNamedId— тип документа.Function— функция документа.Version— версия документа.ParticipantRoles— список участников документооборота. Поле заменяетToBoxIdиProxyBoxIdструктурыMessageToPost: заполните его, чтобы отправить многосторонний или многотитульный документ с несколькими участниками.SignedContent.PowerOfAttorneyToPost— машиночитаемая доверенность (МЧД). Указать ее можно следующими способами:- указать регистрационный номер МЧД в формате GUID, ИНН доверителя и ИНН представителя во вложенной структуре
PowerOfAttorneyToPost.PowerOfAttorneyFullIdв поляхRegistrationNumber,IssuerInnиRepresentativeInnсоответственно, - использовать признак
PowerOfAttorneyToPost.UseDefault = true, если у сотрудника установлена МЧД по умолчанию; - передать файл доверенности и подпись к ней во вложенной структуре
PowerOfAttorneyToPost.Contents; файл передается в полеContent, подпись — в полеSignature.
- указать регистрационный номер МЧД в формате GUID, ИНН доверителя и ИНН представителя во вложенной структуре
Также для некоторых типов документов нужно самостоятельно заполнить метаданные. Инструкция о получении списка доступных и обязательных метаданных приведена на странице Получение информации о типе документа.
Обратите внимание, что 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}}",
"RepresentativeInn": "{{representativeInn}}"
}
}
},
"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.
У исходящего неотправленного документа есть ограничения:
- под таким документом не может быть подписи или запроса на подпись по доверенности,
- нельзя изменить содержимое документа и реквизиты получателя, за исключением документов с настройками редактирования.
Отличия исходящего неотправленного документа от других сущностей приведено в таблице.
Шаблон, черновик или неотправленный документ
Используйте шаблон, черновик или исходящий неотправленный документ в подходящих для этого сценариях. Ниже в таблице приведены различия этих сущностей.
Различия черновика, шаблона и исходящего неотправленного документа
| — | Шаблон | Черновик | Исходящий неотправленный документ |
|---|---|---|---|
| Свойства | Сообщение без подписей. На его основе можно создать один или несколько документов — в зависимости от настроек. С шаблоном можно работать в своем ящике или отправить контрагенту. | «Заготовка» документа, т.е. сущность, на основе которой можно создать один документ. | Уже готовый к отправке документ, сохраненный в разделе «Исходящие». Имеет статус «Требуется подписать и отправить». |
| Где хранится | в ящике отправителя или получателя | в ящике отправителя | в ящике отправителя |
| Можно ли редактировать перед отправкой | да, если указаны настройки редактирования | нет | да, если указаны настройки редактирования |
| Что будет после отправки | в зависимости от настроек: - если шаблон одноразовый, то он будет удален после создания документа; - если шаблон многоразовый, то он продолжит существовать после создания документа. | черновик будет удален | будет отправлен контрагенту |