API PDF/A-3b cho lưu trữ và hóa đơn điện tử
Tạo đầu ra PDF/A-3b bằng gPdf và hiểu khi nào PDF/A-3b chỉ là hồ sơ lưu trữ so với khi là wrapper hóa đơn điện tử.
/api/v1/pdf/render Tạo tài liệu PDF/A-3b cho quy trình lưu trữ và chọn endpoint e-invoice khi PDF/A-3b phải mang XML EN 16931 Factur-X hoặc ZUGFeRD nhúng.
Khi nào dùng API này
- Bạn cần đầu ra PDF/A cho quy trình lưu trữ hoặc retention.
- Hệ thống của bạn đã có dữ liệu tài liệu và cần chỉ định profile PDF/A rõ ràng.
- Bạn cần tách hồ sơ PDF/A khỏi nghĩa vụ hóa đơn điện tử.
- Bạn muốn kiểm tra đầu ra bằng trình xác thực tham chiếu bên ngoài.
Những gì không thay thế
- Bạn cần hóa đơn điện tử Factur-X hoặc ZUGFeRD có XML nhúng. Hãy dùng E-Invoice Render.
- Bạn kỳ vọng PDF/A tự làm cho dữ liệu nghiệp vụ trở nên hợp lệ về mặt pháp lý.
- Bạn cần hệ thống lưu trữ, retention policy hoặc acceptance quy trình do gPdf vận hành.
Endpoint cần gọi
/api/v1/pdf/render
JSON Render là đường mặc định cho quy trình này.
/api/v1/e-invoice/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 - PDF/A-3b.
{
"settings": {
"profile": "pdfa-3b"
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Archive copy",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf xử lý gì
- Kết xuất PDF với thiết lập hồ sơ PDF/A được yêu cầu.
- Metadata, font embedding và các ràng buộc PDF/A liên quan đến đầu ra.
- Phản hồi PDF nhị phân qua JSON Render hoặc E-Invoice Render tùy ý định.
- Đường kiểm tra qua trình xác thực hoặc reference-engine pipeline bên ngoài.
Hệ thống của bạn quản lý gì
- Dữ liệu nghiệp vụ, lý do chọn profile và yêu cầu retention.
- Acceptance policy, trình xác thực tham chiếu và bằng chứng kiểm thử.
- Mọi nghĩa vụ pháp lý hoặc lưu trữ ngoài đầu ra PDF.
Checklist đưa vào production
- Chọn profile PDF/A phù hợp trước khi kết xuất.
- Xác thực request theo OpenAPI hoặc docs trước production.
- Chạy đầu ra qua /validator/ hoặc trình xác thực tham chiếu bên ngoài.
- Ghi lại request ID, profile và bằng chứng validation.
- Tách PDF/A archival khỏi logic hóa đơn điện tử nếu cần XML nhúng.
Ranh giới tuyên bố
- PDF/A là hồ sơ đầu ra; nó không tự chứng minh dữ liệu nghiệp vụ đúng.
- Khi PDF/A-3b phải chứa Factur-X hoặc ZUGFeRD XML, hãy dùng E-Invoice Render.
- Validation và acceptance cuối cùng vẫn thuộc quy trình của hệ thống gọi.
PDF/A-3b là wrapper, không phải toàn bộ quy trình
PDF/A-3b là một hồ sơ/wrapper đầu ra. Nó hữu ích cho lưu trữ và cũng là wrapper thường dùng cho hóa đơn điện tử có XML nhúng, nhưng bản thân PDF/A-3b không quyết định dữ liệu nghiệp vụ đúng.
Chọn endpoint theo mục đích
Nếu bạn chỉ cần tài liệu PDF/A-3b để lưu trữ, dùng JSON Render với profile PDF/A phù hợp. Nếu PDF/A-3b phải mang Factur-X hoặc ZUGFeRD EN 16931 XML, hãy dùng endpoint E-Invoice Render.
Xác thực bằng công cụ bên ngoài
Chạy đầu ra qua /validator/ hoặc trình xác thực tham chiếu bên ngoài và lưu bằng chứng. Acceptance cuối cùng, retention policy và yêu cầu pháp lý vẫn thuộc quy trình của hệ thống gọi.
FAQ
- Đây có phải API PDF/A-3b độc lập không?
- Có. Trang này ánh xạ quy trình PDF/A-3b 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 xác thực bằng /validator/ hoặc reference engine bên ngoài và lưu bằng chứng validation.