Документация

Документация API

Нужна точная спецификация?

Полный OpenAPI-справочник со всеми параметрами и схемами — в одном месте.

Справочник API

Базовый URL: https://api.mkpdf.ru (резервный хост — https://api.lt.mkpdf.ru, см. ниже). Каждый запрос к /v1/* требует заголовок Authorization: Bearer <API-ключ> (ключ создаётся в личном кабинете). Из месячной квоты списываются только успешные операции — неудачная конвертация (некорректные входные данные, сбой движка) в квоту не засчитывается.

Резервный хост

Основной хост — https://api.mkpdf.ru. Если он недоступен (например, из-за проблем с маршрутизацией до вашей сети), тот же API доступен через прокси в Латвии — https://api.lt.mkpdf.ru.

Меняется только хост: пути (/v1/...), параметры, формат ответов и заголовок Authorization: Bearer <api key> остаются прежними, тот же API-ключ.
Это запасной вариант: пользуйтесь основным хостом, а на резервный переключайтесь, когда основной не отвечает (таймаут, ошибка соединения или 502/503 от сетевого уровня). Через прокси возможна дополнительная задержка.
Ошибки самого API (400, 401, 413, 422, 429) на резервном хосте те же и означают то же самое — переключение хоста их не исправит.

# основной хост не ответил — тот же запрос через резервный
curl -X POST https://api.lt.mkpdf.ru/v1/merge \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@part1.pdf" -F "files=@part2.pdf" \
  --output merged.pdf

Postman

Готовая коллекция для Postman (формат Collection v2.1.0) со всеми эндпоинтами, разложенными по папкам, и два окружения — для основного и резервного хоста:

Импортируйте коллекцию и одно из окружений, выберите окружение и впишите свой API-ключ в переменную api_key (она хранится как секрет). Если основной хост недоступен, переключитесь на окружение с резервным — запросы менять не нужно. Коллекция генерируется из openapi.yaml, поэтому совпадает с этим справочником.

Быстрый старт

Зарегистрируйтесь и создайте API-ключ в личном кабинете.
Отправьте запрос на нужный эндпоинт с заголовком Authorization: Bearer <ваш ключ>.
Получите готовый PDF в теле ответа (application/pdf) либо ссылку на файл, если указали "deliver": "url".

`POST /v1/convert/html`

Конвертирует HTML-разметку в PDF через Chromium — с полноценным CSS, кастомными шрифтами и кириллицей из коробки.

curl -X POST https://api.mkpdf.ru/v1/convert/html \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Счёт №482</h1><p>Итого: 14 300 ₽</p>",
    "options": { "format": "A4", "margin": "16mm" }
  }' \
  --output invoice.pdf

Тело запроса

Поле	Тип	Обязательное	Описание
`html`	string	да	HTML-разметка страницы
`options.format`	string	нет	`A4` (по умолчанию) \| `Letter` \| `Legal`
`options.margin`	string	нет	`"16mm"` \| `"1in"` \| `"2cm"` (число без суффикса — миллиметры)
`options.landscape`	bool	нет	альбомная ориентация, по умолчанию `false`
`deliver`	string	нет	`"inline"` (по умолчанию, байты PDF в ответе) \| `"url"` (нужен настроенный S3, см. ниже)

Ответ 200 OK, Content-Type: application/pdf — бинарное содержимое файла.

Ошибка, например 400 Bad Request:

{ "error": "html is required" }

`POST /v1/convert/url`

Рендерит реальную веб-страницу (вместе с JS и динамическим контентом) в PDF.

curl -X POST https://api.mkpdf.ru/v1/convert/url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "options": { "format": "A4", "landscape": true }
  }' \
  --output page.pdf

