Đây có phải API hóa đơn PDF độc lập không?

Có. Trang này ánh xạ quy trình hóa đơ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 hóa đơn cho hệ thống lập hóa đơn và tài chính

Tạo PDF hóa đơn thông thường từ dữ liệu billing bằng JSON Render hoặc Template Render, trong khi logic thuế và kế toán nằm trong hệ thống của bạn.

API CHÍNH JSON Render

ENDPOINT /api/v1/pdf/render

HỆ THỐNG backend tính phí / ERP / hệ thống kế toán / ứng dụng SaaS

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

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

Chuyển dữ liệu hóa đơn từ hệ thống lập hóa đơn, ERP hoặc SaaS thành PDF hóa đơn dễ đọc, trong khi số hóa đơn, thuế, trạng thái thanh toán và ngữ nghĩa kế toán vẫn nằm trong hệ thống gọi.

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 PDF/A-3b với EN 16931 CII XML. 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.

PHỤ 2

/api/v1/e-invoice/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 - hóa đơn PDF.

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Invoice INV-1007",
          "style": { "font_size": 18, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "text",
          "x": 20,
          "y": 42,
          "content": "Bill to: Example Customer\nAmount due: USD 245.00",
          "style": { "font_size": 11, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "line",
          "x1": 20,
          "y1": 62,
          "x2": 190,
          "y2": 62
        }
      ]
    }
  ]
}

gPdf xử lý gì

Kết xuất PDF tài liệu từ JSON pages hoặc dữ liệu template.
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.

Hóa đơn PDF thông thường và hóa đơn điện tử

API PDF hóa đơn tạo PDF hóa đơn thông thường từ dữ liệu billing hoặc ERP. Đây không tự động là mandate hóa đơn điện tử pháp lý; nếu cần Factur-X hoặc ZUGFeRD PDF/A-3b với EN 16931 CII XML nhúng, hãy dùng E-Invoice Render.

Template Render thường là endpoint production

Trong production, bố cục hóa đơn thường ổn định và được nhiều hệ thống dùng lại. Khi đó Template Render với template_id giúp hệ thống gọi chỉ gửi dữ liệu nghiệp vụ, còn owner tài liệu kiểm soát bố cục và thay đổi template.

Giữ logic kế toán ở upstream

gPdf kết xuất PDF hóa đơn; gPdf không tính thuế, không cấp số hóa đơn, không reconcile payment và không quyết định ý nghĩa ledger. Những phần đó phải nằm trong hệ thống lập hóa đơn, ERP hoặc kế toán của bạn.

FAQ

Đây có phải API hóa đơn PDF độc lập không?: Có. Trang này ánh xạ quy trình hóa đơ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.