JSON to PDF API for structured document generation
Turn structured JSON DocumentRequest payloads into PDFs with pages, coordinates, text, tables, barcodes, metadata, and PDF/A settings.
/api/v1/pdf/render Convert structured application data into deterministic PDF documents without running a browser, shipping HTML/CSS, or storing customer files. Your system sends pages, elements, coordinates, settings, and business content; gPdf returns an application/pdf response.
When to use this API
- Your backend already has structured data and needs a PDF response.
- You want explicit pages, coordinates, elements, barcodes, and settings instead of HTML layout.
- You need repeatable output for invoices, labels, reports, statements, or generated packets.
- You want to test payloads in the Playground before putting a token in production.
What it does not replace
- You need arbitrary HTML-to-PDF conversion. gPdf uses DocumentRequest JSON, not a browser DOM.
- Your team wants a stable template_id contract. Use Template Render after the layout is published.
- You need Factur-X or ZUGFeRD e-invoice packaging. Use the E-Invoice Render endpoint.
Which endpoint to call
/api/v1/pdf/render
JSON Render is the default path for this workflow.
/api/v1/template-render
Use this when the workflow needs the related API path, template contract, or capabilities lookup.
Minimal request
POST /api/v1/pdf/render - one-page JSON DocumentRequest.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
What gPdf handles
- DocumentRequest rendering from pages and elements.
- Text, tables, images, vector barcodes, lines, shapes, watermarks, metadata, and PDF/A settings.
- Font embedding and fallback for Latin, CJK, emoji-capable, and other supported scripts.
- Binary PDF response with the shared gPdf error-code envelope on failure.
What your system owns
- Business data, field mapping, and document semantics.
- Request IDs, retry and idempotency strategy, file naming, and storage after response.
- Any tax, invoice, carrier, compliance, or customer-specific rules before rendering.
Production checklist
- Generate and pass an X-Request-Id for traceability.
- Validate payloads against the OpenAPI or docs before sending live traffic.
- Keep the API base URL configurable and store the bearer token outside source code.
- Decide whether your output should be inline or attachment mode.
- Add golden-PDF tests for critical layouts so template or data changes are visible.
Claim boundaries
- This is not HTML-to-PDF and does not run Chromium.
- The API renders the document you describe; it does not infer legal or business meaning from your data.
- For repeated layouts, Template Render is usually the better public contract.
How the JSON Render workflow fits
JSON Render is the lowest-level public rendering path. Your application sends the document structure directly: page size, elements, coordinates, styling, metadata, output mode, and optional PDF/A settings. This is the right layer when the document layout is generated by code or when your team wants pixel-level control over the PDF.
The API contract is explicit. If your system sends a text element, gPdf renders a text element. If it sends a barcode element, gPdf draws the barcode as vector PDF content. gPdf does not read business intent from the payload and does not decide whether an invoice number, carrier tracking value, or tax field is correct.
When to switch to Template Render
If the same layout is used repeatedly across systems, publish it as a template
and call POST /api/v1/template-render with template_id plus data[]. That
moves layout ownership out of every caller and gives your ERP, OMS, WMS, or SaaS
backend a stable field contract.
Use JSON Render for layout creation, one-off documents, and programmatic documents. Use Template Render when the layout is fixed and the only thing that changes per request is business data.
Production shape
In production, treat a PDF request like any other important API call: include a request ID, set a timeout, make retries idempotent, log the response metadata, and store the returned PDF only in your own system if retention is required. The gPdf render path is stateless after a standard render response.
FAQ
- Is this a HTML-to-PDF API?
- No. gPdf accepts a structured JSON DocumentRequest with pages, elements, coordinates, and settings. It does not run a browser or execute arbitrary HTML/CSS.
- Which endpoint should I call first?
- Start with POST /api/v1/pdf/render when you want direct control of the layout. Move to POST /api/v1/template-render when the layout should become a stable template_id contract.
- Does the API return a PDF directly?
- Yes. A successful render returns application/pdf. Errors use the shared JSON error envelope with an API-XXX code and req_id.
- Can I test without building an integration?
- Use the gPdf Playground to test JSON payloads interactively, then move the same DocumentRequest shape into your backend client.