# @ekwo-ai/factur-x 中文文档

规范地址：https://npmcn.com/package/%40ekwo-ai/factur-x/

版本：0\.25\.2
npm 元数据更新时间：2026-11-13T14:09:26.546Z
中文译文更新时间：2026-11-13T15:44:57.732Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ekwo-ai/factur-x
原文对照：https://npmcn.com/package/%40ekwo-ai/factur-x/?lang=original
项目主页：https://github.com/Ekwo-ai/ekwo-os/tree/main/packages/formats/factur-x#readme
源码仓库：https://github.com/Ekwo-ai/ekwo-os

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：228 kB，64 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-09-18T16:07:15.803Z
- 最新版本发布：2026-11-13T14:09:26.023Z
- 近 30 天下载量：4197（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

Factur-X / ZUGFERD TypeScript中的电子发票:EN 16931 CII XML 从平面发票对象,PDF/A-3嵌入和取出.

## 安装

```sh
npm install @ekwo-ai/factur-x
```

也可以使用：`pnpm add @ekwo-ai/factur-x`、`yarn add @ekwo-ai/factur-x`、`bun add @ekwo-ai/factur-x`

## README

# @ekwo-ai/事实十

Factur-X / ZUGFERD TypeScript的电子发票.

-   **CII XML 从平面发票对象.** EN 16931 语义模型,联合国/简化手续中心CII D16B 语法、计划要素顺序、增值税细目规则(`BR-S`, (中文(简体) ), `BR-Z`, (中文(简体) ), `BR-E`, (中文(简体) ), `BR-AE`, (中文(简体) ), `BR-IC`, (中文(简体) ), `BR-G`, (中文(简体) ), `BR-O`简介 MINIMUM, BASIC WL, BASIC (默认), EN 16931, EXTED.
-   **PDF/A-3 嵌入系统.** 附以 XML 为 `factur-x.xml` 与 `AFRelationship /Alternative` 并用 Factur-X 扩展图谱写入 XMP 包.
-   **提炼.** 读取 `factur-x.xml`, (中文(简体) ), `zugferd-invoice.xml` 或者说 `xrechnung.xml` 从任意 PDF 返回.
-   **阅读收到的发票.** `readCii` 财务报告和审定财务报表 `readFacturX` 打开任意配置文件的 CII 进入相同的平面结果 `@ekwo-ai/peppol-ubl` 从 UBL 返回 - 见 [阅读](https://npmcn.com/package/%40ekwo-ai/factur-x/#readme-reading)。 。 。 .
-   **总数你可以信任.** 每个类别和税率一个增值税类别,按四舍五入计算增值税 基础、预付款项、参考原始发票的信用证.
-   XML 部分的零依赖性; `pdf-lib` 仅用于PDF部分(分出入口).

## 安装

```sh
npm install @ekwo-ai/factur-x
```

## 使用量

```ts
import { generateCiiXml, computeTotals } from '@ekwo-ai/factur-x';
import { embedFacturX, extractFacturX } from '@ekwo-ai/factur-x/pdf';

const invoice = {
  number: 'INV-2026-0042',
  issueDate: '2026-03-31',
  dueDate: '2026-04-30',
  seller: {
    name: 'Exemple Conseil SA',
    vatId: 'BE0123456749',
    legalId: { scheme: '0208', value: '0123456749' },   // Belgian enterprise number
    address: { line1: "Rue de l'Exemple 1", postalCode: '1000', city: 'Bruxelles', country: 'BE' },
  },
  buyer: {
    name: 'Société Fictive SAS',
    vatId: 'FR12345678901',
    legalId: { scheme: '0002', value: '345678901' },    // SIREN
    address: { line1: '10 avenue des Tests', postalCode: '75001', city: 'Paris', country: 'FR' },
  },
  buyerReference: 'SERVICE-EXEC-42',
  lines: [
    { name: 'Consulting days', quantity: 3, unitCode: 'day', unitPrice: 950, vatRate: 0 },
    { name: 'Software licence', quantity: 1, unitPrice: 1200, vatRate: 0 },
  ],
  payment: { iban: 'BE71 0961 2345 6769' },
};

const xml = generateCiiXml(invoice);                       // BASIC profile
const totals = computeTotals(invoice);                     // { lineTotal, taxTotal, grandTotal, duePayable, breakdown }

const pdf = await embedFacturX(visualPdfBytes, xml, { title: 'Invoice INV-2026-0042' });
const back = await extractFacturX(pdf);                    // { filename: 'factur-x.xml', xml }
```

`npm run example` 运行 [`examples/basic.ts`](https://npmcn.com/package/%40ekwo-ai/factur-x/examples/basic.ts) 结束到结束.

### 增值税类别

每一行带一个 `vatRate`。该类别(BT-151)在不声明时产生: 积极比率 − `S`; 国内零率 `Z`;对欧洲联盟另一成员国具有增值税标识的企业的零税率 + `K` (成员国之间的供应);对那里没有供应的买方) `E`(欧洲联盟以外) `G`设置 `vatCategory` 要覆盖的线上( o)`AE` 反向电荷, `O` 不受增值税约束.). 免刑小组 理由文本(BT-120, 以 `invoice.exemptionReasons`VATEX 代码 已存在.

### 标识符

| 外地 | 示例 | XML 数据 |
| --- | --- | --- |
| `vatId` | `BE0123456749`, (中文(简体) ), `FR12345678901` | `SpecifiedTaxRegistration/ID[@schemeID="VA"]` |
| `legalId` | `{ scheme: '0208', value: '0123456749' }` (贝), `{ scheme: '0002', value: '345678901' }` (法语) | `SpecifiedLegalOrganization/ID[@schemeID]` |
| `buyerReference` | 法语“服务执行人”代码 | `BuyerReference` (BT-10级) |
| `orderReference` | 定购单 | `BuyerOrderReferencedDocument` (BT-13级) |

### 单位

`unitCode` 接受联合国/欧洲经委会建议20的编码`HUR`, (中文(简体) ), `DAY`, (中文(简体) ), `KWH`...)或日常活动 法语、荷兰语、英语或德语(`heures`, (中文(简体) ), `dagen`, (中文(简体) ), `m²`, (中文(简体) ), `Stück`) (中文(简体) ). 未知数值下降 返回到 `C62` (单位). 见 `UNIT_CODES` 财务报告和审定财务报表 `toUnitCode`。 。 。 .

## API 密码

| 导出 | 说明 |
| --- | --- |
| `generateCiiXml(invoice, { profile?, businessProcess? })` | CII XML 字符串. |
| `computeTotals(invoice)` | 增值税细目和文件总额(BT-106.BT-117). |
| `defaultVatCategory`, (中文(简体) ), `EXEMPTION_REASON_CODES`, (中文(简体) ), `DEFAULT_EXEMPTION_REASONS` | 增值税帮手. |
| `toUnitCode`, (中文(简体) ), `UNIT_CODES` | 单位帮手. |
| `buildXmpMetadata`, (中文(简体) ), `CONFORMANCE_LEVELS`, (中文(简体) ), `GUIDELINES`, (中文(简体) ), `DOCUMENT_TYPE_CODES` | 规格的常数. |
| `embedFacturX(pdf, xml, { profile?, title?, creator?, producer?, date? })` _(单位:千美元)`/pdf`(中文(简体) )_ | 返回带有 XML 和 PDF/A-3 XMP 包的新 PDF . |
| `extractFacturX(pdf)` _(单位:千美元)`/pdf`(中文(简体) )_ | `{ filename, xml }` 或者说 `null`。 。 。 . |
| `readCii(xml, { maxBytes?, maxDepth?, maxElements? })` | `{ invoice, violations, profile }`,参见 [阅读](https://npmcn.com/package/%40ekwo-ai/factur-x/#readme-reading)。 。 。 . |
| `readFacturX(pdf, options?)` _(单位:千美元)`/pdf`(中文(简体) )_ | 同样,从PDF读出,与 `filename` 页:1. |
| `InvoiceFileError`, (中文(简体) ), `profileOf`, (中文(简体) ), `checkReceived`, (中文(简体) ), `isValidIban`, (中文(简体) ), `CREDIT_NOTE_TYPE_CODES` | 阅读所拒绝的, 和它使用的帮助者. |

## 范围和限制

-   津贴和费用(BG-20、BG-21、BG-27、BG-28),带折扣的毛额价格 多项分娩尚未模拟.
-   PDF 部分嵌入了数据,宣布 PDF/A-3 并写入一个同意的 XMP 包 文件信息词典; 它不将视觉 PDF 转换为 PDF/A(fonts, 色彩描述文件,输出意图). 由 PDF 提供 [`@ekwo-ai/invoice-pdf`](https://npmcn.com/package/%40ekwo-ai/invoice-pdf/README.md#pdfa-3) 有它们, VeraPDF 发现没有 失败的 PDF/A-3b 规则已嵌入其中; 用您的工具验证其他 PDF 启动前的平台.
-   每个简介都写出其计划承认的内容: 标题和总数, BASIC WL 整行文件没有线条,BASIC 线条没有卖方的物品 标识符(BT-155)和项目说明(BT-154),从EN 16931开始。 测试 以 Factur-X 1.09 XSD 验证每个配置文件 .
-   运行时没有进行验证,而Schematron规则不是由测试运行的. 对FNFE Factur-X验证器或野马项目等验证器进行测试.

## 阅读

一个供应商以 Factur-X 或 ZUGFERD 身份寄给你的发票变成了普通物品 a 购买稿可以从.

```ts
import { readCii, InvoiceFileError } from '@ekwo-ai/factur-x';
import { readFacturX } from '@ekwo-ai/factur-x/pdf';

const { invoice, violations, profile, filename } = await readFacturX(pdfBytes);
profile;                 // 'minimum' | 'basic-wl' | 'basic' | 'en16931' | 'extended' | null
invoice.kind;            // 'invoice' | 'credit_note', from the type code
invoice.totals.payable;  // '648.40', a decimal as text, never a number

const same = readCii(xmlBytesOrText);   // the XML alone, without pdf-lib
```

-   `readCii(input: string | Uint8Array, options?: ReadOptions): ReceivedCiiFile` 读取 CII D16B (英语) `CrossIndustryInvoice` - Factur-X 1.0, ZUGFERD 2.x, CII中的一款XRechnung——并 返回时 `{ invoice, violations, profile }`。 。 。 .
-   `readFacturX(pdf: Uint8Array | ArrayBuffer, options?: ReadOptions): Promise<ReceivedFacturX>` _(单位:千美元)`/pdf`(中文(简体) )_ 查找附在 PDF 上的 XML 并读取它 `readCii`; 结果 添加 `filename` 它被附着在下面.
-   `profileOf(guideline)` 是配置文件一个准则标识符(BT-24)声明。 一个 EN 16931 计算机辅助系统`urn:cen.eu:en16931:2017#compliant#…`, XRechnung for one)读作: `en16931`; 此软件包不知道的标识符是 `null`,以及 `invoice.customizationId` 保存文件所写的.

**外形为UBL读取器.** `invoice` 是一个 `ReceivedInvoice`类型 `readUbl` 联 合 国 `@ekwo-ai/peppol-ubl` 返回:每个字段将其命名为 EN 16931 商业术语 持有,而一个商业术语在同一领域,无论所携带的语法如何——测试 套接字读出一张用两种语法写成的发票,从两者得到相同的对象. 这个 两种砖块不互相依赖;它们持有文件的字节取字节副本 定义形状、检查、 XML 读取器和小数,并进行测试保存 一样. `syntax` 说哪个读了.

**无事被重算,无事被默认.** 一个图是文件写的文本, 选中为小数; 缺少的元素是 `null` - MINIMUM或BASIC WL文件没有 和没有线总, 回来这样。 EN 16931(BR-CO-10至 BR-CO-17在精确小数下进行核对,并在 `violations`CII 特定 调查结果也存在: `invalid_iban` (单位:千美元) `IBANID` 谁的支票数字失败,仍然 以书面形式返回, `invalid_attachment`, (中文(简体) ), `unsupported_date_format` (a) 日期 102以外的格式,返回为 `null`) (中文(简体) ). CII曾经写过一些东西 文档,UBL按付款方式写——付款参考(BT-83)和 直接借项授权(BT-89)——按各种支付方式退还.

**什么不是发票 扔一个 `InvoiceFileError`** 带有 `code`代码: UBL 读取器`malformed_xml`, (中文(简体) ), `unsupported_encoding`, (中文(简体) ), `doctype_forbidden`, (中文(简体) ), `undefined_entity`, (中文(简体) ), `too_large`, (中文(简体) ), `too_deep`, (中文(简体) ), `too_many_elements`, (中文(简体) ), `not_an_invoice`, (中文(简体) ), `missing_element`, (中文(简体) ), `invalid_value`),加 (中文(简体) ) `not_a_pdf` 财务报告和审定财务报表 `no_embedded_invoice` 从 `readFacturX`除MINIMUM和BASIC WL简介外,需要一条线。 没有生的 xML 解析器或 `pdf-lib` 逃脱。 XML由严格阅读者阅读 软件包本身:没有DOCTYPE,因此没有实体扩展,只有UTF-8,大小,深度和 元素限制.

**限制.**

-   PDF 打开时 `pdf-lib`,已经是 `/pdf` 切入点 : 附件可见于 `EmbeddedFiles` 目录名称树, 在一个下 名称。 仅可从页注释、 和 加密 PDF 和过滤器中的流 `pdf-lib` 不解码不读:它们 以上面的代码之一拒绝, 永远不要读错。 XMP 元数据不读: profile 来自 XML .
-   ZUGFERD 1.0 (英语:`CrossIndustryDocument`,另一个命名空间)作为 `not_an_invoice`。 。 。 .
-   超过EN 16931的ExTEND要素(若干交付,线路分结构.)不是 读取。 CII计划或Schematron计划是无法验证的.

## 发展

```sh
npm install
npm run typecheck
npm test
npm run build
```

## 许可证

[麻省理工学院](https://npmcn.com/package/%40ekwo-ai/factur-x/LICENSE) 埃克沃·艾尔

## 常见问题

### @ekwo-ai/factur-x 是什么？

Factur-X / ZUGFERD TypeScript中的电子发票:EN 16931 CII XML 从平面发票对象,PDF/A-3嵌入和取出\.

### 如何安装 @ekwo-ai/factur-x？

在项目目录运行 npm install @ekwo-ai/factur-x，或使用 pnpm add / yarn add / bun add。

### @ekwo-ai/factur-x 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ekwo-ai/factur-x 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ekwo-ai/factur-x 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ekwo-ai/factur-x 可以商用吗？

@ekwo-ai/factur-x 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ekwo-ai/factur-x 的下载量有多少？

根据 npm 官方下载统计，@ekwo-ai/factur-x 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,197 次，日均约 140 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ekwo-ai/factur-x 还在维护吗？

最新版本 0\.25\.2 发布于 2026/11/13（今天）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/09/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。