约旦电子发票 JoFotara 对接
不必更换会计系统，也不必重复录入发票。我们构建一个合规层，位于你的系统与所得税 与销售税总局之间，由它负责 UBL 2.1、压缩、编码、密钥管理与错误信息。
对接实际如何运作
国家系统在发票开出的瞬间接收并予以认证，返回参考号、UUID 和二维码。发票既不是 PDF 也不是图片 —— 而是按 UBL 2.1 标准组织的 XML 文件。你打印给客户的，只是该文件的 视觉呈现。
1. 你的系统
ERP、会计系统、POS 或在线商店。它仍是销售数据的唯一真实来源，除了在发票确认时 增加一次调用之外，内部无需任何改动。
2. 合规层
字段预校验、UBL 2.1 构建、压缩、Base64 编码、按正确请求头发送，以及每次调用的 审计记录。
3. 总局的响应
带参考号、UUID 和二维码的认证结果 —— 或在该次调用的响应中返回，或在状态稍后 变更时通过签名 Webhook 推送。
官方 Portal 用户指南所描述的完整对接流程，发布在 国家对接与 ERP 页面， 字段与错误参考则见 API 文档。
Client-Id 与 Secret-Key
程序化对接依赖总局签发给你企业的两个密钥，随每次请求在请求头中传输。在此之前，企业 必须持有有效税号并已在电子税务门户登记，电子发票账户再从门户内部创建。
| 密钥 | 请求头 | 作用 |
|---|---|---|
| Client Id | Client-Id | 向系统标识你的企业。 |
| Secret Key | Secret-Key | 证明请求确实来自你。须严格保密。 |
发票必填字段
缺少其中任何一项，发票都会被拒 —— 与金额是否正确无关。
| 字段 | 在 UBL 中的位置 | 实务提示 |
|---|---|---|
| 发票号 | cbc:ID | 在你企业内唯一，且不得重复使用。 |
| 唯一标识 | cbc:UUID | 每张发票生成一个（UUID v4）。 |
| 开票日期 | cbc:IssueDate | 只接受 YYYY-MM-DD 格式。 |
| 发票类型与付款方式 | cbc:InvoiceTypeCode | 两者必须相互匹配 —— 见下节。 |
| 卖方税号 | cac:PartyTaxScheme | 须与总局登记信息一致。 |
| 收入来源序列 | cac:SellerSupplierParty | 最常被遗漏的字段，也是反复出现的拒收原因。 |
| 买方信息 | cac:AccountingCustomerParty | 名称始终必填；税号视交易类型而定。 |
| 发票明细 | cac:InvoiceLine | 至少一条数量大于零的明细行。 |
| 合计金额 | cac:LegalMonetaryTotal | 保留三位小数 —— 不是两位。 |
255.200 而非
255.20。对来自美元或欧元体系的团队，四舍五入到两位是反复出现的拒收
原因，因为合计金额会与明细行之和无法对平。
发票类型与付款方式代码
这里是最常见错误的发生地。两个代码并非彼此独立： 允许的付款方式取决于单据类型。
| 单据类型 | 代码 | 允许的付款方式 |
|---|---|---|
| 税务发票 | 388 | 011 现金 · 021 赊账 |
| 贷记通知单 / 退货 | 381 | 013 现金退货 · 023 赊账退货 |
388 绝不与 013 或 023 搭配，
381 也绝不与 011 或 021 搭配。其他任何组合
在发送时即被立刻拒收，因此最好在校验层拦截，根本不让它到达总局。
UBL 2.1 与 XML 实务
UBL（Universal Business Language）是以 XML 表示商业单据的国际标准，约旦系统采用的 是 2.1 版。你不需要背下它，但理解其结构有助于读懂错误信息。一张发票由四个区块 构成：单据头、交易方、明细行、合计。
<Invoice>
<cbc:ID>INV-2026-0418</cbc:ID>
<cbc:UUID>8f3c1e42-…</cbc:UUID>
<cbc:IssueDate>2026-04-18</cbc:IssueDate>
<cbc:InvoiceTypeCode name="011">388</cbc:InvoiceTypeCode>
<cac:AccountingSupplierParty> <!-- 卖方 -->
<cac:AccountingCustomerParty> <!-- 买方 -->
<cac:SellerSupplierParty> <!-- 收入来源序列 -->
<cac:InvoiceLine> <!-- 每个品项一行 -->
<cac:LegalMonetaryTotal> <!-- 合计 -->
</Invoice>税额按明细行计算，而非按整张发票
约旦销售税普遍税率为 16%，并视货物或服务性质存在优惠税率、免税及零税率项目。
计税基数 = (数量 × 单价) − 折扣
税额 = 计税基数 × (税率 ÷ 100)
行合计 = 计税基数 + 税额
// 示例：2 × 120，折扣 20，税率 16%
// 基数 = 220，税额 = 35.200，合计 = 255.200
零税率与免税明细须以不同税目发送（用 Z 而非 S），并附免税
原因。应税与免税明细可以出现在同一张发票上，合计金额必须准确反映这一点。
发票被拒的原因
| 原因 | 表现形式 | 修复 |
|---|---|---|
| 发票类型与付款方式冲突 | 发送时立刻被拒 | 遵循上方代码表。 |
| 缺少收入来源序列 | 错误指向 SellerSupplierParty | 将序列写入卖方静态数据。 |
| 四舍五入到两位小数 | 合计金额无法对平 | 按三位小数计算并发送。 |
| XML 未压缩 | 单据格式错误 | 先压缩，再做 Base64 编码。 |
| 发票号重复 | 按重复拒收 | 使用唯一序列，不重复使用号码。 |
其中四项可由预校验拦截，根本不会到达总局。附总局错误代码及其翻译的完整错误表， 发布在 国家电子发票系统指南。
二维码与发票验证
发票被接受后，系统返回二维码，你将其置于打印件或 PDF 上，任何人都可扫码确认发票 确已登记且金额未被改动。实务上这意味着两点：在收到接受响应之前不要打印发票，因为 此前二维码并不存在；并且要把二维码与发票记录一并留存 —— 它是单据的一部分，不是 装饰。
我们对接的系统
均为已验证的对接模式。若你的系统不在列表中，仅凭接口本身也足够。
Odoo
模块在发票确认时捕获并发送，随后把参考号与二维码写回同一条记录。
SAP / S4HANA
通过消费 IDoc 或 OData 的中间层对接，并集中映射卖方字段。
Microsoft Dynamics
挂接在发票过账事件上，状态回写至 Dynamics 内的自定义字段。
WooCommerce / Shopify
订单完成时自动开具电子发票，并将发票链接发送给客户。
POS 与餐饮系统
成交瞬间发送，二维码直接打印在小票上。可配合 Codexal POS。
会计与自研系统
任何能发出 HTTPS 请求的系统都能对接 —— 包括内部自研系统与会计事务所。
上述产品名称为其各自所有者的商标，此处仅用于说明技术兼容性。
常见问题
如何通过 API 将我的会计系统对接约旦国家电子发票系统（JoFotara）？
程序化对接需要三样东西：国家门户上的纳税人账户、由管理员账户在「设备绑定」界面签发的一对密钥（Client-Id 与 Secret-Key），以及一个按 UBL 2.1 标准构建 XML 发票、压缩并进行 Base64 编码后发送的层。你不需要更换现有会计系统：该层位于你的系统与税务总局之间，销售数据的唯一真实来源仍然是你的系统。
JoFotara 发票有哪些必填字段？
发票号（cbc:ID，必须唯一）、UUID、YYYY-MM-DD 格式的开票日期、发票类型代码及与之匹配的付款方式、卖方税号、收入来源序列、买方信息、至少一条数量大于零的明细行，以及保留三位小数的合计金额。缺少任一字段都会导致发票被拒，与金额是否正确无关。
什么是收入来源序列，为什么我的发票因它被拒？
收入来源序列标识发票所属的经营活动，在 UBL 中位于 cac:SellerSupplierParty 内。它是首次构建对接时最常被遗漏的字段，也是反复出现的拒收原因。解决办法是将它一次性写入卖方静态数据，使其在每张发票上自动重复，而不是手工填写。
JoFotara 的发票类型与付款方式代码是什么？
税务发票代码为 388，允许的付款方式是 011 现金与 021 赊账。贷记通知单或退货代码为 381，允许的付款方式是 013 现金退货与 023 赊账退货。两个代码并非彼此独立：388 绝不与 013 或 023 搭配，381 也绝不与 011 或 021 搭配。两者不匹配是最常见的错误。
JoFotara 为什么拒收发票，该如何修复？
多数拒收源于五个原因：发票类型代码与付款方式冲突、缺少收入来源序列、金额四舍五入到两位小数而非三位、发送未压缩的 XML，以及重复使用发票号。其中四个可通过预校验拦截，根本不会到达税务总局。
为什么金额必须保留三位小数？
约旦第纳尔可细分为 1000 费尔，因此系统要求三位小数 —— 是 255.200，而不是 255.20。对于来自美元或欧元体系的团队，四舍五入到两位是反复出现的拒收原因，因为合计金额会与明细行之和无法对平。
WooCommerce、Shopify 或 POS 系统能对接 JoFotara 吗？
可以。任何能发出 HTTPS 请求的系统都能对接。已验证的模式涵盖 Odoo、SAP、Microsoft Dynamics、WooCommerce、Shopify 和 POS 系统，以及自研系统。在线商店可在订单完成时自动开票；POS 则在成交瞬间发送，并将二维码直接打印在小票上。
Client Id 和 Secret Key 从哪里获取？
在国家门户账户内的「设备绑定」界面获取，该界面仅对主账户（管理员）开放 —— 子用户只能通过界面整理发票，无法签发对接密钥。两个密钥随每次请求在请求头中传输，等同于你企业的税务签名：持有者可以用你的名义开票并计入你的税务账户，因此切勿通过邮件或即时通讯发送，也不要写入应用或网站代码。
发票会带二维码吗？客户如何验证？
发票被接受后，系统会返回参考号、UUID 和二维码。任何人 —— 你的客户或税务稽查员 —— 都可以扫码确认发票确已登记且金额未被改动。实务上最重要的一点是：在收到接受响应之前不要打印发票，因为此前二维码并不存在。
我的企业是否必须开具电子发票，从何时开始？
约旦的强制要求按批次逐步扩大，你的企业属于哪一批次由所得税与销售税总局根据年营业额、经营性质、销售税登记情况等因素确定。强制日期及逾期罚则会多次修订，因此不要依赖非官方来源的日期：请查阅总局公告或咨询你的税务顾问，确认你所属的具体批次。
一个对接项目需要多久？
典型对接项目需一天到一周，取决于系统复杂度。路径分四步：几分钟内获取沙箱密钥；字段映射，确定每个必填字段在你系统中的位置；对接并针对真实场景测试（普通发票、赊销、带折扣、含免税明细、贷记通知单）；最后用企业自有密钥切换到生产环境。