API ZUGFeRD cho hóa đơn hybrid PDF/A-3b
Tạo hóa đơn ZUGFeRD PDF/A-3b với EN 16931 CII XML nhúng bằng endpoint E-Invoice Render công khai của gPdf.
/api/v1/e-invoice/render Đóng gói đầu ra PDF hóa đơn thành ZUGFeRD PDF/A-3b với EN 16931 CII XML nhúng sau khi ERP hoặc hệ thống lập hóa đơn của bạn đã chuẩn bị dữ liệu hóa đơn đúng.
Khi nào dùng API này
- Bạn cần đầu ra Factur-X hoặc ZUGFeRD, không chỉ PDF hóa đơn thông thường.
- Hệ thống của bạn có thể cung cấp EN 16931 CII XML đúng cho hóa đơn.
- Bạn cần đóng gói PDF/A-3b, attachment metadata và e-invoice XMP wiring.
- Bạn muốn endpoint capabilities công khai xác nhận standards và profiles được hỗ trợ.
Những gì không thay thế
- Bạn chỉ cần PDF hóa đơn thông thường cho khách hàng. Hãy dùng JSON Render hoặc Template Render.
- Bạn cần native XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e hoặc GST trước khi OpenAPI liệt kê.
- Bạn kỳ vọng gPdf tạo XML hóa đơn hợp lệ từ dữ liệu nghiệp vụ thiếu.
Endpoint cần gọi
/api/v1/e-invoice/render
E-Invoice Render là đường mặc định cho quy trình này.
/api/v1/e-invoice/capabilities
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/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ì
- Đóng gói Factur-X hoặc ZUGFeRD PDF/A-3b qua POST /api/v1/e-invoice/render.
- Nhúng EN 16931 CII XML do hệ thống gọi cung cấp dưới dạng associated file.
- PDF/A-3b wrapper metadata và e-invoice XMP wiring theo chuẩn.
- Discovery capability qua GET /api/v1/e-invoice/capabilities.
Hệ thống của bạn quản lý gì
- Ngữ nghĩa hóa đơn, quy tắc thuế, định danh người mua/người bán và tính đúng của EN 16931 XML.
- Quyết định Factur-X hoặc ZUGFeRD có phù hợp với quy trình của người nhận hay không.
- Acceptance testing bên ngoài với receiver, AP automation system hoặc quy trình tuân thủ địa phương.
Checklist đưa vào production
- Gọi /api/v1/e-invoice/capabilities trước khi giả định standard hoặc profile.
- Xác thực EN 16931 CII XML trước khi nhúng.
- Chạy đầu ra qua /validator/ hoặc pipeline reference-engine của bạn.
- Tách tạo PDF hóa đơn thông thường khỏi đóng gói hóa đơn điện tử pháp lý trong code.
- Log request ID, standard, profile, XML source version và bằng chứng xác thực.
Ranh giới tuyên bố
- Đầu ra e-invoice native công khai là Factur-X / ZUGFeRD với EN 16931 CII XML.
- Tên hóa đơn điện tử quốc gia khác chỉ là bối cảnh thị trường trừ khi OpenAPI liệt kê là chuẩn được hỗ trợ.
- gPdf đóng gói XML do hệ thống gọi cung cấp; hệ thống của bạn vẫn chịu trách nhiệm tính đúng nghiệp vụ của XML.
ZUGFeRD dùng đường E-Invoice Render
ZUGFeRD dùng cùng đường E-Invoice Render như Factur-X cho hóa đơn hybrid PDF/A-3b có EN 16931 CII XML nhúng. Hệ thống gọi vẫn chịu trách nhiệm chuẩn bị dữ liệu hóa đơn đúng và quyết định ZUGFeRD có phù hợp với quy trình của người nhận hay không.
Gọi POST /api/v1/e-invoice/render khi cần đóng gói ZUGFeRD. Trước production, hãy kiểm tra capabilities, OpenAPI và trình xác thực bên ngoài; đừng tuyên bố hỗ trợ chuẩn quốc gia khác nếu OpenAPI chưa liệt kê.
FAQ
- ZUGFeRD có phải hóa đơn PDF thông thường không?
- Không. ZUGFeRD là gói hóa đơn điện tử PDF/A-3b có EN 16931 CII XML nhúng; hóa đơn PDF thông thường nên dùng JSON Render hoặc Template Render.
- gPdf có tạo XML hợp lệ từ dữ liệu thiếu không?
- Không. gPdf đóng gói XML do hệ thống gọi cung cấp. ERP hoặc hệ thống lập hóa đơn của bạn vẫn phải tạo XML đúng nghiệp vụ và đúng chuẩn.
- Làm sao biết chuẩn nào được hỗ trợ?
- Gọi GET /api/v1/e-invoice/capabilities và đối chiếu OpenAPI trước khi tuyên bố hỗ trợ một chuẩn hay profile.
- Có cần trình xác thực ngoài không?
- Có. Hãy chạy đầu ra qua /validator/ hoặc pipeline veraPDF/Mustang/receiver của bạn để giữ bằng chứng chấp nhận.