Шаблоны, черновики и отложенное подписание титулов ЭТрН

Эта страница описывает, как подготовить титул электронной транспортной накладной (ЭТрН) заранее и отправить его после проверки или подписи.

Способы отправить титул без подписи 

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

Сравнение шаблона, черновика и отложенного подписания для ЭТрН
	Шаблон	Черновик	Отложенное подписание
Метод API	PostTemplate	PostMessage (V3)	PostMessage (V3)
Признак	—	`IsDraft = true`	`DelaySend = true`
Где хранится документ до отправки	В ящике получателя шаблона	В ящике организации-отправителя, в черновиках	В исходящих документах организации-отправителя
Кто подписывает итоговый документ	Организация-отправитель итогового документа (идентификатор ящика `MessageFromBoxId`)	Организация, из ящика которой создан черновик (идентификатор ящика `FromBoxId`)	Организация, из ящика которой создан документ (идентификатор ящика `FromBoxId`)
Кто может редактировать содержимое до отправки	Организация, которая создает итоговый документ из шаблона, — только в случае, если указаны настройки редактирования `EditingSettingId`*	Черновик нельзя редактировать как документ через API. Можно изменить реквизиты сообщения и добавить подписи при отправке, если не установлен признак `LockDraft`**	Организация-отправитель — только в случае, если указаны настройки редактирования `EditingSettingId`*
Нужен ли идентификатор ящика	`FromBoxId`, `ToBoxId`, `MessageFromBoxId` и `MessageToBoxId`	Только `FromBoxId`	`FromBoxId` и `ToBoxId`
Содержимое	XML в кодировке Base64	XML в кодировке Base64	XML в кодировке Base64

* EditingSettingId — настройка редактирования; определяет, какие поля документа разрешено изменить перед отправкой. Подробнее — на странице Настройки редактирования.

** LockDraft — настройка для защиты черновика от изменений: ее можно указать при создании черновика в структуре MessageToPost.

Выбор способа зависит от вашего сценария:

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

Шаблон 

Шаблон — предварительно заполненный титул Т1 без подписи. Подробнее о шаблонах и сценариях их использования — на странице Работа с шаблонами.

Составитель шаблона не подписывает титул Т1. Это делает грузоотправитель или лицо, осуществляющее погрузку (ЛОП).

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

При отправке шаблона нужно указать двух адресатов:

получателя шаблона;
получателя итогового документа.

Отправка шаблона 

Чтобы отправить шаблон, вызовите метод PostTemplate. Содержимое шаблона передайте в поле UnsignedContent: для шаблона не нужно указывать подпись.

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

маршрут шаблона:
- FromBoxId — идентификатор ящика организации, которая создает шаблон;
- ToBoxId — идентификатор ящика грузоотправителя: он получит шаблон и подпишет титул Т1.
маршрут будущего документа:
- MessageFromBoxId — идентификатор ящика грузоотправителя;
- MessageToBoxId — идентификатор ящика перевозчика, будущего получателя подписанного титула Т1.

Алгоритм отправки документа из шаблона:

Вызовите метод PostTemplate и сохраните из ответа идентификатор сообщения MessageId шаблона и идентификатор сущности EntityId титула Т1.
Когда грузоотправитель получит шаблон в своем ящике, вызовите метод TransformTemplateToMessage и укажите в запросе:
- BoxId — идентификатор ящика грузоотправителя;
- TemplateId — идентификатор сообщения MessageId шаблона;
- DocumentId — идентификатор сущности EntityId титула Т1; поле входит в список преобразований документов DocumentTransformations.
В результате появится исходящее, но еще неотправленное сообщение от грузоотправителя перевозчику.
Если для шаблона задан идентификатор настройки редактирования EditingSettingId, грузоотправитель может дополнить документ, созданный из шаблона. Для этого вызовите метод PostMessagePatch (V4) и передайте список операций редактирования EditingPatches. Дополнить документ можно только до того, как грузоотправитель подпишет титул Т1.
Грузоотправитель подписывает титул Т1 квалифицированной электронной подписью (КЭП). Чтобы добавить подпись, вызовите метод PostMessagePatch (V4) и передайте ее в списке подписей Signatures. После добавления подписи Диадок отправит титул Т1 перевозчику.

Примечание

Созданный из шаблона титул Т1 уходит от лица грузоотправителя, а не от лица вашей организации. Составитель шаблона готовит только его содержимое.

Пример тела запроса метода PostTemplate с настройкой редактирования:

