factur-x 3.1

Factur-X和Order-X Python库

Factur-X是符合欧洲电子发票标准 EN 16931 的法德电子发票标准。Factur-X规范可在 FNFE-MPE网站（英文和法文）上找到。Factur-X标准在德国也被称为 ZUGFeRD 2.2。

Order-X是采购订单的Factur-X对应标准。Order-X规范可在 FNFE-MPE网站 和 FeRD网站 上找到（英文）。

此Python库的主要功能是从常规PDF文档和Factur-X或Order-X兼容的XML文件生成Factur-X发票和Order-X订单。

此库还提供以下附加功能：

• 从Factur-X或Order-X PDF文件中提取XML文件，

• 将Factur-X或Order-X XML文件与官方的 XML模式定义 进行校验。

此库提供的某些功能也适用于 ZUGFeRD 1.0（Factur-X 标准的前身）。

安装

在 Linux 上安装它，请运行

sudo pip3 install --upgrade factur-x

用法

from facturx import generate_from_file

generate_from_file(regular_pdf_file, xml_file)

PDF 文件 regular_pdf_file 将更新为 Factur-X/Order-X。如果您想将生成的 Factur-X/Order-X PDF 写入另一个文件，请使用参数 output_pdf_file。

要查看更多示例，请查看源代码中的 docstrings 或查看位于 bin 子目录中的命令行工具的源代码。

命令行工具

此库提供了几个命令行工具

• facturx-pdfgen：从常规 PDF 文件和 XML 文件生成 Factur-X 或 Order-X PDF 文件

• facturx-pdfextractxml：从 Factur-X 或 Order-X PDF 文件中提取 XML 文件

• facturx-xmlcheck：检查 Factur-X 或 Order-X XML 文件与官方 XML 架构定义的一致性

所有这些命令行工具都有一个 –help 选项，用于解释如何使用它们并显示所有可用选项。

教程：在 Windows 下生成 Factur-X 发票

从 python.org/downloads 下载 Windows 的最新版本 Python。

启动安装程序。在安装程序的第一屏上，启用选项 将 python.exe 添加到 PATH。安装过程结束后，安装程序会显示一个带有消息 安装成功 的屏幕；在此步骤中，它可能会建议您 禁用路径长度限制，帮助消息说 更改您的机器配置以允许程序，包括 Python，绕过 260 个字符的“MAX_PATH”限制。您必须接受此建议（否则 factur-x 库的安装将失败）：单击标签 禁用路径长度限制 并按照说明操作。

以管理员身份打开 Windows 命令提示符并输入以下命令以下载和安装 factur-x 库

pip3 install --upgrade factur-x

查看安装日志并确保没有错误消息。关闭 Windows 命令提示符。

打开一个新的 Windows 命令提示符（不是管理员身份）并输入以下命令（根据您的文件系统路径进行适配）

python C:\Users\Alexis\AppData\Local\Programs\Python\Python311\Scripts\facturx-pdfgen --help

它应该显示命令 facturx-pdfgen 的帮助信息。

输入以下命令以生成 Factur-X 发票

python C:\Users\Alexis\AppData\Local\Programs\Python\Python311\Scripts\facturx-pdfgen C:\Users\Alexis\Documents\invoice.pdf C:\Users\Alexis\Documents\fx.xml C:\Users\Alexis\Documents\invoice-facturx.pdf

其中

• C:\Users\Alexis\Documents\invoice.pdf 是原始 PDF 发票，

• C:\Users\Alexis\Documents\fx.xml 是 Factur-X XML 文件，

• C:\Users\Alexis\Documents\invoice-facturx.pdf 是将生成的 Factur-X PDF 发票。

Web 服务

该项目还提供了一个 Web 服务，可以从常规 PDF 文件、XML 文件和附加文件（如果有）生成 Factur-X 或 Order-X PDF 文件。此 Web 服务使用 Flask。要运行 Web 服务，请运行位于项目 bin 子目录中的 facturx-webservice。要查询 Web 服务，您必须发送一个使用以下键的 HTTP POST 请求 multipart/form-data

• pdf -> PDF 文件（必需）

• xml -> Factur-X 或 Order-X 文件（任何配置文件，必需）

• attachment1 -> 第一个附件（可选）

• attachment2 -> 第二个附件（可选）

• …

要将此 Web 服务部署到生产环境，请遵循官方 Flask 文档的 指南：您应该使用 WSGI 服务器（如 Gunicorn）和反向代理（如 Nginx 或 Apache）。您可能需要增加默认的最大上传大小（在 Nginx 下的默认值仅为 1MB）：对于 Nginx 使用参数 client_max_body_size，对于 Apache 使用 LimitRequestBody。

