Đây có phải API biên nhận PDF độc lập không?

Có. Trang này ánh xạ quy trình biên nhận 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 kiểm tra dữ liệu thật, overflow nhiều trang, tổng tiền, định dạng tiền tệ và quy trình kế toán downstream.

Hóa đơn và tài chính

API PDF biên nhận cho ecommerce và thanh toán SaaS

Tạo PDF biên nhận từ dữ liệu order, payment, tax và refund với mã QR, mã vạch, thiết lập PDF/A và đầu ra template lặp lại được.

API CHÍNH JSON Render

ENDPOINT /api/v1/pdf/render

HỆ THỐNG backend thương mại điện tử / backend tính phí / SaaS platform / POS export service

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

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

Chuyển dữ liệu order, payment, refund và tax đã hoàn tất thành PDF biên nhận có thể email, lưu, in hoặc gắn vào tài khoản khách hàng mà không yêu cầu mọi hệ thống gọi tự viết code vẽ PDF.

Khi nào dùng API này

Bạn cần PDF tài chính thông thường cho khách hàng, biên nhận, sao kê hoặc export kế toán.
Hệ thống của bạn đã sở hữu số chứng từ, tính thuế, line items và trạng thái thanh toán.
Bạn muốn bảng, totals, metadata và tùy chọn PDF/A mà không chạy trình duyệt.
Bạn muốn hợp đồng template_id cho bố cục tài chính dùng lặp lại.

Những gì không thay thế

Bạn cần gói hóa đơn điện tử pháp lý như Factur-X hoặc ZUGFeRD. Hãy dùng E-Invoice Render.
Bạn kỳ vọng gPdf tính thuế, xác thực quy tắc kế toán hoặc reconcile payments.
Bạn muốn chuyển HTML tùy ý thành hóa đơn thay vì dùng JSON có cấu trúc hoặc template.

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 - biên nhận PDF.

{
  "pages": [
    {
      "size": "a6",
      "elements": [
        {
          "type": "text",
          "x": 10,
          "y": 12,
          "content": "Receipt R-2026-1001",
          "style": { "font_size": 16, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "text",
          "x": 10,
          "y": 28,
          "content": "Order total: $82.40\nPaid by card ending 4242\nTax: $6.10",
          "style": { "font_size": 10, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "barcode",
          "format": "qrcode",
          "content": "https://example.com/receipts/R-2026-1001",
          "x": 10,
          "y": 58,
          "width": 28,
          "height": 28
        }
      ]
    }
  ]
}

gPdf xử lý gì

Kết xuất DocumentRequest hoặc dữ liệu template thành PDF tài liệu.
Văn bản, bảng, khối tổng tiền, phân trang, metadata và đầu ra PDF/A tùy chọn.
Template Render cho bố cục ổn định dùng bởi nhiều hệ thống.
Phản hồi PDF nhị phân và API error envelope nhất quán.

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

Số chứng từ, trạng thái thanh toán, tính thuế, discount, credit và ý nghĩa ledger.
Dữ liệu khách hàng/issuer, ánh xạ line item, tiền tệ và quy tắc làm tròn.
Retention, delivery, email, payment links và reconciliation với hệ thống kế toán.

Checklist đưa vào production

Xác nhận mọi trường hiển thị map về dữ liệu nguồn.
Test overflow line item, tên khách hàng dài, tài liệu nhiều trang và totals.
Quyết định bố cục thuộc JSON Render hay template đã publish.
Tách tạo PDF thông thường khỏi đóng gói hóa đơn điện tử pháp lý.
Lưu request ID và tên đầu ra file cùng bản ghi nghiệp vụ.

Ranh giới tuyên bố

PDF tài chính thông thường không giống mandate hóa đơn điện tử pháp lý.
gPdf kết xuất tài liệu; gPdf không tính thuế hoặc trạng thái kế toán.
Output Factur-X / ZUGFeRD thuộc POST /api/v1/e-invoice/render.

PDF biên nhận là đầu ra kết xuất

PDF biên nhận là đầu ra kết xuất từ dữ liệu order, payment, refund và tax mà hệ thống của bạn đã quyết định. gPdf có thể kết xuất DocumentRequest hoặc dữ liệu template thành PDF, nhưng không quyết định trạng thái thanh toán hoặc quy tắc kế toán.

Đường template cho biên nhận lặp lại

Nếu biên nhận dùng cùng bố cục giữa nhiều hệ thống gọi, hãy publish bố cục thành template và gọi Template Render bằng template_id. Điều này giữ bố cục ổn định trong khi backend chỉ gửi dữ liệu nghiệp vụ.

FAQ

Đây có phải API biên nhận PDF độc lập không?: Có. Trang này ánh xạ quy trình biên nhận 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 kiểm tra dữ liệu thật, overflow nhiều trang, tổng tiền, định dạng tiền tệ và quy trình kế toán downstream.