API PDF sao kê cho export tài khoản và billing
Tạo PDF sao kê tài khoản, billing và hoạt động với nhiều trang dòng dữ liệu, totals, metadata và tùy chọn PDF/A archival.
/api/v1/pdf/render Kết xuất PDF sao kê khách hàng, tài khoản hoặc billing từ dữ liệu kỳ, opening balances, line items, adjustments và totals để người dùng tải xuống một bản ghi nhất quán cho review hoặc retention.
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
/api/v1/pdf/render
JSON Render là đường mặc định cho quy trình này.
/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 - sao kê PDF.
{
"settings": {
"profile": "pdfa-2b"
},
"pages": [
{
"size": "letter",
"elements": [
{
"type": "text",
"x": 18,
"y": 20,
"content": "Account Statement",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 18,
"y": 38,
"content": "Period: 2026-05-01 to 2026-05-31\nOpening balance: $1,240.00\nClosing balance: $1,890.25",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
}
]
}
]
}
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.
Sao kê là tài liệu theo kỳ
Sao kê là tài liệu theo kỳ: opening balance, line items, adjustments và totals cần khớp với hệ thống nguồn. gPdf có thể kết xuất DocumentRequest hoặc dữ liệu template thành PDF sao kê, nhưng không quyết định số dư hay nghĩa kế toán.
Xử lý tập dòng lớn
Với sao kê nhiều dòng, hãy kiểm tra phân trang, header lặp lại, totals, dòng dài và đầu ra PDF/A nếu cần lưu trữ. Hệ thống của bạn vẫn chịu trách nhiệm chọn kỳ, chunk dữ liệu và retention policy.
FAQ
- Đây có phải API sao kê PDF độc lập không?
- Có. Trang này ánh xạ quy trình sao kê 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.