Это HTML-to-PDF API?

Нет. gPdf принимает structured JSON DocumentRequest со страницами, elements, coordinates и settings. Он не запускает браузер и не выполняет arbitrary HTML/CSS.

Какой endpoint вызвать первым?

Начните с POST /api/v1/pdf/render, если нужен прямой контроль layout. Переходите на POST /api/v1/template-render, когда layout должен стать стабильным контрактом `template_id`.

Возвращает ли API PDF напрямую?

Да. Успешный render возвращает application/pdf. Ошибки используют общий JSON error envelope с API-XXX code и req_id.

Можно ли протестировать без интеграции?

Используйте gPdf Playground для интерактивного тестирования JSON payloads, затем перенесите ту же форму DocumentRequest в backend client.

Рабочие процессы разработчиков

JSON to PDF API для structured document generation

Преобразуйте structured JSON DocumentRequest payloads в PDF: страницы, координаты, текст, таблицы, штрихкоды, metadata и PDF/A settings.

ОСНОВНАЯ API JSON Render

ENDPOINT /api/v1/pdf/render

СИСТЕМЫ SaaS backend / API worker / AI agent / job queue

Попробовать в Playground Читать документацию

Задача сценария

Преобразовывать structured application data в детерминированные PDF documents без браузера, HTML/CSS и хранения customer files. Ваша система отправляет pages, elements, coordinates, settings и business content; gPdf возвращает response application/pdf.

Когда использовать эту API

Ваш backend уже содержит structured data и ему нужен PDF response.
Нужны явные pages, coordinates, elements, barcodes и settings вместо HTML layout.
Нужен repeatable output для invoices, labels, reports, statements или generated packets.
Вы хотите протестировать payloads в Playground перед production token.

Что она не заменяет

Нужно arbitrary HTML-to-PDF conversion. gPdf использует DocumentRequest JSON, а не browser DOM.
Команде нужен стабильный контракт `template_id`. Используйте Template Render после публикации layout.
Нужен Factur-X или ZUGFeRD e-invoice packaging. Используйте E-Invoice Render endpoint.

Какой endpoint вызывать

ОСНОВНОЙ

/api/v1/pdf/render

JSON Render — путь по умолчанию для этого сценария.

ДОПОЛНИТЕЛЬНЫЙ 1

/api/v1/template-render

Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.

Минимальный запрос

POST /api/v1/pdf/render - одностраничный JSON DocumentRequest.

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Hello from gPdf",
          "style": {
            "font_size": 18,
            "font_family": "NotoSans-Regular"
          }
        }
      ]
    }
  ]
}

Что выполняет gPdf

DocumentRequest rendering из pages и elements.
Text, tables, images, vector barcodes, lines, shapes, watermarks, metadata и PDF/A settings.
Font embedding и fallback для Latin, CJK, emoji-capable и других supported scripts.
Binary PDF response и общий gPdf error-code envelope при failure.

Что контролирует ваша система

Business data, field mapping и document semantics.
Request IDs, retry и idempotency strategy, file naming и storage после response.
Любые tax, invoice, carrier, compliance или customer-specific rules до rendering.

Production-чеклист

Генерируйте и передавайте X-Request-Id для traceability.
Валидируйте payloads по OpenAPI или docs перед live traffic.
Держите API base URL configurable и храните bearer token вне source code.
Решите, должен ли output быть inline или attachment mode.
Добавьте golden-PDF tests для критичных layouts, чтобы изменения template или data были видимы.

Границы заявлений

Это не HTML-to-PDF и здесь не запускается Chromium.
API рендерит документ, который вы описали; он не выводит legal или business meaning из ваших данных.
Для повторяемых layouts Template Render обычно является лучшим public contract.

Как работает JSON Render workflow

JSON Render — самый низкоуровневый публичный путь рендеринга. Ваше приложение отправляет структуру документа напрямую: page size, elements, coordinates, styling, metadata, output mode и опциональные PDF/A settings. Это правильный слой, когда layout документа генерируется кодом или когда команде нужен pixel-level control над PDF.

API contract явный. Если ваша система отправляет text element, gPdf рендерит text element. Если отправляет barcode element, gPdf рисует штрихкод как vector PDF content. gPdf не считывает business intent из payload и не решает, корректны ли invoice number, carrier tracking value или tax field.

Когда переходить на Template Render

Если один и тот же layout многократно используется разными системами, опубликуйте его как template и вызывайте POST /api/v1/template-render с template_id плюс data[]. Это выводит layout ownership из каждого caller и дает ERP, OMS, WMS или SaaS backend стабильный field contract.

Используйте JSON Render для создания layout, one-off documents и programmatic documents. Используйте Template Render, когда layout зафиксирован, а от request к request меняются только business data.

Production shape

В production относитесь к PDF request как к любому важному API call: передавайте request ID, задавайте timeout, делайте retries идемпотентными, логируйте response metadata и храните returned PDF только в своей системе, если нужна retention. Стандартный render path gPdf после response stateless.

FAQ

Это HTML-to-PDF API?: Нет. gPdf принимает structured JSON DocumentRequest со страницами, elements, coordinates и settings. Он не запускает браузер и не выполняет arbitrary HTML/CSS.
Какой endpoint вызвать первым?: Начните с POST /api/v1/pdf/render, если нужен прямой контроль layout. Переходите на POST /api/v1/template-render, когда layout должен стать стабильным контрактом `template_id`.
Возвращает ли API PDF напрямую?: Да. Успешный render возвращает application/pdf. Ошибки используют общий JSON error envelope с API-XXX code и req_id.
Можно ли протестировать без интеграции?: Используйте gPdf Playground для интерактивного тестирования JSON payloads, затем перенесите ту же форму DocumentRequest в backend client.