API Factur-X cho hóa đơn điện tử hybrid PDF/A-3b
Tạo hóa đơn Factur-X PDF/A-3b với EN 16931 CII XML nhúng qua endpoint E-Invoice Render công khai.
/api/v1/e-invoice/render Đóng gói PDF hóa đơn đã kết xuất thành Factur-X 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 đã tạo dữ liệu hóa đơn có cấu trúc đú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 Factur-X.
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"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": "Factur-X 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.
Factur-X là quy trình đóng gói hóa đơn điện tử
Factur-X là quy trình đóng gói hóa đơn điện tử, không chỉ là tên gọi của một PDF hóa đơn. ERP hoặc hệ thống lập hóa đơn của bạn tạo dữ liệu hóa đơn có cấu trúc đúng, còn gPdf đóng gói PDF hóa đơn đã được kết xuất cùng EN 16931 CII XML thành PDF/A-3b.
Đường API phù hợp là POST /api/v1/e-invoice/render. Hãy dùng capabilities endpoint và OpenAPI để xác nhận profile được hỗ trợ, rồi xác thực đầu ra bằng trình xác thực tham chiếu hoặc quy trình của bên nhận. gPdf không tạo XML hợp lệ từ dữ liệu thiếu và không thay thế quyết định pháp lý downstream.
FAQ
- Factur-X có phải hóa đơn PDF thông thường không?
- Không. Factur-X 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.