API hóa đơn ZUGFeRD cho hệ thống production
Tạo hóa đơn ZUGFeRD từ dữ liệu backend có cấu trúc, không cần browser. gPdf xử lý PDF rendering; logic nghiệp vụ nằm trong hệ thống của bạn.
/api/v1/e-invoice/render Tạo hóa đơn ZUGFeRD thành PDF có thể tái tạo từ dữ liệu có cấu trúc. gPdf render tài liệu; hệ thống của bạn giữ ngữ nghĩa dữ liệu và trạng thái quy trình.
Khi nào dùng API này
- Backend đã có dữ liệu hóa đơn ZUGFeRD và cần phản hồi PDF ổn định.
- Bạn muốn tránh Chromium hoặc HTML-to-PDF cho tài liệu vận hành.
- Bạn cần output lặp lại được cho in lại, audit hoặc batch.
Những gì không thay thế
- gPdf không mua vận chuyển, khai thuế, tạo đơn hàng ngoài hoặc đóng vai trò hệ thống thuế.
- Không thay thế validation dữ liệu, business rules hoặc tích hợp marketplace.
Endpoint cần gọi
/api/v1/e-invoice/render
E-Invoice Render là đường mặc định cho workflow này.
/api/v1/e-invoice/capabilities
Dùng khi workflow cần API liên quan, hợp đồng template hoặc truy vấn capability.
Request tối thiểu
/api/v1/e-invoice/render - hóa đơn ZUGFeRD
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "zugferd",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "ZUGFeRD invoice",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf xử lý gì
- PDF rendering cho hóa đơn ZUGFeRD từ request có cấu trúc.
- Text, bảng, đường kẻ, barcode, trang, metadata và tùy chọn output theo request.
- Output deterministic cho retry, in lại và audit.
Hệ thống của bạn quản lý gì
- Dữ liệu đúng của hóa đơn ZUGFeRD, business rules và trạng thái vận hành.
- Authentication, lưu trữ, workflow bên ngoài và kiểm tra với hệ thống nhận.
Checklist production
- Test bằng dữ liệu thật và hệ thống sẽ nhận PDF.
- Lưu request ID và bằng chứng validation cho support, audit và in lại.
- Chuyển layout đã duyệt thành template khi nhiều hệ thống dùng lại.
Ranh giới cam kết
- gPdf dùng public e-invoice endpoint cho Factur-X / ZUGFeRD PDF/A-3b.
- Cổng thuế, PDP, SDI, KSeF, ZATCA, IRP, Peppol và nghĩa vụ pháp lý nằm ngoài scope.
- Buyer data, tax logic, routing và diễn giải pháp lý địa phương thuộc hệ thống của bạn.
Dạng API
API hóa đơn ZUGFeRD là workflow production chạy trên public APIs của gPdf. Request mô tả dữ liệu, layout, settings và các phần PDF cần render. gPdf tạo PDF; hệ thống của bạn giữ ngữ nghĩa nghiệp vụ.
Chọn endpoint
Endpoint mặc định của workflow này là /api/v1/e-invoice/render. Dùng Template Render khi layout đã duyệt và tái sử dụng giữa nhiều hệ thống. Chỉ dùng E-Invoice Render khi cần gói Factur-X / ZUGFeRD PDF/A-3b với EN 16931 CII XML nhúng.
Kiểm tra trước production
Kiểm tra hóa đơn ZUGFeRD bằng dữ liệu thật và downstream systems. Lưu request ID, output đã render và bằng chứng validation cho support, audit và in lại.
FAQ
- Đây có phải endpoint riêng không?
- API hóa đơn ZUGFeRD dùng public e-invoice endpoint khi cần Factur-X / ZUGFeRD PDF/A-3b. Đây không phải surface riêng.
- Có bao phủ mạng clearance địa phương không?
- Không. gPdf render và đóng gói PDF/e-invoice; cổng thuế và routing pháp lý nằm trong hệ thống của bạn.
- Có thể tiếp tục dùng JSON Render không?
- Có, với PDF thông thường. Dùng E-Invoice Render khi output phải chứa gói e-invoice có cấu trúc.