API hóa đơn Factur-X cho hệ thống production
Tạo hóa đơn Factur-X 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 Factur-X 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 Factur-X 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 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ì
- PDF rendering cho hóa đơn Factur-X 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 Factur-X, 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 Factur-X 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 Factur-X 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 Factur-X 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.