นี่คือ HTML-to-PDF API หรือไม่

ไม่ gPdf รับ structured JSON DocumentRequest ที่มี pages, elements, coordinates และ settings ไม่รัน browser และไม่ execute arbitrary HTML/CSS

ควรเรียก endpoint ไหนก่อน

เริ่มด้วย POST /api/v1/pdf/render เมื่อคุณต้องการควบคุม layout โดยตรง ย้ายไป POST /api/v1/template-render เมื่อ layout ควรกลายเป็น contract แบบ template_id ที่เสถียร

API ส่ง PDF กลับโดยตรงหรือไม่

ใช่ render ที่สำเร็จจะส่ง application/pdf กลับมา ส่วน errors ใช้ JSON error envelope ร่วมที่มี API-XXX code และ req_id

ทดสอบโดยไม่ build integration ได้ไหม

ใช้ gPdf Playground เพื่อทดสอบ JSON payloads แบบ interactive จากนั้นย้าย shape ของ DocumentRequest เดิมเข้า backend client ของคุณ

เวิร์กโฟลว์สำหรับนักพัฒนา

JSON to PDF API สำหรับการสร้างเอกสารแบบ structured

แปลง structured JSON DocumentRequest payload เป็น PDF พร้อม pages, coordinates, text, tables, barcodes, metadata และ PDF/A settings

PRIMARY API JSON Render

ENDPOINT /api/v1/pdf/render

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

ลองใน Playground อ่านเอกสาร

งานที่ต้องทำให้เสร็จ

แปลง structured application data เป็นเอกสาร PDF ที่ deterministic โดยไม่ต้องรัน browser ไม่ต้องส่ง HTML/CSS และไม่ต้องเก็บไฟล์ลูกค้า ระบบของคุณส่ง pages, elements, coordinates, settings และ business content; gPdf ส่งกลับ application/pdf response

ควรใช้ API นี้เมื่อใด

backend ของคุณมี structured data อยู่แล้วและต้องการ PDF response
คุณต้องการ pages, coordinates, elements, barcodes และ settings ที่ explicit แทน HTML layout
คุณต้องการ output ที่ repeat ได้สำหรับ invoices, labels, reports, statements หรือ generated packets
คุณต้องการทดสอบ payloads ใน Playground ก่อนนำ token ไปใช้ใน production

สิ่งที่ไม่ได้ทดแทน

คุณต้องการ arbitrary HTML-to-PDF conversion gPdf ใช้ DocumentRequest JSON ไม่ใช่ browser DOM
ทีมของคุณต้องการ contract แบบ template_id ที่เสถียร ให้ใช้ Template Render หลังจาก layout ถูก publish
คุณต้องการ Factur-X หรือ ZUGFeRD e-invoice packaging ให้ใช้ E-Invoice Render endpoint

ควรเรียก endpoint ใด

PRIMARY

/api/v1/pdf/render

JSON Render คือ path หลักสำหรับเวิร์กโฟลว์นี้.

SECONDARY 1

/api/v1/template-render

ใช้เมื่อเวิร์กโฟลว์ต้องการ API path ที่เกี่ยวข้อง สัญญาเทมเพลต หรือการค้นหา capability.

Minimal 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 จัดการอะไร

การเรนเดอร์ DocumentRequest จาก pages และ elements
text, tables, images, vector barcodes, lines, shapes, watermarks, metadata และ PDF/A settings
font embedding และ fallback สำหรับ Latin, CJK, emoji-capable และ scripts อื่นที่รองรับ
binary PDF response พร้อม error-code envelope ร่วมของ gPdf เมื่อเกิด failure

ระบบของคุณรับผิดชอบอะไร

business data, field mapping และ document semantics
request IDs, retry และ idempotency strategy, file naming และ storage หลัง response
กฎ tax, invoice, carrier, compliance หรือ customer-specific ใด ๆ ก่อน render

Production checklist

