@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 返回 - 见 阅读。 。 。 .
• 总数你可以信任. 每个类别和税率一个增值税类别,按四舍五入计算增值税 基础、预付款项、参考原始发票的信用证.
• XML 部分的零依赖性; pdf-lib 仅用于PDF部分(分出入口).

安装

npm install @ekwo-ai/factur-x

使用量

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 结束到结束.

增值税类别

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

标识符

单位

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

API 密码

范围和限制

• 津贴和费用(BG-20、BG-21、BG-27、BG-28),带折扣的毛额价格 多项分娩尚未模拟.
• PDF 部分嵌入了数据,宣布 PDF/A-3 并写入一个同意的 XMP 包 文件信息词典; 它不将视觉 PDF 转换为 PDF/A(fonts, 色彩描述文件,输出意图). 由 PDF 提供 @ekwo-ai/invoice-pdf 有它们, 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 购买稿可以从.

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在精确小数下进行核对,并在 violationsCII 特定 调查结果也存在: 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计划是无法验证的.

发展

npm install
npm run typecheck
npm test
npm run build

许可证

麻省理工学院 埃克沃·艾尔