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

Работать с документами можно только внутри сообщения.

Генерация формализованного документа ¶

Через Диадок можно отправить как формализованные, так и неформализованные документы. Неформализованные документы могут быть представлены в любом формате. Формализованные документы должны представлять собой XML-файлы в формате, рекомендованном ФНС.

Вы можете сформировать формализованный документ самостоятельно или с помощью метода GenerateTitleXml. Для этого в метод GenerateTitleXml нужно передать следующие параметры:

documentTypeNamedId — тип документа;
documentFunction — функция документа;
documentVersion — версия документа;
titleIndex — идентификатор титула документа.

Получить тип, функцию, версию, идентификатор титула и ссылку на скачивание XSD-схемы можно с помощью метода GetDocumentTypes. В ответе метод возвращает описание всех типов документов, доступных в ящике.

В теле запроса метода GenerateTitleXml нужно передать XML-файл UserDataXsd, соответствующий XSD-схеме. UsedDataXsd содержит информацию для генерации титула, которую может заполнить только пользователь.

Метод GenerateTitleXml вернет в ответе XML-файл титула, сгенерированный в соответствии с указанной XSD-схемой. Полученный файл можно подготовить к подписанию и отправить как формализованный документ или сохранить как черновик и отправить позже.

Подготовка документа к подписанию ¶

Метод PrepareDocumentsToSign позволяет автоматически добавить в XML-файл информацию о подписанте. К подписанию можно подготовить черновик, незагруженный в Диадок формализованный документ или неотправленный исходящий документ. Дополнить можно только первый титул документа, второй титул генерируется сразу со всеми данными.

Кроме данных подписанта в файл можно добавить:

версию формата и программы,

дату и время формирования файлов,

идентификатор файла.

Данные подписанта, в зависимости от его типа, можно указать в структурах Signer или ExtendedSigner или в поле SignerContent. Чтобы определить тип подписанта, используйте метод GetDocumentTypes, тип подписанта вернется в поле SignerType структуры SignerInfoV2.

В зависимости от типа подписанта заполните его следующим образом:

простой подписант — при вызове метода PrepareDocumentsToSign заполните структуру Signer.

расширенный подписант — при вызове метода PrepareDocumentsToSign заполните структуру ExtendedSigner.

универсальный подписант — передайте бинарное представление упрощенного XML-файла подписанта в поле SignerContent. Чтобы подготовить упрощенный XML-файл подписанта, выполните следующие действия:

С помощью метода GetDocumentTypes получите URL-путь метода, возвращающего файл XSD-схемы упрощенного XML подписанта. URL-путь возвращается в поле SignerUserDataXsdUrl.

С помощью URL-пути вызовите метод GetContent. В ответ метод вернет файл XSD-схемы SignerUserData.xsd.

По полученной схеме подготовьте упрощенный XML-файл подписанта одним из следующих способов:

используйте кодогенерацию в SDK;

вручную укажите все данные для блока Подписант в упрощенном XML-файле;

укажите в файле данные, по которым Диадок сможет дополнить информацию, например, идентификатор ящика организации, отпечаток сертификата, регистрационный номер МЧД и ИНН доверителя. Диадок по переданным данным заполнит блок Подписант.

В ответе метод PrepareDocumentsToSign возвращает список документов, подготовленных к подписанию и отправке.

Отправка сообщения ¶

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

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

укажите идентификатор ящика получателя в поле ToBoxId;

используйте вложенную структуру DocumentAttachment для передачи XML-файла:

XML-файл передайте в поле Content структуры SignedContent;

подпись перейдайте в поле Signature структуры SignedContent;

укажите тип документа в поле TypeNamedId;

укажите функцию документа в поле Function;

укажите версию документа в поле Version.

передать машиночитаемую доверенность (МЧД) можно во вложенной структуре PowerOfAttorneyToPost. Это можно сделать следующими способами:

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

использовать флаг UseDefault = true, если у пользователя установлена МЧД по умолчанию;

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

Пример заполнения структуры MessageToPost:

"FromBoxId": "db32772b-9256-49a8-a133-fda593fda38a",
"ToBoxId": "13254c42-b4f7-4fd3-3324-0094aeb0f15a",
"DocumentAttachments": [
        {
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0...NC50Ls+",        //контент xml-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvcNAQcCoIIN1jCCDdIA...kA9MJfsplqgW",       //контент файла подписи в кодировке base-64
                {
                    "PowerOfAttorney":
                        "FullId":
                       {
                            "RegistrationNumber": "регистрационный номер МЧД",
                            "IssuerInn": "ИНН доверителя"
                        },
                },
            },
            "TypeNamedId": "тип документа",
            "Function": "функция документа",
            "Version": "версия документа"
        }
    ]
}

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

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

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

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

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

Если размер отправляемого документа больше 500 Кб, рекомендуем использовать полку документов.

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

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

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

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

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

Чтобы сохранить документ без отправки, используйте функцию отложенной отправки. Для этого в структуре MessageToPost установите флаг DelaySend. При вызове метода PostMessage документ с этим флагом будет сохранен в разделе исходящих документов. Такой документ называется исходящим неотправленным документом.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сформированные сообщения можно дополнять служебными документами и титулами последующих участников с помощью метода PostMessagePatch, в который передается структура MessagePatchToPost. Эта структура должна содержать идентификатор ящика, хранящего сообщение, и идентификатор цепочки документооборота, которую нужно дополнить новым документом. Пользователь, вызывающий метод, должен иметь доступ к ящику, в котором хранится сообщение.

Пример заполнения структуры MessagePatchToPost:

"BoxId": "db32772b-9256-49a8-a133-fda593fda38a",
"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
            }
        }
    ]
}

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

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

Генерация формализованного документа¶

Подготовка документа к подписанию¶

Отправка сообщения¶

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

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

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

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