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

46 lines
2.9 KiB
Markdown

# Эндпоинт конвертации
```
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. Полная таблица ответов — [Коды ошибок](errors.md),
пороги — [Лимиты](limits.md).