Đây có phải API JSON sang PDF độc lập không?

Có. Trang này ánh xạ quy trình JSON sang PDF vào endpoint công khai POST /api/v1/pdf/render. Hệ thống của bạn vẫn sở hữu dữ liệu nghiệp vụ, còn gPdf chỉ tạo PDF từ request hợp lệ.

Khi nào nên dùng Template Render?

Dùng Template Render khi bố cục đã được duyệt và bạn muốn gọi bằng template_id cùng data thay vì gửi toàn bộ tọa độ ở mỗi request.

API có trả PDF trực tiếp không?

Có. Khi kết xuất thành công, API trả về application/pdf. Khi lỗi, API dùng JSON error envelope chung với mã API-XXX và req_id.

Cần kiểm tra gì trước production?

Hãy đưa cùng DocumentRequest shape từ Playground vào backend client và kiểm thử với dữ liệu thật.

Quy trình cho lập trình viên

API JSON sang PDF cho tạo tài liệu có cấu trúc

Chuyển JSON DocumentRequest có cấu trúc thành PDF với trang, tọa độ, văn bản, bảng, mã vạch, metadata và thiết lập PDF/A.

API CHÍNH JSON Render

ENDPOINT /api/v1/pdf/render

HỆ THỐNG backend SaaS / API worker / AI agent / job queue

Thử trong Playground Đọc tài liệu

Việc cần giải quyết

Chuyển dữ liệu ứng dụng có cấu trúc thành tài liệu PDF xác định mà không chạy trình duyệt, không gửi HTML/CSS và không lưu file khách hàng. Hệ thống của bạn gửi pages, elements, tọa độ, thiết lập và nội dung nghiệp vụ; gPdf trả về phản hồi application/pdf.

Khi nào dùng API này

Backend của bạn đã có dữ liệu có cấu trúc và cần nhận phản hồi PDF.
Bạn muốn định nghĩa rõ pages, tọa độ, elements, mã vạch và thiết lập thay vì bố cục HTML.
Bạn cần đầu ra lặp lại được cho hóa đơn, nhãn, báo cáo, sao kê hoặc bộ tài liệu sinh tự động.
Bạn muốn thử payload trong Playground trước khi đưa token vào production.

Những gì không thay thế

Bạn cần chuyển HTML tùy ý sang PDF. gPdf dùng DocumentRequest JSON, không dùng browser DOM.
Đội ngũ của bạn muốn hợp đồng template_id ổn định. Hãy dùng Template Render sau khi bố cục được publish.
Bạn cần đóng gói hóa đơn điện tử Factur-X hoặc ZUGFeRD. Hãy dùng endpoint E-Invoice Render.

Endpoint cần gọi

CHÍNH

/api/v1/pdf/render

JSON Render là đường mặc định cho quy trình này.

PHỤ 1

/api/v1/template-render

Dùng khi quy trình cần API liên quan, hợp đồng mẫu hoặc truy vấn năng lực.

Request tối thiểu

POST /api/v1/pdf/render - DocumentRequest JSON một trang.

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

gPdf xử lý gì

Kết xuất DocumentRequest từ pages và elements.
Văn bản, bảng, hình ảnh, mã vạch vector, đường kẻ, hình khối, watermark, metadata và thiết lập PDF/A.
Nhúng font và fallback cho Latin, CJK, emoji-capable và các script được hỗ trợ khác.
Phản hồi PDF nhị phân cùng error-code envelope chung của gPdf khi thất bại.

Hệ thống của bạn quản lý gì

Dữ liệu nghiệp vụ, ánh xạ trường và ngữ nghĩa tài liệu.
Request ID, chiến lược retry và idempotency, đặt tên file và lưu trữ sau phản hồi.
Mọi quy tắc thuế, hóa đơn, hãng vận chuyển, tuân thủ hoặc khách hàng trước khi kết xuất.

Checklist đưa vào production

Tạo và truyền X-Request-Id để truy vết.
Kiểm tra payload theo OpenAPI hoặc docs trước khi gửi traffic thật.
Giữ API base URL có thể cấu hình và lưu bearer token ngoài mã nguồn.
Quyết định đầu ra nên ở chế độ inline hay attachment.
Thêm golden-PDF tests cho các bố cục quan trọng để thấy rõ thay đổi template hoặc dữ liệu.

Ranh giới tuyên bố

Đây không phải HTML-to-PDF và không chạy Chromium.
API kết xuất tài liệu bạn mô tả; API không suy luận ý nghĩa pháp lý hay nghiệp vụ từ dữ liệu.
Với bố cục dùng lặp lại, Template Render thường là hợp đồng public tốt hơn.

Quy trình JSON Render phù hợp ở đâu

JSON Render là đường kết xuất công khai ở mức thấp nhất. Ứng dụng của bạn gửi trực tiếp cấu trúc tài liệu: kích thước trang, elements, tọa độ, style, metadata, chế độ đầu ra và các thiết lập PDF/A tùy chọn. Đây là lớp phù hợp khi bố cục được sinh bằng mã hoặc khi đội ngũ muốn kiểm soát PDF đến từng pixel.

Hợp đồng API là rõ ràng. Nếu hệ thống gửi text element, gPdf kết xuất text element. Nếu gửi mã vạch element, gPdf vẽ mã vạch dưới dạng nội dung PDF vector. gPdf không đọc ý định nghiệp vụ từ payload và không quyết định số hóa đơn, mã tracking hãng vận chuyển hoặc trường thuế có đúng hay không.

Khi nào nên chuyển sang Template Render

Nếu cùng một bố cục được dùng lặp lại giữa nhiều hệ thống, hãy publish nó thành template và gọi POST /api/v1/template-render với template_id cộng data[]. Cách này đưa quyền sở hữu bố cục ra khỏi từng hệ thống gọi và cho ERP, OMS, WMS hoặc backend SaaS một hợp đồng trường ổn định.

Dùng JSON Render cho giai đoạn tạo bố cục, tài liệu một lần và tài liệu sinh bằng chương trình. Dùng Template Render khi bố cục đã cố định và phần thay đổi duy nhất trong mỗi request là dữ liệu nghiệp vụ.

Mô hình production

Trong production, hãy đối xử với request PDF như mọi API call quan trọng khác: thêm request ID, đặt timeout, làm retry idempotent, log metadata phản hồi và chỉ lưu PDF trả về trong hệ thống của bạn nếu cần retention. Đường kết xuất tiêu chuẩn của gPdf là stateless sau khi phản hồi được trả về.

FAQ

Đây có phải API JSON sang PDF độc lập không?: Có. Trang này ánh xạ quy trình JSON sang PDF vào endpoint công khai POST /api/v1/pdf/render. Hệ thống của bạn vẫn sở hữu dữ liệu nghiệp vụ, còn gPdf chỉ tạo PDF từ request hợp lệ.
Khi nào nên dùng Template Render?: Dùng Template Render khi bố cục đã được duyệt và bạn muốn gọi bằng template_id cùng data thay vì gửi toàn bộ tọa độ ở mỗi request.
API có trả PDF trực tiếp không?: Có. Khi kết xuất thành công, API trả về application/pdf. Khi lỗi, API dùng JSON error envelope chung với mã API-XXX và req_id.
Cần kiểm tra gì trước production?: Hãy đưa cùng DocumentRequest shape từ Playground vào backend client và kiểm thử với dữ liệu thật.