এটি কি HTML-to-PDF API?

না। gPdf page, element, coordinate এবং setting-সহ structured JSON DocumentRequest গ্রহণ করে। এটি browser চালায় না বা arbitrary HTML/CSS execute করে না।

প্রথমে কোন endpoint call করব?

Layout-এর ওপর সরাসরি control চাইলে POST /api/v1/pdf/render দিয়ে শুরু করুন। Layout stable template_id contract হওয়া দরকার হলে POST /api/v1/template-render-এ যান।

API কি সরাসরি PDF return করে?

হ্যাঁ। Successful render application/pdf return করে। Error হলে API-XXX code এবং req_id-সহ shared JSON error envelope ব্যবহার হয়।

Integration বানানো ছাড়াই কি test করা যায়?

gPdf Playground-এ JSON payload interactively test করুন, তারপর একই DocumentRequest shape আপনার backend client-এ নিয়ে যান।

Developer workflow

Structured document generation-এর জন্য JSON থেকে PDF API

Structured JSON DocumentRequest payload থেকে page, coordinate, text, table, barcode, metadata এবং PDF/A setting-সহ PDF তৈরি করুন।

প্রাথমিক API JSON Render

Endpoint /api/v1/pdf/render

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

Playground-এ পরীক্ষা করুন Docs পড়ুন

যে কাজটি করতে হবে

Browser চালানো, HTML/CSS পাঠানো বা customer file সংরক্ষণ ছাড়াই structured application data-কে deterministic PDF document-এ রূপান্তর করুন। আপনার system page, element, coordinate, setting এবং business content পাঠায়; gPdf application/pdf response ফেরত দেয়।

কখন এই API ব্যবহার করবেন

আপনার backend-এ আগে থেকেই structured data আছে এবং PDF response দরকার।
HTML layout-এর বদলে explicit page, coordinate, element, barcode এবং setting চান।
ইনভয়েস, লেবেল, রিপোর্ট, স্টেটমেন্ট বা generated packet-এর জন্য repeatable output দরকার।
Production token ব্যবহারের আগে Playground-এ payload পরীক্ষা করতে চান।

এটি কী replace করে না

আপনার arbitrary HTML-to-PDF conversion দরকার। gPdf browser DOM নয়, DocumentRequest JSON ব্যবহার করে।
আপনার team stable template_id contract চায়। Layout publish হওয়ার পরে Template Render ব্যবহার করুন।
Factur-X বা ZUGFeRD e-invoice packaging দরকার। E-Invoice Render endpoint ব্যবহার করুন।

কোন endpoint call করবেন

প্রাথমিক

/api/v1/pdf/render

JSON Render এই workflow-এর default path।

সহায়ক 1

/api/v1/template-render

Workflow-তে related API path, template contract অথবা capabilities lookup দরকার হলে ব্যবহার করুন।

নূন্যতম request

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 কী করে

Page ও element থেকে DocumentRequest rendering।
Text, table, image, vector barcode, line, shape, watermark, metadata এবং PDF/A setting।
Latin, CJK, emoji-capable এবং অন্যান্য supported script-এর জন্য font embedding ও fallback।
Successful render-এ binary PDF response; failure হলে shared gPdf error-code envelope।

আপনার system-এর দায়িত্ব

Business data, field mapping এবং document semantics।
Request ID, retry ও idempotency strategy, file naming এবং response-এর পরে storage।
Rendering-এর আগে tax, invoice, carrier, compliance বা customer-specific rule।

Production checklist

Traceability-এর জন্য X-Request-Id generate করে পাঠান।
Live traffic পাঠানোর আগে OpenAPI বা docs-এর against payload validate করুন।
API base URL configurable রাখুন এবং bearer token source code-এর বাইরে সংরক্ষণ করুন।
Output inline হবে নাকি attachment mode-এ যাবে তা ঠিক করুন।
Critical layout-এর জন্য golden-PDF test যোগ করুন, যাতে template বা data change দৃশ্যমান হয়।

দাবির সীমা

এটি HTML-to-PDF নয় এবং Chromium চালায় না।
API আপনার বর্ণনা করা document render করে; data থেকে legal বা business meaning অনুমান করে না।
Repeated layout-এর জন্য Template Render সাধারণত ভালো public contract।

JSON Render workflow কোথায় মানায়

JSON Render হলো public rendering path-এর সবচেয়ে low-level layer। আপনার application সরাসরি document structure পাঠায়: page size, element, coordinate, styling, metadata, output mode এবং optional PDF/A setting। Document layout যদি code দিয়ে তৈরি হয়, অথবা team যদি PDF-এর ওপর pixel-level control চায়, এই layer সেই কাজের জন্য ঠিক।

API contract স্পষ্ট। আপনার system text element পাঠালে gPdf text element render করে। Barcode element পাঠালে gPdf সেটি vector PDF content হিসেবে আঁকে। Payload থেকে gPdf business intent পড়ে না, এবং invoice number, carrier tracking value বা tax field সঠিক কি না তা সিদ্ধান্ত নেয় না।

কখন Template Render-এ যাবেন

একই layout যদি বারবার একাধিক system-এ ব্যবহার হয়, সেটি 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 document এবং programmatic document-এর জন্য JSON Render ব্যবহার করুন। Layout fixed হয়ে গেলে এবং প্রতি request-এ শুধু business data বদলালে Template Render ব্যবহার করুন।

Production shape

Production-এ PDF request-কে অন্য গুরুত্বপূর্ণ API call-এর মতো treat করুন: request ID include করুন, timeout সেট করুন, retry idempotent করুন, response metadata log করুন, এবং retention দরকার হলে returned PDF শুধু আপনার নিজের system-এ store করুন। Standard render response-এর পরে gPdf render path stateless থাকে।

FAQ

এটি কি HTML-to-PDF API?: না। gPdf page, element, coordinate এবং setting-সহ structured JSON DocumentRequest গ্রহণ করে। এটি browser চালায় না বা arbitrary HTML/CSS execute করে না।
প্রথমে কোন endpoint call করব?: Layout-এর ওপর সরাসরি control চাইলে POST /api/v1/pdf/render দিয়ে শুরু করুন। Layout stable template_id contract হওয়া দরকার হলে POST /api/v1/template-render-এ যান।
API কি সরাসরি PDF return করে?: হ্যাঁ। Successful render application/pdf return করে। Error হলে API-XXX code এবং req_id-সহ shared JSON error envelope ব্যবহার হয়।
Integration বানানো ছাড়াই কি test করা যায়?: gPdf Playground-এ JSON payload interactively test করুন, তারপর একই DocumentRequest shape আপনার backend client-এ নিয়ে যান।