Работа с черновиками
Определение черновика приведено на странице Черновик. Отличия черновика от шаблона и исходящего неотправленного документа приведены в таблице.
Сценарии использования черновиков
- Подготовкой документа занимается один сотрудник, а правом подписи обладает другой. Первый сотрудник создает черновик, второй — подписывает его и отправляет.
- Документ можно заполнять постепенно: сохранить частично заполненный титул и дополнить его позже в веб-интерфейсе Диадока.
- Перед подписанием документ можно проверить: открыть черновик в веб-интерфейсе Диадока и сверить содержимое и реквизиты.
- Интеграционное решение создает документ, а подписывают и отправляют его в веб-интерфейсе Диадока.
- Несколько документов можно отправить одним сообщением и подписать одновременно.
Возможности и ограничения черновиков
- Черновик хранится в ящике отправителя. Контрагент его не видит и получит документы только после отправки сообщения.
- В черновике нет подписей, поэтому юридической силы он не имеет.
- В черновик можно включить документы любых типов, которые поддерживает метод PostMessage (V3): формализованные, неформализованные и служебные.
- В одном черновике можно сохранить несколько документов и связать их между собой. При отправке все документы уйдут одним сообщением.
- Получателя, подразделение получателя и промежуточного получателя можно указать как при создании черновика, так и при его отправке. Если черновик создан без получателя, его нужно указать при отправке.
- Черновик можно защитить от изменений признаком
LockDraft, но только при создании. В заблокированном черновике нельзя добавлять или удалять документы, а уже указанных получателя, подразделение получателя и промежуточного получателя нельзя заменить. Если они не заполнены, их можно указать при отправке. Такой черновик можно только отправить, превратив в полноценное сообщение, либо удалить. - Черновик можно удалить без возможности восстановления и переместить в другое подразделение.
Черновик нельзя:
- передать контрагенту: получатель увидит только отправленное сообщение;
- отправить без подписи: подписать нужно все документы черновика;
- создать с отложенной отправкой — признак
DelaySend; - создать в закрытом пакете — признак
LockPacket; - создать с зашифрованными документами и с документами, у которых есть настройки редактирования;
- создать с несколькими участниками — поле
DocumentAttachments.ParticipantRoles; - восстановить после удаления.
Действия с черновиками
С черновиками может работать сотрудник организации, у которого есть доступ к подразделению с черновиком. Он может:
- создать черновик,
- изменить черновик,
- отправить черновик,
- получить черновик и события по нему,
- удалить или переместить черновик.
Список действий, доступных пользователю для конкретного черновика, возвращает метод GetDocumentActions.
Создание черновика
Чтобы создать черновик, вызовите метод PostMessage (V3) и установите признак IsDraft = true в структуре MessageToPost. Диадок сохранит сообщение в ящике отправителя, но не будет формировать задание на доставку его получателю.
В запросе укажите следующие поля:
FromBoxId— идентификатор ящика отправителя.DocumentAttachments— список документов, представленных структурой DocumentAttachment. В каждом документе заполнитеTypeNamedId, при необходимости —FunctionиVersion, содержимое в полеSignedContent.Contentи обязательные метаданные. Поля подписи оставьте пустыми: при создании черновика подписи указывать нельзя.ToBoxId— идентификатор ящика получателя. Можно не указывать: если черновик создан без получателя, укажите его при отправке.ToDepartmentId— идентификатор подразделения получателя.FromDepartmentId— идентификатор подразделения отправителя. Если не указан, используется подразделение сотрудника.ProxyBoxIdиProxyDepartmentId— ящик и подразделение промежуточного получателя.IsInternal— признак внутреннего черновика. Для внутреннего черновикаToBoxIdуказывать нельзя, аToDepartmentIdобязателен.LockDraft— признак того, что черновик защищен от изменений.StrictDraftValidation— признак проверки формата содержимого. По умолчанию равенtrue. Если указатьfalse, черновик можно сохранить с частично заполненным документом. ПриLockDraft = trueпроверка выполняется независимо от значения этого признака.
Чтобы связать документы черновика между собой, заполните InitialDocumentIds и SubordinateDocumentIds. Для ссылки на документ внутри черновика передайте в поле DocumentId.MessageId пустую строку, а в поле DocumentId.EntityId — значение CustomDocumentId этого документа.
Метод вернет сообщение-черновик, представленное структурой Message. Сохраните идентификаторы сущностей EntityId из ответа: они понадобятся при отправке черновика.
Пример тела запроса метода PostMessage для черновика:
{
"FromBoxId": "{{boxId_sender}}",
"ToBoxId": "{{boxId_recipient}}",
"IsDraft": true,
"DocumentAttachments": [
{
"SignedContent": {
"Content": "{{content}}" // содержимое файла документа в кодировке base-64
},
"TypeNamedId": "Nonformalized",
"Metadata": [
{
"Key": "FileName",
"Value": "document.pdf"
}
]
}
]
}
Редактирование черновика
Состав документов и их содержимое задаются при создании черновика. Через API нельзя добавить или удалить документ, заменить содержимое целиком, изменить комментарий или метаданные. Чтобы изменить черновик, откройте его в веб-интерфейсе Диадока или удалите черновик и создайте новый.
Через API можно изменить:
- получателя, подразделение получателя и промежуточного получателя — в запросе метода SendDraft. Незаполненные реквизиты можно указать и в защищенном черновике, а уже указанные заменить нельзя;
- подписи — в запросе метода SendDraft;
- данные подписанта в первом титуле документа — методом PrepareDocumentsToSign;
- подразделение отправителя — методом MoveDocuments.
Данные подписанта
Чтобы дополнить первый титул документа данными подписанта, вызовите метод PrepareDocumentsToSign и заполните в структуре PrepareDocumentsToSignRequest список DraftDocuments. Для каждого документа укажите DocumentId и данные подписанта: Signer, ExtendedSigner или SignerContent. Если нужно, заполните ToBoxId: по умолчанию используется ящик получателя из черновика.
Метод не меняет черновик. Он формирует новое содержимое документа и возвращает его в поле DocumentPatchedContents.Content вместе с идентификатором PatchedContentId. Подпишите новое содержимое и передайте подпись и PatchedContentId в структуре DocumentSenderSignature при вызове метода SendDraft: при отправке Диадок заменит содержимое черновика подготовленным.
Пример тела запроса метода PrepareDocumentsToSign для черновика:
{
"BoxId": "{{boxId}}",
"DraftDocuments": [
{
"DocumentId": {
"MessageId": "{{draftId}}",
"EntityId": "{{entityId}}"
},
"SignerContent": "PD94bWwgdm...AgPC9TaWduZXJzPg==" // содержимое XML-файла с данными подписанта в кодировке base-64
}
]
}
Подготовка к подписанию доступна не для всех документов. Проверьте свойство SupportsContentPatching версии документа, полученной методом GetDocumentTypes (V3). Подробнее — на странице Подготовка документа к подписанию.
Отправка черновика
Чтобы отправить черновик и превратить его в сообщение, вызовите метод SendDraft и передайте структуру DraftToSend:
BoxId— идентификатор ящика отправителя.DraftId— идентификатор черновика.ToBoxIdиToDepartmentId— ящик и подразделение получателя. Указывайте их, если в черновике не было получателя или его нужно изменить. В защищенном черновике можно только заполнить отсутствующие реквизиты, заменить указанные нельзя. Для внутреннего черновикаToBoxIdуказывать нельзя, аToDepartmentIdобязателен.DocumentSignatures— список подписей к документам черновика, представленных структурой DocumentSenderSignature. Укажите подпись для каждого документа: в полеParentEntityIdпередайте идентификатор сущности документа из черновика, в полеSignature— файл подписи. При необходимости заполнитеPowerOfAttorney,SignWithTestSignatureиPatchedContentId.ProxyBoxIdиProxyDepartmentId— ящик и подразделение промежуточного получателя.
Метод работает по следующим правилам:
- Подписать нужно все документы черновика. Если подписи нет хотя бы для одного документа, метод вернет ошибку
400 (Bad Request). - Получатель должен отличаться от отправителя. Если в черновике не было получателя, укажите его в запросе, иначе метод вернет ошибку
400 (Bad Request). - Сотрудник должен иметь право подписи, иначе метод вернет ошибку
403 (Forbidden). Отправить черновик нельзя, если отправитель или получатель отключен от оператора ЭДО или ликвидирован. - В защищенном черновике (
LockDraft = true) нельзя заменить уже указанных получателя, подразделение получателя и промежуточного получателя: метод вернет ошибку409 (Conflict). Отсутствующие реквизиты можно заполнить и у защищенного черновика. - Отправить утилизированный черновик нельзя: если черновик удален или из него уже создано сообщение, метод вернет ошибку
409 (Conflict). - Содержимое черновика проверяется при отправке. Даже если черновик сохранен без проверки формата (
StrictDraftValidation = false), некорректный документ отправлен не будет.
После успешной отправки Диадок создает сообщение и возвращает его в теле ответа. Черновик становится утилизированным: в нем заполняется признак DraftIsRecycled и список DraftIsTransformedToMessageIdList с идентификатором сообщения. В самом сообщении идентификатор черновика указан в поле CreatedFromDraftId.
Пример тела запроса метода SendDraft:
{
"BoxId": "{{boxId_sender}}",
"ToBoxId": "{{boxId_recipient}}",
"DraftId": "{{draftId}}",
"DocumentSignatures": [
{
"ParentEntityId": "{{parentEntityId}}",
"Signature": "MIINoAYJK..." // содержимое файла подписи в кодировке base-64
}
]
}
Получение черновиков и событий
Черновик можно получить методами чтения ленты событий GetNewEvents (V8) и GetDocflowEvents (V4). Если известен идентификатор черновика, используйте метод GetMessage (V6).
Чтобы найти черновик по ленте событий, передайте в метод фильтр по типу сообщения:
- GetDocflowEvents (V4) — значение
MessageTypes = Draftв структуре GetDocflowEventsRequest; - GetNewEvents (V8) — значение
messageType = Draftв параметрах запроса.
По значениям MessageId и EntityId из события получите черновик методом GetMessage (V6). События по черновикам в методе GetNewEvents доступны пользователям, у которых есть доступ ко всем документам организации.
Метод GetMessage (V6) вернет структуру Message с типом MessageType = Draft и признаками черновика:
DraftIsLocked— черновик заблокирован: в него нельзя добавлять или удалять документы. Такой черновик можно только отправить, превратив в полноценное сообщение, либо удалить.DraftIsRecycled— черновик утилизирован: его удалили либо на его основе создали и отправили получателю полноценное сообщение.DraftIsTransformedToMessageIdList— список идентификаторов сообщений, созданных на основе черновика. Заполняется, если на основе черновика отправили сообщение; у такого сообщения заполнено полеCreatedFromDraftId.
Признаки DraftIsLocked, DraftIsRecycled и DraftIsTransformedToMessageIdList заполняются только в структурах Message, которые представляют черновики.
Чтобы получить содержимое документа из черновика, используйте метод GetEntityContent (V4) или параметр injectEntityContent = true метода GetMessage (V6).
Документ черновика можно получить методом GetDocument (V3). Признаков черновика в ответе этого метода нет.
Признаки черновика содержит поле DraftInfo в структуре DocumentInfoV3. Их возвращают методы работы с документооборотом. Например, вызовите метод GetDocflowEvents (V4) с параметром PopulateDocuments = true: в событии DocflowEventV4 поле Document будет содержать структуру DocumentWithDocflowV4, в поле DocumentInfo — структуру DocumentInfoV3, а в поле DraftInfo, представленном структурой DocumentDraftInfo, будут признаки IsRecycled и IsLocked и список TransformedToLetterIds.
Историю событий по документу черновика возвращает метод GetDocumentHistory.
Метод GetDocuments (V3) не возвращает черновики, поэтому отдельного списка черновиков получить нельзя.
Удаление и перемещение черновика
Чтобы удалить черновик, вызовите метод RecycleDraft и передайте идентификаторы ящика и черновика. Если черновика нет, метод вернет ошибку 404 (Not Found), если черновик уже утилизирован — ошибку 409 (Conflict). Чтобы удалить черновик, у сотрудника должно быть право удалять документы и черновики, иначе метод вернет ошибку 403 (Forbidden).
Удаление черновика необратимо: восстановить его нельзя. Метод Delete для черновика не работает и возвращает ошибку 409 (Conflict).
Чтобы переместить черновик в другое подразделение, вызовите метод MoveDocuments. В структуре DocumentsMoveOperation укажите документы черновика и подразделение в поле ToDepartmentId. Черновик перемещается целиком, даже если в запросе указана только часть его документов.