Тело запроса такое же, как у /v1/convert/html, но с полем url вместо html. Адрес без схемы (example.com) дополняется до https://. Принимаются только публичные http/https-адреса: localhost, внутренние имена (service, *.local, *.internal) и адреса частных сетей отклоняются с 400. Если страница не загрузилась, вернётся 502 с понятным сообщением — подробности сбоя остаются только в наших логах.

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/convert/office`

Конвертирует офисные документы в PDF через LibreOffice — без установки офисного пакета у себя: .docx/.doc, .xlsx/.xls, .pptx/.ppt, .odt/.ods/.odp, .rtf, .txt, .csv. multipart/form-data, поле file.

curl -X POST https://api.mkpdf.ru/v1/convert/office \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.docx" \
  --output contract.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/merge`

Склеивает 2 и более PDF в один, в порядке загрузки. multipart/form-data, повторяющееся поле files.

curl -X POST https://api.mkpdf.ru/v1/merge \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@part1.pdf" \
  -F "files=@part2.pdf" \
  --output merged.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/convert/image`

Собирает изображения в один PDF — по странице на изображение, в порядке загрузки. multipart/form-data, повторяющееся поле files (до 30 файлов, до 50 МБ суммарно). Форматы: JPG/JPEG, PNG, GIF, BMP, TIFF (WebP не поддерживается).

curl -X POST https://api.mkpdf.ru/v1/convert/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@page1.jpg" \
  -F "files=@page2.png" \
  --output images.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/pdf/to-word`

Конвертирует PDF в редактируемый .docx: обычные абзацы (переносятся при редактировании), шрифты, жирный и курсив, цвет, картинки и позиции табуляции для колонок; сложные таблицы и многоколоночная вёрстка передаются приближённо. multipart/form-data, поле file (PDF до 50 МБ, до 100 страниц). Хорошо работает для PDF с текстовым слоем; у скана текстового слоя нет, и в Word он превратится в набор картинок — сначала распознайте его через /v1/ocr/image.

curl -X POST https://api.mkpdf.ru/v1/pdf/to-word \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf" \
  --output report.docx

Ответ 200 OK, Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document. Имя файла для сохранения — в заголовке Content-Disposition.

`POST /v1/pdf/to-png`

Отрисовывает страницы PDF как PNG. multipart/form-data, поле file (PDF до 50 МБ, до 100 страниц) и необязательное dpi (72–300, по умолчанию 150).

curl -X POST https://api.mkpdf.ru/v1/pdf/to-png \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf" \
  -F "dpi=150" \
  --output pages.zip

Ответ 200 OK. Одна страница — image/png, несколько — application/zip с файлами page-1.png, page-2.png, … в порядке документа.

`POST /v1/pdf/to-jpg`

То же, что /v1/pdf/to-png, но в JPG (качество 90%). Поля: file, необязательное dpi (72–300, по умолчанию 150).

curl -X POST https://api.mkpdf.ru/v1/pdf/to-jpg \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf" \
  --output pages.zip

Ответ 200 OK: image/jpeg для одной страницы или application/zip (page-1.jpg, …) для нескольких.

`POST /v1/pdf/to-html`

Конвертирует PDF в один самодостаточный HTML-файл: текст остаётся текстом, фон и картинки встроены как data:-URI. Элементы позиционируются точно как в PDF (вёрстка не «резиновая»). Поле file (PDF до 50 МБ, до 100 страниц).

curl -X POST https://api.mkpdf.ru/v1/pdf/to-html \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf" \
  --output report.html

Ответ 200 OK, Content-Type: text/html; charset=utf-8.

`POST /v1/pdf/to-text`

Извлекает текст из PDF с сохранением расположения абзацев и колонок (UTF-8). Поле file (PDF до 50 МБ, до 100 страниц). Текст берётся из самого документа — для сканов используйте OCR.

curl -X POST https://api.mkpdf.ru/v1/pdf/to-text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf" \
  --output report.txt

Ответ 200 OK, Content-Type: text/plain; charset=utf-8.

`POST /v1/pdf/split`

Извлекает страницы или режет PDF на части. multipart/form-data, поле file и параметры:

