API Reference

Base URL:

https://api.mkpdf.ru

/v1/*

Authorization: Bearer <api key>

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

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

Тело запроса

html

options.format

A4

Letter

Legal

options.margin

"16mm"

"1in"

"2cm"

options.landscape

false

deliver

"inline"

"url"

Ответ

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

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"

.env.example

"deliver": "url"

/v1/convert/html

/v1/convert/url

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

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

Rate limits и квоты

• Rate limit: 5 запросов/сек, всплеск до 20, на один API-ключ — не зависит от тарифа.
• Месячная квота: общая на все ключи в аккаунте (см.

  GET /dashboard/usage

  ). Каждый ответ несёт заголовки

  X-RateLimit-Limit

  /

  X-RateLimit-Remaining

  для текущего периода.
• В квоту засчитывается только успешная конвертация — ошибка на стороне движка или невалидный запрос ничего не списывают.

Ошибки

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

Соответствующий HTTP-статус:

400

401

429

502