b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
46 lines
2.9 KiB
Markdown
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).
|