我推荐这篇法语教程（如何在Ubuntu上使用Gunicorn和Nginx部署Flask应用程序），其中解释了如何部署Flask应用程序。

您可以使用命令行工具curl发送HTTP请求（在Linux Ubuntu/Debian上，只需安装curl包即可）来生成请求

curl -X POST -F 'pdf=@/home/me/regular_invoice.pdf' -F 'xml=@/home/me/factur-x.xml' -F 'attachment1=@/home/me/delivery_note.pdf' -o /home/me/facturx_invoice.pdf https://ws.fnfe-mpe.org/generate_facturx

此web服务的公共实例在FNFE-MPE的服务器上可用，URL为https://ws.fnfe-mpe.org/generate_facturx。

许可证

该库采用BSD许可证发布（与依赖的pypdf许可证相同）。

贡献者

• Alexis de Lattre <alexis.delattre@akretion.com>

变更日志

• 版本 3.1，日期 2023-08-13

  • 保留输入PDF文件的书签、注释等。为此，我们使用pypdf的clone_document_from_reader()方法而不是append_pages_from_reader()方法。

  • 修复xml类型解析的bug（3.0版本中引入的bug）

  • 尝试生成ZUGFeRD 1.x PDF发票时引发明确的错误

• 版本 3.0，日期 2023-08-13

  • 将依赖PyPDF4替换为pypdf。开发重点重新回到pypdf，PyPDF2、PyPDF3和PyPDF4的分叉不再维护，请参阅此文章。

  • 移除对Python 2.7的支持

  • 在脚本中，将/usr/bin/python3替换为/usr/bin/env python

• 版本 2.5，日期 2023-03-24

  • 在get_level()中添加对ZUGFeRD 1.0的支持

  • xml_check_xsd(): 避免警告“Use specific ‘len(elem)’ or ‘elem is not None’ test instead。”

• 版本 2.4，日期 2023-03-13

  • 更新所有配置文件的Factur-X XSD到版本1.0.6

  • 更新所有配置文件的Order-X XSD到版本1.0.0

• 版本 2.3，日期 2021-04-12

  • 修复generate_facturx_from_file()传递给generate_from_file()的错误flavor参数

• 版本 2.2，日期 2021-04-08

  • 使方法generate_from_binary()可通过库访问

• 版本 2.1，日期 2021-04-07

  • 将Order-X XSD更新到FNFE-MPE提供的最新版本

• 版本 2.0，日期 2021-04-04

  • 添加对Order-X的支持。这涉及到几个变更

    • 方法check_facturx_xsd()被新方法xml_check_xsd()取代，但仍然带有警告

    • 方法get_facturx_flavor()被新方法get_flavor()取代，但仍然带有警告

    • 方法generate_facturx_from_binary()被新方法generate_from_binary()取代，但仍然带有警告

    • 方法generate_facturx_from_file()被新方法generate_from_file()取代，但仍然带有警告

    • 为方法generate_from_file()和generate_from_binary()添加新可选参数orderx_type，默认值为autodetect

    • 添加新方法get_orderx_type()以获取Order-X类型（订单、订单更改或订单响应）

    • 添加新方法get_xml_from_pdf()，该方法同时适用于Factur-X和Order-X（方法get_facturx_xml_from_pdf()仍然存在，仅适用于Factur-X）

    • 更新脚本

  • 为方法generate_from_file()和generate_from_binary()添加新参数lang以设置PDF的lang。这是PDF无障碍性的一项要求，对于残疾人士来说非常重要：它允许盲人PDF语音合成器选择正确的语言。

  • 添加选择Factur-X/Order-X XML文件和附加文件的AFRelationship PDF属性的能力

    • 为方法generate_from_file()和generate_from_binary()添加新参数afrelationship

    • 在方法generate_from_file()和generate_from_binary()的参数中添加新键afrelationship

  • 方法 generate_facturx_from_file() 中的参数 additional_attachments 在 1.8 版本中被弃用：它不再起作用，只会显示警告。

  • 在脚本中将 optparse 库替换为 argparse 库。

• 版本 1.12，日期 2020-07-16

  • 使用 Flate 压缩压缩附件和 XMP 元数据。

• 版本 1.11，日期 2020-05-11

  • 修复了 Python 2.7 上的 UnicodeEncodeError 冒险。

