> For the complete documentation index, see [llms.txt](https://docs.docbits.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docbits.com/chinese/guan-li-yu-she-zhi/settings/document-processing/module/bar-code-qr-code-extraction/zatca-fatoora.md).

# ZATCA Fatoora（沙特阿拉伯）

## 概述

**ZATCA Fatoora** 是沙特阿拉伯天课、税务与海关管理局（Zakat, Tax and Customs Authority）规定的电子发票二维码。自 **2021 年 12 月（第一阶段）** 起，沙特境内开具的每张 B2C 发票都必须包含 Fatoora 二维码，其中包含五项核心发票字段；自 **2023 年 1 月（第二阶段）** 起，二维码还需包含加密签名封装。DocBits 可解码这两个阶段的二维码，并将第一阶段的所有付款字段作为具名属性返回到文档 API 响应中。

### 功能概述

ZATCA Fatoora 使用 **二进制 TLV** 格式（1 字节标签 ID、1 字节长度、值），并以 **Base64** 封装。所有文本均采用 UTF-8 编码，因此阿拉伯语供应商名称可以正确解码。提取器会将第一阶段的标签 1–5 提取为结构化字段；如果存在第二阶段的标签 6–9，则会将其提取为 Base64 字符串，供下游合规工具使用。**签名和哈希验证不在此功能范围内**；这类验证应由专用电子发票合规系统处理。

#### 主要优势

* **覆盖强制合规要求**：解析每张沙特 B2C 发票。
* **支持阿拉伯语**：UTF-8 供应商名称在往返过程中无需重新编码。
* **支持第一阶段和第二阶段**：可检测两个阶段，并在输出中标明阶段。
* **保留第二阶段封装**：保留哈希、签名、公钥和证书签名的 Base64 字符串，供合规工具使用。

***

### 检测

* Base64 封装的二进制 TLV（标签 1–9，1 字节标签 ID + 1 字节长度 + 值）
* 阶段检测：仅包含标签 1–5 时，`zatca_phase = 1`；同时包含标签 6–9 时，`zatca_phase = 2`

### TLV 标签布局

| 标签 | 阶段 | 内容                  |
| -- | -- | ------------------- |
| 1  | 1  | 供应商名称（UTF-8，支持阿拉伯语） |
| 2  | 1  | 增值税登记号              |
| 3  | 1  | 发票时间戳（ISO 8601）     |
| 4  | 1  | 发票总额                |
| 5  | 1  | 增值税总额               |
| 6  | 2  | XML 发票哈希（Base64）    |
| 7  | 2  | 数字签名（Base64）        |
| 8  | 2  | 公钥（Base64）          |
| 9  | 2  | 证书签名（Base64）        |

### 提取的字段

所有字段均使用 `zatca_` 前缀：

| 字段                            | 描述                       |
| ----------------------------- | ------------------------ |
| `zatca_seller_name`           | 供应商名称（UTF-8）             |
| `zatca_vat_number`            | 增值税登记号                   |
| `zatca_invoice_timestamp`     | 发票日期/时间                  |
| `zatca_invoice_total`         | 发票总额（小数）                 |
| `zatca_vat_total`             | 增值税总额（小数）                |
| `zatca_phase`                 | `1`（第一阶段）或 `2`（第二阶段）     |
| `zatca_invoice_hash`          | XML 发票哈希——仅第二阶段提供，Base64 |
| `zatca_signature`             | 数字签名——仅第二阶段提供，Base64     |
| `zatca_public_key`            | 公钥——仅第二阶段提供，Base64       |
| `zatca_certificate_signature` | 证书签名——仅第二阶段提供，Base64     |

{% hint style="info" %}
**不在此功能范围内**：DocBits 不会验证加密签名、哈希或证书链。此类验证属于专门的合规工作，应由获得 ZATCA 认证的电子发票系统处理。
{% endhint %}

### API 响应示例（第一阶段）

```json
{
  "zatca_seller_name": "شركة أكمي التجارية",
  "zatca_vat_number": "300123456700003",
  "zatca_invoice_timestamp": "2026-04-24T10:00:00",
  "zatca_invoice_total": 115.00,
  "zatca_vat_total": 15.00,
  "zatca_phase": 1
}
```

***

### 如何启用

ZATCA Fatoora 解析由通用 **条码 / 二维码提取** 模块开关控制，无需针对特定标准进行配置。

1. **前往设置**：
   * 从仪表板进入 **Settings**。
   * 选择 **Document Processing**，然后选择 **Module**。
2. **启用功能**：
   * 向下滚动，找到 **Bar-Code / QR Code Extraction** 选项。
   * 切换滑块以启用该功能。

如需查看付款二维码标准的完整列表，请参阅[概述](/chinese/guan-li-yu-she-zhi/settings/document-processing/module/bar-code-qr-code-extraction.md)页面。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.docbits.com/chinese/guan-li-yu-she-zhi/settings/document-processing/module/bar-code-qr-code-extraction/zatca-fatoora.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.