Для взаимодействия с сервисом конвертации документов используются POST-запросы. Параметры запроса вводятся в формате JSON в теле запроса. Запросы отправляются на адрес https://documentserver/ConvertService.ashx, где documentserver — это имя сервера, на котором установлен Сервер документов Р7.

В Р7 Document Server до версии 4.2 использовался GET-запрос с параметрами в QueryString.

Параметр Описание Тип Наличие
Определяет тип запроса на конвертацю: асинхронный или нет.
Поддерживаемые значения:

  • true
  • false

При использовании асинхронного типа запроса ответ формируется мгновенно. В этом случае для получения результата необходимо отправлять запросы без изменения параметров до завершения конвертации. Значение по умолчанию false.

логический необязательно
Определяет кодировку файла при конвертации из формата csv или txt. Основные поддерживаемые значения:

  • 932 — Японский (Shift-JIS),
  • 950 — Китайский (Big5),
  • 1250 — Центральноевропейский (Windows),
  • 1251 — кириллица (Windows),
  • 65001 — Unicode (UTF-8).

Вы можете найти все поддерживаемые значения в этом файле

целое число необязательно
Определяет символы-разделители для разделения значений при преобразовании из формата csv. Поддерживаемые значения:

  • 0 — без разделителя,
  • 1 — вкладка,
  • 2 — точка с запятой,
  • 3 — двоеточие,
  • 4 — запятая,
  • 5 — пробел
целое число необязательно
Определяет макет документа, который задает параметры для печати форм в виде pdf-документов или изображений. объект необязательно
Определяет, будут ли отображаться заполнители или нет. логический необязательно
Определяет, будут ли формы выделены или нет. логический необязательно
Определяет, включен или выключен режим печати. Этот параметр используется только для преобразования docx/docxf в pdf. Если этот параметр равен true, флаги drawPlaceHolders и drawFormHighlight используются, как описано выше. Если этот параметр равен false, флаг drawFormHighlight не работает, а параметр drawPlaceHolders позволяет сохранять формы в формате pdf. Значение по умолчанию false. логический необязательно
Определяет визуализатор документа при конвертации из pdf, xps, oxps. объект необязательно
Определяет режим визуализатора, который может принимать следующие значения:

  • blockChar — весь текст конвертируется отдельными символами. Каждый символ находится в своем фрейме (как текстовое поле),
  • blockLine — весь текст конвертируется отдельными строками. Каждая текстовая строка находится в своем фрейме. Линии могут быть объединены в одном блоке,
  • plainLine — весь текст конвертируется как обычный текст. Но каждая строчка — это отдельный абзац,
  • plainParagraph — весь текст конвертируется как обычный текст. Строки объединяются в абзацы.

Значение по умолчанию — plainLine

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

  • ooxml — определяет, что файл будет преобразован в docx, docm, xlsx, xlsm, pptx или pptm. Например, при преобразовании файла doc в формат OOXML результирующий файл может быть docx или docm, если этот файл содержит макросы (то же самое для xls и ppt). Он также применяется при преобразовании файлов XML в форматы OOXML (docx, xlsx или pptx в зависимости от содержимого);
  • odf — определяет, что файл будет преобразован в odt, ods, odp. Например, он используется при преобразовании файлов XML в форматы ODF (odt, ods или odp в зависимости от содержимого).
