Печать документов
В API Контур.Экстерна реализована печать документов в черновиках и документооборотах.
для печати документа в черновике используйте метод GET DraftDocumentPrint.
для печати документа в документообороте используйте метод POST DocflowDocumentPrint.
для печати документа в документообороте описи используйте метод POST DocumentPrint.
Особенности методов печати
Методы печати подготавливают печатную форму документа в формате pdf файла.
Методы работают только с расшифрованными контентами.
Методы поддерживают не все типы документов и контентов. Если печать невозможна, методы вернут ошибку 400 documentPrintUnsupported.
Методы печати умеют работать только со следующими типами контента:
«application/octet-stream»,
«application/xml»,
«text/xml».
Асинхронный вызов методов
Методы печати необходимо выполнять асинхронно. Для этого в параметрах запроса передайте флаг deferred = true.
Предупреждение
Значение флага false для синхронного вызова метода устарело и больше не используется в методах API. При таком значении вернется ошибка 400 BadRequest.
Асинхронный вызов запроса создает задачу на печать. В ответе метода вернется идентификатор TaskId поставленной задачи. Для получения печатной формы нужно проверить статус выполнения задачи. Когда статус задачи будет равен succeed, печатная форма будет загружена в сервис контентов. В поле task-result будет лежать идентификатор контента content-id.
Печать документа в черновике
Методу печати в черновике в запросе нужно передать только идентификатор документа, так как все расшифрованные контенты были предварительно загружены в черновик.
Алгоритм печати документа в черновике
Вызвать метод печати GET DraftDocumentPrint с флагом deferred = true. В случае успеха метод вернет идентификатор TaskId поставленной на печать задачи.
Получить задачу GET DraftDocumentTask по TaskId. Когда статус будет равен значению succeed, в поле task-result будет лежать идентификатор контента content-id.
Получить сформированную печатную форму документа GET Download по content-id.
Печать документа в документообороте
Как передать расшифрованный контент документа
Для метода печати в документообороте DocflowDocument Print в теле запроса необходимо передать идентификатор расшифрованного контента документа из сервиса контентов.
Если документ зашифрован, у документа в модели docflow-document-contents свойство encrypted равно true, то необходимо предварительно скачать и дешифровать документ. Если контент сжат — признак compressed = true, извлекать контент из архива не обязательно, метод умеет извлекать контент из архива. Далее нужно загрузить контент в сервис контентов. Полученный идентификатор передать в теле метода печати.
Если документ уже расшифрован, у документа признак encrypted равен false — скачивать ничего не нужно, в теле запроса передать идентификатор контента content-id. Идентификатор контента можно посмотреть в информации о документе, в параметре content.
Можно ли заранее узнать возможность печати?
В свойствах документа есть вспомогательный параметр SupportPrint (модель DocflowDocumentDescription). Это поле подсказывает, возможна ли печать документа. Оно может принимать значения: Yes, No, Unknown.
Если значение
SupportPrint = yes, можно вызывать метод печати, и он вернет печатную форму документа.Если значение
SupportPrint = no, печать документа не поддерживается.Если значение
SupportPrint = unknown, не получилось определить возможность печати документа, можно попробовать вызвать метод печати.
Проверка подписи в документообороте
Во время печати метод проверяет переданный на печать расшифрованный и разжатый документ на соответствие подписи этого документа в документообороте. Если на печать передали контент измененного документа, то вернется ошибка.
Алгоритм печати документа в документообороте
Для удобства тестирования печати можно скачать файл коллекции Postman:
Получить документ в документообороте методом GET DocflowDocument. В ответе важно посмотреть, что лежит в параметре docflow-document-contents: идентификатор content-id, по которому можно получить контент в сервисе контентов, флаги compressed и encrypted. В примере ниже контент документа зашифрован и сжат, флаги равны true.
Запрос
GET /v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8 HTTP/1.1
Ответ GET DocflowDocument:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
{
"id": "75d929b9-08a9-4692-961d-111cc87dc2e8",
"description": {
"type": "urn:document:fns534-report",
"filename": "NO_SRCHIS_0007_0007_7757424860680345565_20200129_92425a70-4ac9-4680-bada-3666f0c0514n.xml",
"content-type": "application/xml",
"encrypted-content-size": 2237,
"compressed": true,
"requisites": {},
"related-docflows-count": 0,
"support-recognition": false,
"encrypted-certificates": [
{
"serial-number": "01D0850043AB3C924A605B8D8661E43E"
},
{
"serial-number": "33AC7500C3AAAE924839AA8AE6C459FE"
},
{
"serial-number": "19CCC7C800010000215D"
}
],
"support-print": "yes"
},
"content": {
"encrypted": {
"rel": "encrypted-content",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/encrypted-content"
},
"docflow-document-contents": [
{
"content-id": "f1facbc3-5d74-498f-a8af-dbfd57f82f1f",
"encrypted": true,
"compressed": true
}
]
},
"send-date": "2020-02-26T06:51:08.4636938Z",
"signatures": [
{
"id": "82d5457d-5297-49fb-949a-f9865a1491b1",
"title": "ООО 'Баланс Плюс' (Марков Георгий Эльдарович)",
"signature-certificate-thumbprint": "20AACA440F33D0C90FBC052108012D3062D44873",
"content-link": {
"rel": "content",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/signatures/82d5457d-5297-49fb-949a-f9865a1491b1/content"
},
"links": [
{
"rel": "self",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/signatures/82d5457d-5297-49fb-949a-f9865a1491b1/content"
},
{
"rel": "docflow",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9"
}
]
},
{
"id": "045d9beb-7748-4789-a539-4416fa7969b9",
"title": "ООО 'Баланс Плюс' (Марков Георгий Эльдарович)",
"signature-certificate-thumbprint": "20AACA440F33D0C90FBC052108012D3062D44873",
"content-link": {
"rel": "content",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/signatures/045d9beb-7748-4789-a539-4416fa7969b9/content"
},
"links": [
{
"rel": "self",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/signatures/045d9beb-7748-4789-a539-4416fa7969b9/content"
},
{
"rel": "docflow",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9"
}
]
},
{
"id": "565164bb-c9d5-4805-8250-7f6a4ac9d4aa",
"title": "Корионов Илья Валерьянович",
"signature-certificate-thumbprint": "344AAD7111FC77ADE2A98FFB5E35F039BC4DD650",
"content-link": {
"rel": "content",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/signatures/565164bb-c9d5-4805-8250-7f6a4ac9d4aa/content"
},
"links": [
{
"rel": "self",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/signatures/565164bb-c9d5-4805-8250-7f6a4ac9d4aa/content"
},
{
"rel": "docflow",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9"
}
]
}
],
"links": [
{
"rel": "docflow",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9"
},
{
"rel": "self",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8"
},
{
"rel": "related-docflow",
"href": "https://extern-api.testkontur.ru//v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/related"
},
{
"rel": "encrypted-content",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/encrypted-content"
},
{
"rel": "decrypt-content",
"href": "https://extern-api.testkontur.ru/v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/decrypt-content"
}
]
}
Скачать контент из сервиса контентов GET Download по content-id.
Расшифровывать полученный документ и загрузить его обратно в сервис контентов POST Upload. В ответе метод вернет новый идентификатор content-id2.
Вызвать метод печати POST DocflowDocumentPrint с флагом deferred = true. В теле метода передать content-id2. В ответе вернется идентификатор поставленной на печать задачи TaskId.
Запрос
POST /v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/print?deferred=true HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
{
"content-id": "d065adea-8b9d-4228-bc17-8f86539e01a3"
}
Ответ
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 126
{
"id": "819ade20-665c-470a-befc-e897a56e1641",
"task-state": "running",
"task-type": "urn:task-type:docflowPrint"
}
Получить по TaskId результат выполнения задачи на печать в методе GET DocflowDocumentTask. Запрашивать задачу нужно до тех пор, пока task-state = running. Когда задача завершится со статусом succeed, в поле «task-result» будет лежать новый идентификатор content-id3.
Примечание
Чем больше документ, тем больше времени необходимо сервису для печати, рекомендуемый интервал между повторными запросами — 5 секунд.
Запрос
GET /v1/bd0cd3f6-315d-4f03-a9cc-3507f63265ed/docflows/a9bc74bd-311b-43f0-aff7-faba24ce35d9/documents/75d929b9-08a9-4692-961d-111cc87dc2e8/tasks/819ade20-665c-470a-befc-e897a56e1641 HTTP/1.1
Authorization: Bearer <token>
Ответ
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 210
{
"id": "819ade20-665c-470a-befc-e897a56e1641",
"task-state": "succeed",
"task-type": "urn:task-type:docflowPrint",
"task-result": {
"content-id": "9f6b57db-db9f-4e4c-8375-62a3504e663d"
}
}
Получить документ из сервиса контентов по content-id3. Будет загружен готовый pdf файл.