Conversion API

1. Назначение и схема работы

Conversion API конвертирует документы, таблицы и презентации из одного формата в другой средствами Сервера документов Р7. Типичная задача — получить PDF или архивный PDF/A из файлов DOCX, XLSX или PPTX.

Актуально для версии r7-office-documentserver-ee 2025.4.1-1604.

Как проходит конвертация:

1. Ваше приложение размещает исходный файл по URL, доступному Серверу документов;
2. Приложение отправляет POST-запрос с параметрами в формате JSON на адрес https://documentserver/ConvertService.ashx;
3. Сервер документов сам скачивает файл по URL, конвертирует его и возвращает ссылку fileUrl на результат;
4. Приложение скачивает результат по fileUrl. Ссылка временная и подписанная, поэтому скачивайте файл сразу.

Подробнее о взаимодействии клиента и сервера — в разделе Как это работает ↗.

Вызывайте Conversion API со стороны сервера (бэкенда). Сервер документов не отдаёт CORS-заголовки для ConvertService.ashx, поэтому запрос из браузера со страницы на другом домене будет заблокирован. Кроме того, для подписи запроса нужен секретный ключ JWT, который нельзя размещать в коде страницы.

2. Адрес и формат запроса

Ошибки конвертации возвращаются с HTTP-статусом 200. Признак ошибки — поле error в ответе (раздел 9). Проверяйте это поле, а не только HTTP-статус.

3. Авторизация (JWT)

Если на Сервере документов включена проверка токенов (по умолчанию включена), каждый запрос должен содержать JWT, подписанный секретным ключом. Без токена или с неверной подписью сервер вернёт {"error": -8}.

3.1. Где посмотреть настройки

Настройки находятся в файле /etc/r7-office/documentserver/local.json:

"token": {
"enable": { "request": { "inbox": true, "outbox": true },
"browser": true },
"inbox": { "header": "AuthorizationJWT" },
"outbox": { "header": "AuthorizationJWT" }
},
"secret": {
"inbox": { "string": "secret" },
...
}

3.2. Способ 1: токен в теле запроса (рекомендуется)

Подпишите алгоритмом HS256 объект с параметрами запроса и передайте результат в поле token. Те же параметры можно продублировать в теле открыто — сервер использует данные из токена.

{
"async": false,
"filetype": "docx",
"key": "a7c3e9f01b2d",
"outputtype": "pdf",
"title": "report.docx",
"url": "https://storage.example.com/files/report.docx",
"token": "<JWT, подписанный HS256, payload = параметры выше без token>"
}

Достаточно передать и одно поле token — параметры сервер возьмёт из него. Пример ниже подписан ключом secret, в payload — параметры filetype, key, outputtype, title, url из примера 7.1:

{
"token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxldHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3Iiwib3V0cHV0dHlwZSI6InBkZiIsInRpdGxlIjoiRXhhbXBsZSBEb2N1bWVudCBUaXRsZS5kb2N4IiwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tZXhhbXBsZS1kb2N1bWVudC5kb2N4In0.52WfoJ8nvJZcg9sUQfiWPe4lqw324vZ2vIvs_nJdfZQ"
}

3.3. Способ 2: токен в заголовке

Передайте токен в заголовке с именем из token.inbox.header, с префиксом Bearer. В этом случае параметры запроса вкладываются в поле payload токена:

AuthorizationJWT: Bearer <JWT>

payload токена:

{
"payload": {
"filetype": "docx", "key": "a7c3e9f01b2d", "outputtype":
"pdf",
"title": "report.docx", "url":
"https://storage.example.com/files/report.docx"
}
}

3.4. Требования к токену

• Алгоритм подписи — HS256, ключ — значение secret.inbox.string;
• Все три части токена кодируются в base64url: символы «+» и «/» заменяются на «-» и «_», завершающие «=» удаляются. Это относится и к подписи;
• Токен подписывается, а не шифруется: его содержимое может прочитать любой, у кого он есть. Не передавайте в нём секретные данные.

Частая ошибка — кодировать подпись обычным base64 (например, CryptoJS.enc.Base64.stringify(hash)) и обрезать только последний символ «=». Такой токен проходит проверку лишь тогда, когда в подписи случайно нет символов «+» и «/». Используйте готовую JWT-библиотеку или замените символы, как показано в разделе 10.3.

4. Параметры запроса