Поле	Значение
`mode`	`pages` (по умолчанию) — извлечь страницы в один PDF; `intervals` — разделить на части
`span`	для `pages` — диапазоны, например `1-3` или `1-3, 7`; для `intervals` — сколько страниц в каждой части (например, `1` — каждая страница отдельным файлом)

curl -X POST https://api.mkpdf.ru/v1/pdf/split \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf" \
  -F "mode=pages" \
  -F "span=1-3" \
  --output pages.pdf

Ответ 200 OK: application/pdf для pages и application/zip для intervals.

`POST /v1/pdf/rotate`

Поворачивает все страницы по часовой стрелке. Поля: file и angle — 90 (по умолчанию), 180 или 270.

curl -X POST https://api.mkpdf.ru/v1/pdf/rotate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@scan.pdf" \
  -F "angle=90" \
  --output rotated.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/pdf/compress`

Уменьшает размер, пересохраняя изображения внутри PDF как JPEG. Текст, векторная графика и шрифты не меняются, поэтому PDF без крупных изображений почти не уменьшится. Поля: file и quality — качество изображений от 10 до 95 (по умолчанию 70).

curl -X POST https://api.mkpdf.ru/v1/pdf/compress \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@big.pdf" \
  -F "quality=60" \
  --output small.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/pdf/protect`

Шифрует PDF: для открытия потребуется пароль. Поля: file и password (1–128 символов). Пароль не сохраняется и не попадает в логи; забытый пароль восстановить нельзя.

curl -X POST https://api.mkpdf.ru/v1/pdf/protect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F "password=s3cret" \
  --output protected.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/pdf/watermark`

Наносит текстовый водяной знак на каждую страницу (поверх содержимого, с прозрачностью — текст под ним остаётся читаемым). Поля: file; text (до 60 символов, латиница и кириллица); opacity от 0.05 до 1 (по умолчанию 0.3); orientation — diagonal (под 45°, по умолчанию), horizontal или vertical; layout — single (одна крупная надпись по центру, по умолчанию) или tiled (много маленьких, мозаикой по всей странице).

curl -X POST https://api.mkpdf.ru/v1/pdf/watermark \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F "text=КОНФИДЕНЦИАЛЬНО" \
  -F "opacity=0.3" \
  -F "orientation=diagonal" \
  -F "layout=tiled" \
  --output watermarked.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/pdf/unlock`

Снимает пароль с PDF, который вы можете открыть. Поля: file и password. Пароль можно не указывать, если файл открывается свободно, но запрещает копирование, печать или редактирование (пароль владельца) — ограничения будут сняты. Сервис не подбирает пароли: с неверным паролем вернётся 422.

curl -X POST https://api.mkpdf.ru/v1/pdf/unlock \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@protected.pdf" \
  -F "password=s3cret" \
  --output unlocked.pdf

Ответ 200 OK, Content-Type: application/pdf. 422 — неверный пароль либо файл не защищён паролем.

`POST /v1/pdf/page-numbers`

Проставляет номера страниц. Поля: file и необязательные параметры:

Поле	Значение
`position`	`bc` (по умолчанию) — снизу по центру; `bl`, `br` — снизу слева/справа; `tc`, `tl`, `tr` — сверху
`format`	`n` (по умолчанию) — `1`; `n_of_total` — `1 / 10`; `page_n` — `Page 1`; `page_n_ru` — `Стр. 1 из 10`; `dash_n` — `- 1 -`
`skip_first`	`true` — не нумеровать первую страницу (нумерация при этом считает её: вторая страница получит `2`)

