क्या यह HTML-to-PDF API है?

नहीं. gPdf pages, elements, coordinates और settings वाला structured JSON DocumentRequest स्वीकार करता है. यह browser नहीं चलाता और arbitrary HTML/CSS execute नहीं करता.

सबसे पहले कौन सा endpoint call करना चाहिए?

जब layout पर direct control चाहिए, तो POST /api/v1/pdf/render से शुरू करें. जब layout stable template_id contract बनना चाहिए, तो POST /api/v1/template-render पर जाएं.

क्या API सीधे PDF लौटाती है?

हाँ. Successful render application/pdf लौटाता है. Errors shared JSON error envelope में API-XXX code और req_id के साथ आते हैं.

क्या integration बनाए बिना test कर सकता हूँ?

JSON payloads को interactively test करने के लिए gPdf Playground use करें, फिर वही DocumentRequest shape अपने backend client में ले जाएं.

Developer workflows

Structured document generation के लिए JSON से PDF API

Structured JSON DocumentRequest payloads को pages, coordinates, text, tables, barcodes, metadata और PDF/A settings वाले PDF में बदलें.

PRIMARY API JSON Render

ENDPOINT /api/v1/pdf/render

SYSTEMS SaaS backend / API worker / AI agent / job queue

Playground में आज़माएँ Docs पढ़ें

काम जो पूरा करना है

Structured application data को deterministic PDF documents में बदलें, बिना browser चलाए, HTML/CSS भेजे या customer files store किए. आपका system pages, elements, coordinates, settings और business content भेजता है; gPdf application/pdf response लौटाता है.

यह API कब इस्तेमाल करें

आपके backend में structured data पहले से है और PDF response चाहिए.
आप HTML layout के बजाय explicit pages, coordinates, elements, barcodes और settings चाहते हैं.
Invoices, labels, reports, statements या generated packets के लिए repeatable output चाहिए.
Production token लगाने से पहले payloads को Playground में test करना है.

यह क्या replace नहीं करता

आपको arbitrary HTML-to-PDF conversion चाहिए. gPdf DocumentRequest JSON use करता है, browser DOM नहीं.
आपकी team stable template_id contract चाहती है. Layout publish होने के बाद Template Render use करें.
आपको Factur-X या ZUGFeRD e-invoice packaging चाहिए. E-Invoice Render endpoint use करें.

कौन सा endpoint call करें

PRIMARY

/api/v1/pdf/render

JSON Render इस workflow का default path है।

SECONDARY 1

/api/v1/template-render

जब workflow को related API path, template contract या 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"
          }
        }
      ]
    }
  ]
}

gPdf क्या handle करता है

Pages और elements से DocumentRequest rendering.
Text, tables, images, vector barcodes, lines, shapes, watermarks, metadata और PDF/A settings.
Latin, CJK, emoji-capable और अन्य supported scripts के लिए font embedding और fallback.
Failure पर shared gPdf error-code envelope के साथ binary PDF response behavior.

आपका system क्या संभालता है

Business data, field mapping और document semantics.
Request IDs, retry और idempotency strategy, file naming और response के बाद storage.
Rendering से पहले tax, invoice, carrier, compliance या customer-specific rules.

Production checklist

Traceability के लिए X-Request-Id generate और pass करें.
Live traffic भेजने से पहले payloads को OpenAPI या docs के against validate करें.
API base URL configurable रखें और bearer token को source code से बाहर store करें.
तय करें कि output inline mode में चाहिए या attachment mode में.
Critical layouts के लिए golden-PDF tests जोड़ें, ताकि template या data changes visible रहें.

Claim boundaries

यह HTML-to-PDF नहीं है और Chromium नहीं चलाता.
API वही document render करती है जिसे आप describe करते हैं; यह आपके data से legal या business meaning infer नहीं करती.
Repeated layouts के लिए Template Render आम तौर पर बेहतर public contract है.

JSON Render workflow कैसे fit होता है

JSON Render सबसे low-level public rendering path है. आपकी application document structure सीधे भेजती है: page size, elements, coordinates, styling, metadata, output mode और optional PDF/A settings. यह layer तब सही है जब document layout code से generate होता है या आपकी team PDF पर pixel-level control चाहती है.

API contract explicit है. अगर आपका system text element भेजता है, gPdf text element render करता है. अगर वह barcode element भेजता है, gPdf barcode को vector PDF content के रूप में draw करता है. gPdf payload से business intent नहीं पढ़ता और यह decide नहीं करता कि invoice number, carrier tracking value या tax field सही है या नहीं.

Template Render पर कब switch करें

अगर same layout कई systems में बार-बार use होता है, तो उसे template के रूप में publish करें और template_id plus data[] के साथ POST /api/v1/template-render call करें. इससे layout ownership हर caller से हटती है और आपके ERP, OMS, WMS या SaaS backend को stable field contract मिलता है.

Layout creation, one-off documents और programmatic documents के लिए JSON Render use करें. जब layout fixed हो और हर request में सिर्फ business data बदलता हो, तब Template Render use करें.

Production shape

Production में PDF request को किसी भी important API call की तरह treat करें: request ID include करें, timeout set करें, retries idempotent बनाएं, response metadata log करें और returned PDF को केवल अपने system में store करें अगर retention required हो. Standard render response के बाद gPdf render path stateless रहता है.

FAQ

क्या यह HTML-to-PDF API है?: नहीं. gPdf pages, elements, coordinates और settings वाला structured JSON DocumentRequest स्वीकार करता है. यह browser नहीं चलाता और arbitrary HTML/CSS execute नहीं करता.
सबसे पहले कौन सा endpoint call करना चाहिए?: जब layout पर direct control चाहिए, तो POST /api/v1/pdf/render से शुरू करें. जब layout stable template_id contract बनना चाहिए, तो POST /api/v1/template-render पर जाएं.
क्या API सीधे PDF लौटाती है?: हाँ. Successful render application/pdf लौटाता है. Errors shared JSON error envelope में API-XXX code और req_id के साथ आते हैं.
क्या integration बनाए बिना test कर सकता हूँ?: JSON payloads को interactively test करने के लिए gPdf Playground use करें, फिर वही DocumentRequest shape अपने backend client में ले जाएं.