Кеширование по key. Повторный запрос с тем же key и тем же outputtype возвращает ранее сконвертированный файл, даже если url указывает на другой документ. Для каждой новой версии файла генерируйте новый key, например хеш содержимого или пару «идентификатор файла + версия».

Обобщённые форматы в outputtype. Их используют, когда заранее неизвестно, какое расширение нужно:

• ooxml — результат будет DOCX, DOCM, XLSX, XLSM, PPTX или PPTM. Например, DOC с макросами станет DOCM, без макросов — DOCX (так же для XLS и PPT). При конвертации XML тип (DOCX, XLSX или PPTX) выбирается по содержимому;
• odf — результат будет ODT, ODS или ODP, например при конвертации XML в ODF по содержимому.

Если тип содержимого XML определить не удалось, сервер вернёт ошибку -9 — укажите формат явно.

4.1. documentLayout — печать форм

4.2. documentRenderer.textAssociation — распознавание текста из PDF

4.3. spreadsheetLayout — печать таблиц в PDF

4.4. thumbnail — получение изображений

5. Конвертация в PDF и PDF/A

Значение pdf даёт PDF 1.7, значение pdfa — PDF/A-2a. Других вариантов PDF и PDF/A нет.

5.1. Допустимые значения outputtype

Для получения PDF поддерживаются только два значения outputtype:

• pdf — обычный PDF;
• pdfa — PDF/A (архивный PDF).

Значения проверяются без учёта регистра (PDF и PDFA тоже работают). Любые другие варианты — pdfa1b, pdfa-1b, pdfa2a, pdfa1, pdfa2, pdfa3, pdf/a, PDF/A-1b, pdfua — возвращают ошибку -7. Отдельного параметра для выбора версии PDF или уровня PDF/A нет.

В обоих случаях в ответе fileType равен pdf, а файл результата имеет расширение .pdf.

5.2. Характеристики результата

Результаты одинаковы для всех проверенных исходных форматов: DOCX, XLSX, CSV, PPTX и PDF.

Заголовок %PDF-1.4 в файле PDF/A-2 не ошибка. Стандарт ISO 19005-2 допускает заголовок от %PDF-1.0 до %PDF-1.7. Соответствие PDF/A определяется содержимым файла и XMP-идентификацией, а не номером в заголовке.

5.3. PDF/A-1b и PDF/A-1a не поддерживаются

Получить средствами Сервера документов файл, соответствующий PDF/A-1 (1a или 1b), нельзя.

5.4. Что означает уровень A

Уровень A (accessible) требует логической структуры документа (тегов) и соответствия текста Юникоду. Конвертер строит теги автоматически по структуре исходного документа. Качество тегов зависит от исходного файла, поэтому для лучшего результата:

• оформляйте заголовки стилями «Заголовок 1», «Заголовок 2» и т. д., а не ручным форматированием;
• задавайте замещающий текст (alt text) для рисунков;
• указывайте язык документа.

5.5. Пример запроса PDF/A

POST https://documentserver/ConvertService.ashx
Content-Type: application/json
Accept: application/json

{
"async": false,
"filetype": "docx",
"key": "8f14e45fceea167a",
"outputtype": "pdfa",
"title": "contract.docx",
"url": "https://storage.example.com/files/contract.docx",
"token": "<JWT>"
}

Ответ:

{
"fileUrl":
"https://documentserver/cache/files/data/conv_8f14e45fceea167a_pdfa/output.pdf/contract.pdf?md5=...&expires=...&filename=contract.pdf",
"fileType": "pdf",
"percent": 100,
"endConvert": true
}

6. Поддерживаемые форматы

Значение filetype — формат исходного файла, outputtype — формат результата. Конвертация в тот же формат, что и исходный, не выполняется. Для неподдерживаемого направления сервер возвращает ошибку -7 или -3. Проверено на версии 2025.4.1-1604.

6.1. Текстовые документы

6.2. Электронные таблицы

6.3. Презентации

7. Примеры запросов

Во всех примерах example.com — сервер, на котором установлены менеджер документов и служба хранения документов. Поле token опущено: при включённой проверке JWT добавьте его, как описано в разделе 3.

7.1. DOCX → PDF

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

7.2. Защищённый паролем 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"
}

7.3. 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"
}

7.4. Таблица XLSX → 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 Spreadsheet Title.xlsx",
"url": "https://example.com/url-to-example-spreadsheet.xlsx"
}

Напоминание: в этих примерах везде один key. В реальной работе задавайте новый key для каждого файла и каждой его версии, иначе сервер вернёт закешированный результат (раздел 4).

