API PDF/A cho tạo PDF lưu trữ
Tạo đầu ra PDF/A từ request JSON Render cho quy trình lưu trữ, với ranh giới rõ giữa hồ sơ PDF/A và đóng gói hóa đơn điện tử.
/api/v1/pdf/render Tạo đầu ra theo hồ sơ PDF/A từ request tài liệu có cấu trúc khi quy trình nghiệp vụ cần PDF thân thiện với lưu trữ, đồng thời chỉ chọn E-Invoice Render khi cần đóng gói hóa đơn có XML 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ó EN 16931 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.
{
"settings": {
"profile": "pdfa-2b"
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Archive-ready document",
"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 là lựa chọn profile
API PDF/A là lựa chọn hồ sơ đầu ra cho tài liệu cần lưu trữ hoặc kiểm tra dài hạn. gPdf có thể tạo PDF theo profile được yêu cầu, nhưng hệ thống của bạn vẫn quyết định dữ liệu nào phải xuất hiện, vì sao cần profile đó và bằng chứng validation nào được chấp nhận.
Nếu mục tiêu là hóa đơn điện tử có XML nhúng, PDF/A-3b chỉ là wrapper. Khi đó hãy dùng E-Invoice Render để đóng gói Factur-X hoặc ZUGFeRD thay vì coi PDF/A đơn thuần là đủ.
FAQ
- Đây có phải API PDF/A độc lập không?
- Có. Trang này ánh xạ quy trình PDF/A 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.