строковый обязательно
Определяет пароль для файла документа, если он защищен паролем. строковый необязательно
Определяет формат отображения по умолчанию для валюты, даты и времени при преобразовании из формата электронной таблицы в pdf. Устанавливается с использованием четырехбуквенного кода языка (en-US, fr-FR и т. д.). Значение по умолчанию — en-US. строковый необязательно
Определяет настройки для конвертации электронной таблицы в pdf. объект необязательно
Задает высоту преобразованной области, измеряемую в количестве страниц. Значение по умолчанию равно 0. целое число необязательно
Задает ширину преобразованной области, измеряемую в количестве страниц. Значение по умолчанию равно 0. целое число необязательно
Позволяет включать линии сетки в выходной PDF-файл или нет. Значение по умолчанию равно false. логический необязательно
Позволяет включать заголовки в выходной PDF-файл или нет. Значение по умолчанию равно false. логический необязательно
Определяет, следует ли игнорировать область печати, выбранную для файла электронной таблицы, или нет. Значение по умолчанию true. логический необязательно
Устанавливает поля выходного PDF-файла. объект необязательно
Устанавливает нижнее поле выходного PDF-файла. Значение по умолчанию — 19,1 мм. строковый необязательно
Устанавливает левое поле выходного PDF-файла. Значение по умолчанию — 17,8 мм. строковый необязательно
Устанавливает правое поле выходного PDF-файла. Значение по умолчанию — 17,8 мм. строковый необязательно
Устанавливает верхнее поле выходного PDF-файла. Значение по умолчанию — 19,1 мм. строковый необязательно
Задает ориентацию выходного PDF-файла. Может быть горизонтальный, вертикальный. Значение по умолчанию — вертикальный. строковый необязательно
Устанавливает размер страницы выходного PDF-файла. объект необязательно
Устанавливает высоту страницы выходного PDF-файла. Значение по умолчанию — 297 мм. строковый необязательно
Устанавливает ширину страницы выходного PDF-файла. Значение по умолчанию — 210 мм. строковый необязательно
Позволяет установить масштаб выходного файла PDF. Значение по умолчанию — 100. целое число необязательно
Определяет настройки миниатюры при указании форматов изображения (bmp, gif, jpg, png) в качестве outputtype.  объект необязательно
Определяет режим, чтобы подогнать изображение под заданные высоту и ширину. Поддерживаемые значения:

  • 0 — растянуть файл по высоте и ширине,
  • 1 — сохранить пропорции изображения,
  • 2 — в этом случае настройки ширины и высоты не используются. Вместо этого метрические размеры страницы конвертируются в пиксели с разрешением 96 dpi. Например, страница формата А4 (210 x 297 мм) будет представлять собой изображение размером 794 x 1123 пикс.
    Значение по умолчанию — 2.
целое число необязательно
Определяет, должны ли миниатюры создаваться только для первой страницы или для всех страниц документа. Если false, будет создан zip-архив, содержащий миниатюры всех страниц. Значение по умолчанию true, логический необязательно
Определяет высоту миниатюры в пикселях. Значение по умолчанию — 100. целое число необязательно
Определяет ширину миниатюры в пикселях. Значение по умолчанию — 100. целое число необязательно
Определяет конвертируемое имя файла. строковый необязательно
Определяет зашифрованную подпись, добавленную в конфигурацию сервера документов в виде токена. строковый требуется по конфигурации
Определяет абсолютный URL-адрес документа, который необходимо преобразовать. Обязательно добавляйте токен при использовании локальных ссылок. В противном случае произойдет ошибка. строковый обязательно

* —  в таблицах ниже вы можете увидеть возможность конвертации ваших документов в наиболее известные форматы файлов, где столбец Input format соответствует значениям параметра filetype и параметра outputtype. 

Формат ввода Выходной формат
bmp docm docx docxf dotm dotx epub fb2 gif html jpg odt ott pdf pdfa png rtf txt
djvu                                    
doc                                    
docm                                    
docx                                    
docxf                                    
dot                                    
dotm                                    
dotx                                    
epub                                    
fb2                                    
fodt                                    
htm                                    
html                                    
mht                                    
mhtml                                    
odt                                    
ott                                    
oxps                                    
pdf                                    
rtf                                    
stw                                    
sxw                                    
txt                                    
wps                                    
wpt                                    
xml                                    
xps                                    
Формат ввода Выходной формат
bmp csv gif jpg ods ots pdf pdfa png xlsm xlsx xltm xltx
csv                          
et                          
ett                          
fods                          
ods                          
ots                          
sxc                          
xls                          
xlsb                          
xlsm                          
xlsx                          
xlt                          
xltm                          
xltx                          
xml                          
Формат ввода Выходной формат
bmp gif jpg odp otp pdf pdfa png potm potx ppsm ppsx pptm pptx
dps                            
dpt                            
fodp                            
odp                            
otp                            
pot                            
potm                            
potx                            
pps                            
ppsm                            
ppsx                            
ppt                            
pptm                            
pptx                            
sxi                            
{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
}

Где example.com — это имя сервера, на котором установлены менеджер документов и служба хранения документов. Дополнительные сведения о взаимодействии клиент-сервер службы Сервера документов см. в разделе как это работаетОбразец объекта JSON, отправленного в службу конвертации документов, которая используется для преобразования защищенного паролем файла из формата docx в формат pdf