8. Ответ сервера

По умолчанию ответ приходит в XML; с заголовком Accept: application/json — в JSON.

8.1. Поля ответа

Ссылка fileUrl строится по тому имени сервера, на которое пришёл запрос, и содержит подпись и срок действия (md5, expires). Скачивайте результат сразу после получения ответа.

8.2. Примеры ответов

Успешный ответ в формате JSON (с заголовком Accept: application/json):

{
"fileUrl":
"https://documentserver/cache/files/data/conv_a7c3e9f01b2d_pdf/output.pdf/report.pdf?md5=...&expires=...&filename=report.pdf",
"fileType": "pdf",
"percent": 100,
"endConvert": true
}

Успешный ответ в формате XML (без заголовка Accept):

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
<FileUrl>https://documentserver/cache/files/data/conv_a7c3e9f01b2d_pdf/output.pdf/report.pdf?md5=...&expires=...&filename=report.pdf</FileUrl>
<FileType>pdf</FileType>
<Percent>100</Percent>
<EndConvert>True</EndConvert>
</FileResult>

Ошибка в формате JSON:

{ "error": -8 }

Ошибка в формате XML:

<?xml version="1.0" encoding="utf-8"?>
<FileResult><Error>-8</Error></FileResult>

8.3. Асинхронный режим

При "async": true сервер отвечает сразу. Пока конвертация не завершена, ответ выглядит так.

В формате JSON:

{ "percent": 95, "endConvert": false }

В формате XML:

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
<EndConvert>False</EndConvert>
<FileType></FileType>
<FileUrl></FileUrl>
<Percent>95</Percent>
</FileResult>

Повторяйте тот же запрос с тем же key с интервалом около 1 секунды, пока не получите "endConvert": true и fileUrl (или error).

9. Коды ошибок

Все ошибки возвращаются с HTTP-статусом 200 — проверяйте поле error в ответе.

10. Примеры кода

10.1. Python (серверная сторона)

# pip install pyjwt
import secrets, jwt, requests

DS = "https://documentserver/ConvertService.ashx"
SECRET = "secret" # services.CoAuthoring.secret.inbox.string

params = {
"async": False,
"filetype": "docx",
"key": secrets.token_hex(8), # новый key для каждой версии файла
"outputtype": "pdfa", # или "pdf"
"title": "report.docx",
"url": "https://storage.example.com/files/report.docx",
}
params["token"] = jwt.encode(params, SECRET, algorithm="HS256")

r = requests.post(DS, json=params, headers={"Accept":
"application/json"}, timeout=300)
res = r.json()
if "error" in res:
raise RuntimeError(f"Conversion error {res['error']}")
pdf = requests.get(res["fileUrl"], timeout=60).content
open("report.pdf", "wb").write(pdf)

10.2. Node.js

// npm install jsonwebtoken
const jwt = require("jsonwebtoken");
const crypto = require("crypto");

const params = {
async: false,
filetype: "xlsx",
key: crypto.randomBytes(8).toString("hex"),
outputtype: "pdf",
title: "budget.xlsx",
url: "https://storage.example.com/files/budget.xlsx",
region: "ru-RU",
spreadsheetLayout: { orientation: "landscape", fitToWidth: 1,
fitToHeight: 0 },
};
params.token = jwt.sign(params, "secret", { algorithm: "HS256" });

const res = await fetch("https://documentserver/ConvertService.ashx",
{
method: "POST",
headers: { "Content-Type": "application/json", Accept:
"application/json" },
body: JSON.stringify(params),
}).then((r) => r.json());

10.3. Подпись токена без библиотеки JWT (CryptoJS)

Если токен формируется вручную, все части, включая подпись, должны быть в base64url:

function b64url(str) {
return str.replace(/\+/g, "-").replace(/\//g,
"_").replace(/=+$/, "");
}
const header64 = b64url(btoa(JSON.stringify({ alg: "HS256", typ:
"JWT" })));
const payload64 =
b64url(btoa(unescape(encodeURIComponent(JSON.stringify(payload)))));
const signature = b64url(CryptoJS.enc.Base64.stringify(
CryptoJS.HmacSHA256(header64 + "." + payload64, secret)));
const token = header64 + "." + payload64 + "." + signature;

Этот фрагмент — только для тестовых стендов. В рабочей системе секретный ключ не должен попадать в браузер: формируйте токен и вызывайте Conversion API на сервере.