Работа с черновиками

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

Сценарии использования черновиков 

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

Возможности и ограничения черновиков 

Черновик хранится в ящике отправителя. Контрагент его не видит и получит документы только после отправки сообщения.
В черновике нет подписей, поэтому юридической силы он не имеет.
В черновик можно включить документы любых типов, которые поддерживает метод 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. Черновик перемещается целиком, даже если в запросе указана только часть его документов.