curl -X POST https://api.mkpdf.ru/v1/pdf/page-numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf" \
  -F "position=br" \
  -F "format=page_n_ru" \
  --output numbered.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/pdf/crop`

Обрезает видимую область каждой страницы. Поля: file и отступы top, right, bottom, left — проценты от размера страницы, 0–90 (по умолчанию 0). Для страниц разного размера отступ считается от размера каждой. Обрезка задаёт область просмотра: содержимое за её пределами остаётся в файле, поэтому она не подходит для удаления конфиденциальной информации — закрашивайте её через /v1/pdf/edit.

curl -X POST https://api.mkpdf.ru/v1/pdf/crop \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@scan.pdf" \
  -F "top=5" -F "bottom=5" -F "left=8" -F "right=8" \
  --output cropped.pdf

Ответ 200 OK, Content-Type: application/pdf.

`POST /v1/pdf/edit`

Накладывает на страницы текст, изображения и цветные прямоугольники — на этом строятся редактор и подпись. Поля: file и ops — JSON-массив элементов (до 300). Координаты и размеры — доли страницы (0–1), начало отсчёта — левый верхний угол; поворот страницы (/Rotate) учитывается.

Ключ	Значение
`type`	`text`, `image` или `rect`
`page`	номер страницы, с единицы
`x`, `y`	левый верхний угол элемента
`w`, `h`	ширина и высота (доли страницы); для `image` высота берётся из пропорций картинки, для `text` не нужны
`text`, `size`, `bold`	для `text`: строка (кириллица поддерживается), размер в пунктах (4–200), жирность
`color`	`#rrggbb`; по умолчанию чёрный (`text`) или жёлтый (`rect`)
`opacity`	`0.05`–`1`, по умолчанию `1`
`image`	для `image`: PNG или JPEG в base64 (допускается префикс `data:...;base64,`), до 8 МБ

curl -X POST https://api.mkpdf.ru/v1/pdf/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F 'ops=[{"type":"text","page":1,"x":0.1,"y":0.9,"text":"Согласовано","size":14,"color":"#0044cc"},{"type":"rect","page":1,"x":0.1,"y":0.2,"w":0.3,"h":0.03,"color":"#000000"}]' \
  --output edited.pdf

Ответ 200 OK, Content-Type: application/pdf. Это графическое наложение, а не электронная подпись: юридическую силу квалифицированной ЭП такая подпись не имеет.

`POST /v1/pdf/to-pdfa`

Приводит PDF к формату долговременного хранения PDF/A. Поля: file и level — 1b, 2b (по умолчанию) или 3b.

curl -X POST https://api.mkpdf.ru/v1/pdf/to-pdfa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "level=2b" \
  --output document-pdfa.pdf

Ответ 200 OK, Content-Type: application/pdf.

Доставка результата: `inline` или `url`

По умолчанию (deliver: "inline", или поле не указано) PDF возвращается прямо в теле ответа. Если на бэкенде настроен S3 (см. .env.example), можно передать "deliver": "url" в /v1/convert/html или /v1/convert/url — тогда вместо бинарного тела вы получите:

{ "url": "https://...", "expires_in": "1h" }

Полезно для больших документов, когда не хочется держать соединение открытым на время рендера.

`POST /v1/ocr/image`

Распознаёт текст на одном изображении — синхронно, лимит 10 МБ. Для многостраничных PDF или файлов больше 10 МБ используйте асинхронный /v1/ocr/document ниже. multipart/form-data, поле file.

curl -X POST https://api.mkpdf.ru/v1/ocr/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@scan.png"

Ответ 200 OK:

{
  "text": "Распознанный текст, строки соединены переводом строки",
  "lines": [
    { "text": "Распознанный текст,", "score": 0.98, "box": [2, 0, 320, 23] }
  ]
}

box — [xMin, yMin, xMax, yMax] в пикселях исходного изображения. Строки, которые движок распознавания разбил на несколько фрагментов (типично для скриншотов кода — разный цвет подсветки синтаксиса создаёт ложную границу детекции), уже склеены в одну логическую строку на бэкенде — см. docs/ocr-product-roadmap.md, «Обновление 6».

`POST /v1/ocr/document`

Распознаёт текст в многостраничном PDF, наборе изображений или файле больше 10 МБ — асинхронно: сразу возвращается job_id, результат нужно забрать через GET /v1/jobs/{id} ниже. Лимит 50 МБ. multipart/form-data, поле file.

curl -X POST https://api.mkpdf.ru/v1/ocr/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract-scan.pdf"

