saudi-vat-pro

Saudi VAT Pro — ZATCA Phase 2 电子发票

saudivat.pro 为沙特阿拉伯企业自动处理 ZATCA Phase 2 电子发票，适用于 WooCommerce 商店、Shopify 商家，以及通过 REST API 实现的自定义集成。

每笔已付款订单都会生成一张符合 ZATCA 要求的发票。每笔退款都会生成一张贷项通知单。无需开发人员。

---

此仓库包含什么

文件夹	内容
woocommerce-plugin/	GPLv2 WooCommerce 插件——为每笔 WooCommerce 订单自动开具 ZATCA 发票
zatca-qr-helpers/	开源 TLV 编码/解码库，为免费 ZATCA 二维码工具提供支持
docs/	支持指南：ZATCA Phase 2 概览、二维码说明、常见错误
mcp-server/	面向 Claude、Cursor、Windsurf 和其他 AI Agent 的 MCP 服务

---

平台

→ 在 saudivat.pro 免费注册

Saudi VAT Pro 负责处理 ZATCA Phase 2 合规的复杂事务，让您无需操心：

• CSID 入驻——使用免费的 CSID 向导在 5 分钟内生成您的加密印章标识符
• B2B 清算——标准发票在交付前与 ZATCA 实时完成清算
• B2C 申报——简化发票在 24 小时内完成申报
• 贷项通知单——退款会自动生成符合 ZATCA 要求的贷项通知单
• 问题仪表板——以通俗易懂的语言说明每项 ZATCA 拒绝原因，并提供建议的修复方法
• 重试与修复——无需改动代码即可重新提交失败的发票

支持的平台

平台	方式
WooCommerce	此仓库中的插件——安装、输入 API 密钥，即可使用
Shopify	Webhook 集成——详见 saudivat.pro/docs
自定义 / ERP	REST API——参见 API 文档
AI Agent	Saudi VAT Pro MCP——Claude、Cursor、Windsurf 和通用 MCP 客户端

---

AI Agent 与模型上下文协议

Saudi VAT Pro MCP 服务让兼容 MCP 的 AI 助手通过 Saudi VAT Pro API 创建和管理 ZATCA 发票。

{
  "mcpServers": {
    "saudi-vat-pro": {
      "command": "npx",
      "args": ["saudi-vat-pro-mcp"],
      "env": {
        "SAUDI_VAT_PRO_API_KEY": "svp_live_YOUR_KEY_HERE"
      }
    }
  }
}

可用工具涵盖发票列表和详情、标准和简化发票创建、具备幂等性的贷项通知单、失败发票重试与说明、商家详情、仪表板摘要，以及 ZATCA 证书就绪状态。

该服务为 Agent 提供明确的 ZATCA 安全措施：

• 标准 B2B 发票必须包含买方名称、城市和有效的 15 位 VAT 编号
• 提交前会验证 VAT 类别、税率、VATEX 豁免原因和行项目折扣
• 清楚区分沙盒环境和生产环境
• 重试贷项通知单时必须提供幂等键，以防止重复退款
• 每项结果都会显示实际生命周期状态，而不会假定清算或申报已成功

规范链接

• 源码：mcp-server/
• 设置与 API 密钥：saudivatpro.com/docs#aiagents
• npm：saudi-vat-pro-mcp
• 官方 MCP Registry：io.github.Morouna1/saudi-vat-pro

---

免费工具

ZATCA QR 工具

解码并检查任意 ZATCA Phase 1 或 Phase 2 二维码，或根据发票字段生成有效的 Phase 1 二维码。无需注册。

• 粘贴 base64 二维码字符串 → 查看解码后的所有 TLV 字段
• 填写发票字段 → 即时获取有效二维码
• 以通俗易懂的英文显示验证错误
• 下载为 PNG 或复制 base64

TLV 编码/解码逻辑已开源于 zatca-qr-helpers/。

免费 CSID 向导

只需 5 分钟即可获取 ZATCA Cryptographic Stamp Identifier（CSID）——无需账户。按步骤操作：输入 VAT 编号、生成 CSR、从 Fatoora 门户获取 OTP，然后下载证书。

VAT 计算器

即时计算沙特发票的 VAT——支持 15%、5% 和 0% 税率，以及全部四种 VAT 处理类别（S/Z/E/O）。

---

定价

每 10,000 张发票收费 SAR 999——按实际用量付费。

• 60 天免费试用，无需信用卡
• 每个账户可添加不限数量的商户
• 无月费

→ 查看完整定价

---

知识中心

为沙特商户和开发者提供的免费指南：

• ZATCA Phase 2 概览 — 变更内容、受影响对象，以及清关与申报流程
• 二维码详解 — 解码每个 TLV 标签
• 常见 ZATCA 错误 — BR-KSA 错误代码及修复方法
• VAT 类别 S/Z/E/O — 各代码的适用场景
• 标准发票与简化发票 — B2B 与 B2C 选择指南
• 贷项通知单与退款 — 如何正确开具

→ 完整知识中心

---

WooCommerce 插件

woocommerce-plugin/ 文件夹包含 Saudi VAT Pro WooCommerce 集成的完整 GPLv2 源代码。

快速安装：

1. 下载或克隆此仓库
2. 将 woocommerce-plugin/ 文件夹上传到 /wp-content/plugins/saudi-vat-pro-woocommerce/
3. 在 WordPress → 插件中启用插件
4. 前往 WooCommerce → 设置 → Saudi VAT Pro，粘贴从 Saudi VAT Pro 控制面板 获取的 Webhook URL 和 API Key

需要 WooCommerce 7.0+、PHP 8.0+。完整文档：saudivat.pro/docs

---

ZATCA QR 辅助工具（开源）

zatca-qr-helpers/ 文件夹包含一个无依赖的 JavaScript/TypeScript 库，用于编码和解码 ZATCA TLV 二维码。

import { encodeTlvPhaseOne, decodeTlv, validateQr } from './zatca-qr-helpers/index.js';

// Generate a Phase 1 QR code
const base64 = encodeTlvPhaseOne({
  sellerName: 'Riyadh Gadgets Trading Co.',
  vatNumber:  '310000000000006',
  timestamp:  '2024-01-15T10:30:00Z',
  invoiceTotal: '1725.00',
  vatAmount:    '225.00',
});

// Decode any QR string
const parsed = decodeTlv(base64);
parsed.fields.forEach(f => console.log(f.tag, f.label, f.rawValue));

// Validate
const { valid, errors } = validateQr(base64);

完整 API 参考请参阅 zatca-qr-helpers/README.md。

---

支持与问题反馈

• 错误报告：提交问题
• 支持问题：提交支持问题
• 文档：saudivat.pro/knowledge
• 平台支持：saudivat.pro/support

---

许可证

• WooCommerce 插件：GNU GPL v2.0
• ZATCA QR 辅助工具：MIT
• 文档：CC BY 4.0

---

由 Morouna Business Services 构建 • saudivat.pro