Is dit een HTML-naar-PDF-API?

Nee. gPdf accepteert een gestructureerde JSON DocumentRequest met pagina's, elementen, coördinaten en instellingen. Het draait geen browser en voert geen willekeurige HTML/CSS uit.

Welk endpoint moet ik eerst aanroepen?

Begin met POST /api/v1/pdf/render wanneer u directe controle over de lay-out wilt. Stap over op POST /api/v1/template-render wanneer de lay-out een stabiel `template_id`-contract moet worden.

Retourneert de API direct een PDF?

Ja. Een succesvolle render retourneert application/pdf. Fouten gebruiken de gedeelde JSON-foutenvelop met een API-XXX-code en req_id.

Kan ik testen zonder integratie te bouwen?

Gebruik de gPdf Playground om JSON-requestdata interactief te testen en verplaats daarna dezelfde DocumentRequest-vorm naar uw backendclient.

Developer-workflows

JSON-naar-PDF-API voor gestructureerde documentgeneratie

Zet gestructureerde JSON DocumentRequest-data om naar PDF's met pagina's, coördinaten, tekst, tabellen, barcodes, metadata en PDF/A-instellingen.

PRIMAIRE API JSON Render

ENDPOINT /api/v1/pdf/render

SYSTEMEN SaaS-backend / API-worker / AI-agent / jobqueue

Testen in Playground Documentatie lezen

Taak om op te lossen

Zet gestructureerde applicatiedata om naar deterministische PDF-documenten zonder browser, zonder HTML/CSS te verschepen en zonder klantbestanden op te slaan. Uw systeem stuurt pagina's, elementen, coördinaten, instellingen en bedrijfsinhoud; gPdf retourneert een application/pdf-respons.

Wanneer deze API past

Uw backend heeft al gestructureerde data en heeft een PDF-respons nodig.
U wilt expliciete pagina's, coördinaten, elementen, barcodes en instellingen in plaats van HTML-layout.
U hebt herhaalbare output nodig voor facturen, etiketten, rapporten, overzichten of gegenereerde pakketten.
U wilt requestdata in de Playground testen voordat u een token in productie gebruikt.

Wat dit niet vervangt

U hebt willekeurige HTML-naar-PDF-conversie nodig. gPdf gebruikt DocumentRequest JSON, geen browser-DOM.
Uw team wil een stabiel `template_id`-contract. Gebruik Template Render nadat de lay-out is gepubliceerd.
U hebt Factur-X- of ZUGFeRD-E-Invoice-packaging nodig. Gebruik het E-Invoice Render-endpoint.

Welk endpoint aanroepen

PRIMAIR

/api/v1/pdf/render

JSON Render is het standaardpad voor deze workflow.

SECUNDAIR 1

/api/v1/template-render

Gebruik dit wanneer de workflow een verwant API-pad, templatecontract of capability lookup nodig heeft.

Minimale request

POST /api/v1/pdf/render - JSON DocumentRequest met één pagina.

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

Wat gPdf afhandelt

DocumentRequest-rendering vanuit pagina's en elementen.
Tekst, tabellen, afbeeldingen, vectorbarcodes, lijnen, vormen, watermerken, metadata en PDF/A-instellingen.
Fontembedding en fallback voor Latijn, CJK, emoji-geschikte en andere ondersteunde scripts.
Binaire PDF-respons met de gedeelde gPdf-foutcode-envelop bij fouten.

Wat uw systeem beheert

Bedrijfsdata, veldmapping en documentsemantiek.
Request-ID's, retry- en idempotentiestrategie, bestandsnaamgeving en opslag na de respons.
Belasting-, factuur-, vervoerder-, nalevings- of klantspecifieke regels vóór rendering.

Productiechecklist

Genereer en stuur een X-Request-Id mee voor traceerbaarheid.
Valideer requestdata tegen OpenAPI of documentatie voordat u live verkeer verstuurt.
Houd de API-base-URL configureerbaar en bewaar het bearer token buiten broncode.
Bepaal of uw output inline of als bijlage moet worden geleverd.
Voeg golden-PDF-tests toe voor kritieke lay-outs, zodat template- of datawijzigingen zichtbaar zijn.

Grenzen van de claim

Dit is geen HTML-naar-PDF en draait geen Chromium.
De API rendert het document dat u beschrijft; hij leidt geen juridische of zakelijke betekenis af uit uw data.
Voor herhaalde lay-outs is Template Render meestal het betere publieke contract.

Hoe het JSON Render-proces past

JSON Render is het laagste publieke renderpad. Uw applicatie stuurt de documentstructuur direct: paginaformaat, elementen, coördinaten, styling, metadata, outputmodus en optionele PDF/A-instellingen. Dit is de juiste laag wanneer de documentlay-out door code wordt gegenereerd of wanneer uw team pixelnauwkeurige controle over de PDF wil.

Het API-contract is expliciet. Als uw systeem een tekstelement stuurt, rendert gPdf een tekstelement. Als het een barcode-element stuurt, tekent gPdf de barcode als vector-PDF-inhoud. gPdf leest geen zakelijke intentie uit de requestdata en bepaalt niet of een factuurnummer, trackingwaarde van een vervoerder of belastingveld correct is.

Wanneer overstappen op Template Render

Als dezelfde lay-out herhaaldelijk door meerdere systemen wordt gebruikt, publiceer deze dan als sjabloon en roep POST /api/v1/template-render aan met template_id plus data[]. Zo verschuift lay-outbeheer uit elk aanroepend systeem en krijgt uw ERP, OMS, WMS of SaaS-backend een stabiel veldcontract.

Gebruik JSON Render voor het maken van lay-outs, eenmalige documenten en programmatisch gegenereerde documenten. Gebruik Template Render wanneer de lay-out vaststaat en per request alleen bedrijfsdata verandert.

Productievorm

Behandel een PDF-request in productie als elke andere belangrijke API-aanroep: voeg een request-ID toe, stel een timeout in, maak retries idempotent, log de responsmetadata en sla de geretourneerde PDF alleen in uw eigen systeem op als bewaring vereist is. Het gPdf-renderpad is stateless na een standaard renderrespons.

FAQ

Is dit een HTML-naar-PDF-API?: Nee. gPdf accepteert een gestructureerde JSON DocumentRequest met pagina's, elementen, coördinaten en instellingen. Het draait geen browser en voert geen willekeurige HTML/CSS uit.
Welk endpoint moet ik eerst aanroepen?: Begin met POST /api/v1/pdf/render wanneer u directe controle over de lay-out wilt. Stap over op POST /api/v1/template-render wanneer de lay-out een stabiel `template_id`-contract moet worden.
Retourneert de API direct een PDF?: Ja. Een succesvolle render retourneert application/pdf. Fouten gebruiken de gedeelde JSON-foutenvelop met een API-XXX-code en req_id.
Kan ik testen zonder integratie te bouwen?: Gebruik de gPdf Playground om JSON-requestdata interactief te testen en verplaats daarna dezelfde DocumentRequest-vorm naar uw backendclient.