API Reference

Base URL: https://api.mkpdf.ru. Every /v1/* request requires Authorization: Bearer <api key> (create one in the dashboard). Only the monthly quota charges for a request — a failed conversion (bad input, engine error) never counts against it.

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

1. Зарегистрируйтесь и создайте API-ключ в личном кабинете.
2. Отправьте запрос на нужный эндпоинт с заголовком Authorization: Bearer <ваш ключ>.
3. Получите готовый 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

Тело запроса

Ответ 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.

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

POST /v1/convert/office

Конвертирует .docx/.xlsx/.pptx в PDF через LibreOffice — без установки офисного пакета у себя. 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.

Доставка результата: 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-ключ, 429 — превышен rate limit или квота, 502 — сбой на стороне движка рендеринга.