{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "password": "123456",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
}

Образец объекта JSON, отправленного в службу конвертации документов, используемого для создания миниатюры файла png в формате docx

{
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "png",
    "thumbnail": {
        "aspect": 0,
        "first": true,
        "height": 150,
        "width": 100
    },
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
}

Образец объекта JSON, отправленного в службу конвертации документов, которая используется для преобразования файла электронной таблицы в формат pdf.

{
    "filetype": "xlsx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "region": "en-US",
    "spreadsheetLayout": {
        "ignorePrintArea": true,
        "orientation": "portrait",
        "fitToWidth": 0,
        "fitToHeight": 0,
        "scale": 100,
        "headings": false,
        "gridLines": false,
        "pageSize": {
            "width": "210mm",
            "height": "297mm"
        },
        "margins": {
            "left": "17.8mm",
            "right": "17.8mm",
            "top": "19.1mm",
            "bottom": "19.1mm"
        }
    },
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-spreadsheet.xlsx"
}

Образец объекта JSON содержит веб-токен JSON, отправленный в службу конвертации документов, используемую для преобразования файла из формата docx в формат pdf.

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxldHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3Iiwib3V0cHV0dHlwZSI6InBkZiIsInRpdGxlIjoiRXhhbXBsZSBEb2N1bWVudCBUaXRsZS5kb2N4IiwidXJsIjoiaHR0cDovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifQ.U-YAfuuy7clWjn-xOncfJ-sxVG5DlcYn0AOzJYkoR0M"
}

Где example.com — это имя сервера, на котором установлены менеджер документов и служба хранения документов. Дополнительные сведения о взаимодействии клиент-сервер службы Сервера документов см. в разделе как это работает

Результат запроса возвращается в формате XML. Для получения ответа в формате JSON необходимо указать заголовок Accept со значением application/json в HTTP-запросе (доступно с версии 4.3). При формировании ссылки на результирующий файл используется то же имя сервера, на которое был сделан запрос на конвертацию.

Параметры Описание Тип Пример
Определяет, завершена конвертация или нет. логический true
Определяет ошибку, возникшую во время конвертации. Возможные коды ошибок можно найти здесь. целое число -3
Определяет расширение конвертируемого файла. строковый «docm»
Определяет ссылку на конвертируемый документ. Этот параметр будет получен только в том случае, если для параметра endConvert установлено значение true. строковый «https://documentserver/url-to-converted-document.pdf»
Определяет процент конвертирования файла. Если для параметра endConvert задано значение true, процент равен 100. целое число 100
Образец ответа в формате XML
При формировании ссылки на результирующий файл используется то же имя сервера, на которое был сделан запрос на конвертацию.
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <EndConvert>True</EndConvert>
    <FileType>docm</FileType>
    <FileUrl>https://documentserver/url-to-converted-document.pdf</FileUrl>
    <Percent>100</Percent>
</FileResult>
Образец ответа в формате JSON
При формировании ссылки на результирующий файл используется то же имя сервера, на которое был сделан запрос на конвертацию.
{
    "endConvert": true,
    "fileType": "docm",
    "fileUrl": "https://documentserver/url-to-converted-document.pdf",
    "percent": 100
}
Пример промежуточного ответа на асинхронный запрос (с параметром async=true) в формате XML
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <EndConvert>False</EndConvert>
    <FileType></FileType>
    <FileUrl></FileUrl>
    <Percent>95</Percent>
</FileResult>
Пример промежуточного ответа на асинхронный запрос (с параметром async=true) в формате XML
{
    "endConvert": false,
    "percent": 95
}
Пример ответа при возникновении ошибки в формате XML
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <Error>-3</Error>
</FileResult>
Пример ответа при возникновении ошибки в формате JSON
{
    "error": -3
}
Код ошибки Описание
-1 Неизвестная ошибка
-2 Ошибка тайм-аута конвертации.
-3 Ошибка преобразования.
-4 Ошибка при загрузке файла документа для конвертации.
-5 Неправильный пароль
-6 Ошибка при доступе к базе данных результатов конвертации.
-7 Ошибка ввода.
-8 Недействительный токен.