{
    "FromBoxId": "{{boxId_author}}",
    "ToBoxId": "{{boxId_shipper}}",
    "MessageFromBoxId": "{{boxId_shipper}}",
    "MessageToBoxId": "{{boxId_carrier}}",
    "DocumentAttachments": [
        {
            "TypeNamedId": "LogisticsWaybill",
            "Function": "reception",
            "Version": "kl_trn_mt_05_01",
            "UnsignedContent": {
                "Content": "{{content_t1}}"
            },
            "EditingSettingId": "9D2B3E4A-7F1C-4E55-A6D0-1E8C5F2B9A37"
        }
    ]
}

Пример тела запроса метода PostTemplate без настройки редактирования:

{
    "FromBoxId": "{{boxId_author}}",
    "ToBoxId": "{{boxId_shipper}}",
    "MessageFromBoxId": "{{boxId_shipper}}",
    "MessageToBoxId": "{{boxId_carrier}}",
    "DocumentAttachments": [
        {
            "TypeNamedId": "LogisticsWaybill",
            "Function": "reception",
            "Version": "kl_trn_mt_05_01",
            "UnsignedContent": {
                "Content": "{{content_t1}}"
            }
        }
    ]
}

Черновик 

Черновик — титул без подписи. Черновик доступен только организации, которая его создала: отправить черновик другой организации нельзя. Подробнее о черновиках — в разделе Создание черновика.

Черновик используют в следующих случаях:

Поэтапное заполнение титула — промежуточное сохранение (доступно только при StrictDraftValidation = false).
Передача на подпись другому лицу.
Передача водителю на предварительное согласование.

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

Чтобы создать черновик, вызовите метод PostMessage (V3) и установите признак IsDraft = true. В веб-интерфейсе Диадока такой черновик можно будет найти в разделе «Черновики». Он не подписан и не считается исходящим.

Черновик нужно создать в ящике отправителя: для этого в запросе нужно указать идентификатор ящика FromBoxId. Идентификатор ящика получателя ToBoxId можно не указывать. Если в черновике его не было, укажите его при отправке.

Документ может быть либо черновиком, либо с отложенной отправкой: поэтому в запросе можно указать только один признак: IsDraft или DelaySend.

Пример тела запроса метода PostMessage для черновика титула Т1:

{
    "FromBoxId": "{{fromBoxId}}",
    "IsDraft": true,
    "DocumentAttachments": [
        {
            "TypeNamedId": "LogisticsWaybill",
            "Function": "reception",
            "Version": "kl_trn_mt_05_01",
            "SignedContent": {
                "Content": "{{content_t1}}"
            }
        }
    ]
}

Для отправки черновика вызовите метод SendDraft.

Правила работы с черновиком 

Признак IsDraft не нужно переводить в false: для отправки документа его нужно удалить из запроса. Если вы не планируете создавать черновик, уберите признак IsDraft и признак внутреннего сообщения IsInternal: так документ не станет черновиком и внутренним документом. Оставленный признак IsDraft — частая причина, по которой документ вместо отправки контрагенту оказывается в черновиках.
Обычно в черновик вкладывают полностью заполненное содержимое документа, иначе он не пройдет проверку.
Для черновика действуют те же самые требования формата, что и для документа. Чтобы отключить проверку формата, установите StrictDraftValidation = false в структуре MessageToPost: так можно сохранить частично заполненный титул. При вызове метода SendDraft черновик будет проверен перед отправкой. Обратите внимание, если одновременно установлен признак LockDraft = true, проверка будет выполнена независимо от значения StrictDraftValidation. Перед отправкой черновика методом SendDraft проверка будет выполнена повторно, и некорректный документ отправлен не будет.
Удаление черновика необратимо. Черновик можно удалить в веб-интерфейсе Диадока или с помощью метода RecycleDraft, но отменить удаление будет нельзя.
Содержимое черновика нельзя отредактировать через API (доступно только через веб-интерфейс). Чтобы заменить содержимое через API, удалите черновик и создайте новый. Реквизиты сообщения и подписи можно добавить при отправке методом SendDraft, если не установлен признак LockDraft.

Отложенное подписание 

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

Отправка документа с отложенным подписанием 

Для отправки документа с отложенным подписанием вызовите метод PostMessage (V3) и установите признак DelaySend = true. Уберите из запроса признак IsDraft и подпись.

Подписать такой документ можно с помощью метода PostMessagePatch (V4) или вручную в веб-интерфейсе Диадока. Подписание основной подписью равносильно отправке.

Пример тела запроса метода PostMessage для титула Т1 с отложенным подписанием:

{
    "FromBoxId": "{{fromBoxId}}",
    "ToBoxId": "{{toBoxId}}",
    "DelaySend": true,
    "DocumentAttachments": [
        {
            "TypeNamedId": "LogisticsWaybill",
            "Function": "reception",
            "Version": "kl_trn_mt_05_01",
            "SignedContent": {
                "Content": "{{content_t1}}"
            }
        }
    ]
}