Ответ 202 Accepted:

{ "job_id": "b3f1...", "status": "queued" }

Квота списывается только при успешном завершении задачи (как и у синхронных эндпоинтов) — если распознавание упало с ошибкой, попытка бесплатна.

`GET /v1/jobs/{id}`

Статус и результат задачи, поставленной через /v1/ocr/document.

curl https://api.mkpdf.ru/v1/jobs/b3f1... \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ 200 OK — status один из queued / processing / done / failed:

{
  "id": "b3f1...",
  "status": "done",
  "result": {
    "pages": [
      { "page": 1, "text": "...", "lines": [{ "text": "...", "score": 0.97, "box": [0, 0, 100, 20] }] }
    ]
  }
}

При "status": "failed" вместо result придёт "error": "...". Задача, которую запросил другой аккаунт (или несуществующий id), возвращает 404, а не деталь чужой задачи.

Rate limits и квоты

Rate limit: 5 запросов/сек, всплеск до 20, на один API-ключ — не зависит от тарифа.
Месячная квота: общая на все ключи в аккаунте (см. GET /dashboard/usage). Каждый ответ несёт заголовки X-RateLimit-Limit / X-RateLimit-Remaining для текущего периода.
В квоту засчитывается только успешная конвертация — ошибка на стороне движка или невалидный запрос ничего не списывают. Для /v1/ocr/document это же правило применяется в момент завершения задачи, а не постановки в очередь.

Ошибки

{ "error": "человекочитаемое сообщение" }

Соответствующий HTTP-статус: 400 — некорректный запрос или параметры, 401 — неверный/отсутствующий API-ключ, 413 — в PDF слишком много страниц (максимум 100 для конвертации, 500 для правок), 422 — PDF защищён паролем, повреждён либо неверен пароль для /v1/pdf/unlock, 429 — превышен rate limit или квота, 502 — сбой на стороне движка, 503 — инструмент временно недоступен.

Текст в поле error рассчитан на человека и может меняться — ориентируйтесь на HTTP-статус.

Эта страница собирается из docs/api.md в репозитории проекта — правки туда сразу попадают на сайт после деплоя.

Документация API

Справочник API

Резервный хост

Postman

Быстрый старт

POST /v1/convert/html

POST /v1/convert/url

POST /v1/convert/office

POST /v1/merge

POST /v1/convert/image

POST /v1/pdf/to-word

POST /v1/pdf/to-png

POST /v1/pdf/to-jpg

POST /v1/pdf/to-html

POST /v1/pdf/to-text

POST /v1/pdf/split

POST /v1/pdf/rotate

POST /v1/pdf/compress

POST /v1/pdf/protect

POST /v1/pdf/watermark

POST /v1/pdf/unlock

POST /v1/pdf/page-numbers

POST /v1/pdf/crop

POST /v1/pdf/edit

POST /v1/pdf/to-pdfa

Доставка результата: inline или url

POST /v1/ocr/image

POST /v1/ocr/document

GET /v1/jobs/{id}

Rate limits и квоты

Ошибки

`POST /v1/convert/html`

`POST /v1/convert/url`

`POST /v1/convert/office`

`POST /v1/merge`

`POST /v1/convert/image`

`POST /v1/pdf/to-word`

`POST /v1/pdf/to-png`

`POST /v1/pdf/to-jpg`

`POST /v1/pdf/to-html`

`POST /v1/pdf/to-text`

`POST /v1/pdf/split`

`POST /v1/pdf/rotate`

`POST /v1/pdf/compress`

`POST /v1/pdf/protect`

`POST /v1/pdf/watermark`

`POST /v1/pdf/unlock`

`POST /v1/pdf/page-numbers`

`POST /v1/pdf/crop`

`POST /v1/pdf/edit`

`POST /v1/pdf/to-pdfa`

Доставка результата: `inline` или `url`

`POST /v1/ocr/image`

`POST /v1/ocr/document`

`GET /v1/jobs/{id}`