Files
java-word-pdf/docs/api/convert-endpoint.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

2.9 KiB

Эндпоинт конвертации

POST /api/v1/convert

Тело запроса — multipart/form-data с обязательным полем file: файл .docx (OOXML) или .doc (Word 97–2003, переносится мостом в .docx в памяти). Файлы других расширений отклоняются 400.

Факультативные query/form-параметры

Параметры можно передать в query-строке или как form-поля.

Параметр Тип Дефолт Действие
errorOnCharts Boolean false при true диаграммы в документе отменяют конвертацию (422); диаграммы конвертируются в растры всегда
errorOnSmartArt Boolean false при true SmartArt отменяет конвертацию (422)
errorOnOle Boolean false при true OLE-объекты отменяют конвертацию (422); при false OLE-объекты тихо удаляются, картинка-плейсхолдер сохраняется
maxMb число свойство сервера wordpdf.max-mb (5) лимит размера входа в МБ; переопределяет серверный дефолт в обе стороны; ≤ 0 → 400
maxPages число свойство сервера wordpdf.max-pages (100) лимит числа страниц; переопределяет в обе стороны; ≤ 0 → 400

!!! note "На .doc error-флаги не срабатывают" Плейсхолдеры диаграмм/SmartArt/OLE в бинарном формате — это BLIP-растры, мост вставляет их картинками; векторные EMF/WMF/PICT пропускаются с warn. Флаги работают только для .docx.

Успешный ответ

HTTP 200
Content-Type: application/pdf
Content-Disposition: attachment; filename*=UTF-8''Документ.pdf

Имя файла берётся из Content-Disposition загруженного файла, санитизируется (разрешены буквы, цифры, пробел и ._-; кириллица разрешена; пустое имя → document) и используется единожды для имени файла, заголовка ответа и заголовка PDF.

Обработка

Задача ставится в однопоточную очередь воркеров (16 мест). Проверка размера — синхронно до очереди. Конвертация дольше wordpdf.convert-timeout (2m) → 504, очередь полна → 503. Полная таблица ответов — Коды ошибок, пороги — Лимиты.