• 版本 1.10，日期 2020-04-14

  • 将所有配置文件的 XSD 更新到 Factur-X 版本 1.0.5。

• 版本 1.9，日期 2020-02-11

  • 在 get_facturx_xml_from_pdf() 中改进了对 Python3 的支持。

• 版本 1.8，日期 2020-01-16

  • 新增工具 facturx-webservice，它通过 Flask 实现了一个 RESTful Web 服务，可以通过简单的 POST 请求生成 Factur-X PDF 发票。

  • 为 generate_facturx_from_file() 新增了参数 attachments，以替换参数 additional_attachments。

    • 可以为附件设置不同的文件名，而不是文件路径的文件名。

    • 可以为附件设置创建日期。

    • 更新脚本来使用新的 attachments 参数。

• 版本 1.7，日期 2020-01-13

  • 修复了 XMP 中的错误：变量没有被替换为其真实值。

• 版本 1.6，日期 2020-01-09

  • 通过字符串替换而不是使用 XML 库生成 XMP（基于 XML 的 PDF 元数据）。

• 版本 1.5，日期 2019-11-13

  • 修复了使用参数 additional_attachments 时在 generate_facturx_from_file() 中的错误。

• 版本 1.4，日期 2019-07-24

  • 将 Factur-X XSD 更新到 Factur-X v1.0.04 的最终版本。

  • 使用“zugferd-invoice.xml”文件名（而不是标准指定的“ZUGFeRD-invoice.xml”文件名）支持使用 ZUGFeRD 发票进行 XML 提取。

• 版本 1.3，日期 2019-06-12

  • 在 Python 包中添加了 Extended 配置文件的 XSD 文件。

• 版本 1.2，日期 2019-06-12

  • 添加了对 Extended 配置文件的支持。

  • 根据 Cyrille Sautereau 的要求，使用 EN 16931 配置文件的 XSD 对 Minimum 和 Basic WL 配置文件进行 XML 验证。

  • 在 /Kids 代码中进行了小的改进。

• 版本 1.1，日期 2019-04-22

  • 通过添加对 /Kids 的支持来改进嵌入式文件的提取支持。

• 版本 1.0，日期 2019-01-26

  • 使用 PyPDF4 而不是 PyPDF2，因为 PyPDF2 自 2016 年 5 月以来没有新版本（cf https://github.com/mstamy2/PyPDF2/wiki/State-of-PyPDF2-and-Future-Plans），我们需要 PyPDF2 的最新版本来生成完全符合 PDF/A-3 的文件。

• 版本 0.9，日期 2019-01-25

  • JoshuaJan 贡献了 Python 3 的迁移（https://github.com/joshuajan）

  • 修复了 ZUGFeRD 1.0 XSD 的路径。

• 版本 0.8，日期 2018-06-10

  • 使 pretty_print 对 XMP 文件生效，以提高该文件的可读性。

• 版本 0.7，日期 2018-05-24

  • 修复了 /x:xmpmeta/rdf:RDF/rdf:Description 下的 XMP 结构（使用 XML 标签而不是 XML 属性）。

  • 声明 PDF-1.6 而不是 PDF-1.3（仍然默认由 pyPDF2 声明）。

• 版本 0.6，日期 2018-05-01

  • 现在完全符合 PDF/A-3，附加附件（使用 veraPDF 测试）。

  • facturx-pdfgen：默认不覆盖，并添加 –overwrite 选项。

  • 在元数据创建器条目中添加 factur-x 库版本号。

• 版本 0.5，日期 2018-03-29

  • 修复了 XMP 元数据结构。

  • 当输入 PDF 文件符合 PDF/A 规范时，现在完全符合 PDF/A-3（使用 veraPDF 测试）。这意味着需要从源 PDF 复制 /OutputIntents 和 /ID 数据到 Factur-X PDF。

  • 修复了对附加附件的支持：现在它们都可以使用 Acrobat Reader 保存。

  • 改进从 Factur-x PDF 文件提取 XML。

• 版本 0.4，日期 2018-03-27

  • Factur-x 规范说明 /AFRelationship 必须是 /Data（而不是 /Alternative）。

  • 将 Factur-X XSD 更新到最终版本 1.0。

  • 添加了对附加附件的支持。

  • 在创建者元数据表中添加 factur-x 库版本。

  • 添加 /PageMode = /UseAttachments，这样在用 Acrobat Reader 打开 Factur-X PDF 发票时，默认会显示附件。

  • 改进并丰富了 PDF 对象（ModDate，CheckSum，Size）。