สร้างและส่ง X-Request-Id เพื่อ traceability
validate payloads กับ OpenAPI หรือ docs ก่อนส่ง live traffic
ทำให้ API base URL configurable และเก็บ bearer token ไว้นอก source code
ตัดสินใจว่า output ควรเป็น inline หรือ attachment mode
เพิ่ม golden-PDF tests สำหรับ critical layouts เพื่อให้เห็น template หรือ data changes

ขอบเขตของ claim

นี่ไม่ใช่ HTML-to-PDF และไม่รัน Chromium
API เรนเดอร์เอกสารตามที่คุณอธิบาย ไม่ infer ความหมายทางกฎหมายหรือธุรกิจจากข้อมูลของคุณ
สำหรับ layout ที่ใช้ซ้ำ Template Render มักเป็น public contract ที่ดีกว่า

JSON Render workflow ใช้ตรงไหน

JSON Render คือ public rendering path ระดับต่ำสุด แอปพลิเคชันของคุณส่งโครงสร้างเอกสารโดยตรง: page size, elements, coordinates, styling, metadata, output mode และ optional PDF/A settings ชั้นนี้เหมาะเมื่อ layout เอกสารถูกสร้างด้วยโค้ด หรือเมื่อทีมของคุณต้องการควบคุม PDF ระดับพิกเซล

API contract ชัดเจน หากระบบของคุณส่ง text element gPdf ก็เรนเดอร์ text element หากส่ง barcode element gPdf ก็วาดบาร์โค้ดเป็นเนื้อหา PDF แบบเวกเตอร์ gPdf ไม่อ่าน business intent จาก payload และไม่ตัดสินว่า invoice number, carrier tracking value หรือ tax field ถูกต้องหรือไม่

เมื่อไรควรย้ายไป Template Render

ถ้า layout เดิมถูกใช้ซ้ำข้ามหลายระบบ ให้ publish เป็นเทมเพลตแล้วเรียก POST /api/v1/template-render ด้วย template_id พร้อม data[] วิธีนี้ย้าย ownership ของ layout ออกจาก caller ทุกตัว และให้ ERP, OMS, WMS หรือ SaaS backend ของคุณมี field contract ที่เสถียร

ใช้ JSON Render สำหรับการสร้าง layout, เอกสารเฉพาะครั้ง และเอกสารแบบ programmatic ใช้ Template Render เมื่อ layout คงที่และสิ่งเดียวที่เปลี่ยนในแต่ละ request คือ business data

รูปแบบสำหรับ production

ใน production ให้ปฏิบัติกับ PDF request เหมือน API call สำคัญอื่น ๆ: ใส่ request ID, ตั้ง timeout, ทำ retries ให้ idempotent, log response metadata และเก็บ PDF ที่ส่งกลับเฉพาะในระบบของคุณเองถ้า retention จำเป็น render path ของ gPdf เป็น stateless หลัง standard render response

FAQ

นี่คือ HTML-to-PDF API หรือไม่: ไม่ gPdf รับ structured JSON DocumentRequest ที่มี pages, elements, coordinates และ settings ไม่รัน browser และไม่ execute arbitrary HTML/CSS
ควรเรียก endpoint ไหนก่อน: เริ่มด้วย POST /api/v1/pdf/render เมื่อคุณต้องการควบคุม layout โดยตรง ย้ายไป POST /api/v1/template-render เมื่อ layout ควรกลายเป็น contract แบบ template_id ที่เสถียร
API ส่ง PDF กลับโดยตรงหรือไม่: ใช่ render ที่สำเร็จจะส่ง application/pdf กลับมา ส่วน errors ใช้ JSON error envelope ร่วมที่มี API-XXX code และ req_id
ทดสอบโดยไม่ build integration ได้ไหม: ใช้ gPdf Playground เพื่อทดสอบ JSON payloads แบบ interactive จากนั้นย้าย shape ของ DocumentRequest เดิมเข้า backend client ของคุณ