gPdf
Tuân thủ và lưu trữ

API hóa đơn điện tử cho Factur-X và ZUGFeRD PDF/A-3b

Tạo hóa đơn điện tử Factur-X và ZUGFeRD PDF/A-3b với EN 16931 CII XML nhúng qua endpoint e-invoice công khai của gPdf.

API CHÍNH E-Invoice Render
ENDPOINT /api/v1/e-invoice/render
HỆ THỐNG ERP / backend tài chính / hệ thống công nợ phải thu / quy trình tuân thủ
Thử trong Playground Đọc tài liệu
Việc cần giải quyết

Đóng gói một PDF hóa đơn human-readable và EN 16931 CII XML do hệ thống gọi cung cấp thành hóa đơn điện tử Factur-X hoặc ZUGFeRD PDF/A-3b có thể được trình xác thực PDF/A và engine tham chiếu e-invoice bên ngoài kiểm tra.

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

CHÍNH

/api/v1/e-invoice/render

E-Invoice Render là đường mặc định cho quy trình này.

PHỤ 1

/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 điện tử Factur-X / ZUGFeRD.

{
  "settings": {
    "profile": "pdfa-3b",
    "e_invoice": {
      "standard": "factur_x",
      "profile": "en16931",
      "document_type": "invoice",
      "xml": {
        "format": "cii",
        "encoding": "utf8",
        "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
      }
    }
  },
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Invoice INV-1007",
          "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

  1. Gọi /api/v1/e-invoice/capabilities trước khi giả định standard hoặc profile.
  2. Xác thực EN 16931 CII XML trước khi nhúng.
  3. Chạy đầu ra qua /validator/ hoặc pipeline reference-engine của bạn.
  4. 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.
  5. 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.

Một endpoint cho gói hóa đơn điện tử

API hóa đơn điện tử dùng endpoint E-Invoice Render để đóng gói PDF/A-3b và XML hóa đơn có cấu trúc. Hệ thống gọi cung cấp PDF hoặc nội dung kết xuất cùng EN 16931 CII XML; gPdf xử lý wrapper, attachment metadata và e-invoice XMP wiring.

Những gì vẫn nằm ngoài gPdf

Tính đúng nghiệp vụ của dữ liệu hóa đơn, thuế, định danh buyer/seller, routing và acceptance với receiver vẫn thuộc hệ thống của bạn. gPdf không biến dữ liệu thiếu thành XML hợp lệ và không thay thế quy trình pháp lý downstream.

Không biến thuật ngữ roadmap thành tuyên bố hỗ trợ native

Chỉ tuyên bố hỗ trợ native cho chuẩn xuất hiện trong OpenAPI hoặc capabilities endpoint. Các tên như XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e hoặc GST có thể là bối cảnh thị trường, nhưng không phải đầu ra được hỗ trợ nếu OpenAPI chưa liệt kê.

FAQ

Hóa đơn điện tử có phải hóa đơn PDF thông thường không?
Không. Hóa đơn điện tử 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.
Giải pháp API Factur-X E-Invoice Render Giải pháp API ZUGFeRD E-Invoice Render Giải pháp API PDF/A JSON Render Giải pháp API PDF/A-3b JSON Render Giải pháp API PDF hóa đơn JSON Render Tham chiếu Tham chiếu E-Invoice API /docs/e-invoice-api/ Tham chiếu Tham chiếu Render API /docs/api-reference/ Tham chiếu Trường hợp sử dụng hóa đơn điện tử EU /use-cases/eu-e-invoice/ Tham chiếu Xác thực ZUGFeRD bằng Mustang /blog/validating-zugferd-with-mustang/ Tham chiếu PDF/A và Factur-X cho kỹ sư /blog/pdf-a-and-factur-x-explained-for-engineers/