如何将Zatca Fatoora Portal Phase 2集成至Dynamics AX或D365？求实施步骤

前置准备 #

• 完成Zatca Phase 1全流程配置（E-Invoice门户注册、数字证书获取等）
• 熟悉目标Dynamics系统的发票生成逻辑（AX2012的应收模块，D365的财务模块）
• 获取Zatca官方提供的Phase 2 Invoice XML Schema（XSD文件）

1. 创建合规Invoice XML文件 #

Zatca Phase 2的XML必须严格遵循其XSD规范，核心必填字段包括：

• 发票核心信息：发票编号、开票时间（精确到秒）、交易币种、总金额、总税额
• 交易双方信息：买卖双方的VAT税号、法定名称、注册地址、联系方式
• 商品/服务明细：SKU、名称、数量、单价、适用税率、税额
• 合规标识字段：UUID、Hash Value（后续步骤生成）

Dynamics中实现方式 #

• AX2012：
  1. 扩展SalesInvoiceHeader和SalesInvoiceLine表，添加Zatca专属字段（如UUID、HashValue）
  2. 修改SalesInvoiceReport的数据源，关联新增字段，通过XSLT转换或X++代码拼接生成符合格式的XML
• D365：
  1. 利用电子申报（ER）工具，导入Zatca官方提供的ER配置模板
  2. 映射Dynamics发票实体字段到XML的对应节点，通过ER引擎自动生成合规XML

2. 生成UUID #

UUID需符合RFC 4122版本4标准，每个发票对应唯一ID，不可重复。

• AX2012：在X++代码中调用System.Guid::NewGuid().ToString()生成，直接写入XML的UUID节点和发票表字段
• D365：在ER配置中使用内置GUID函数，或在自定义C#代码中调用Guid.NewGuid().ToString()

3. 计算Hash Value #

Hash值是Zatca验证发票完整性的核心，计算步骤如下：

1. 压缩XML：移除生成的Invoice XML中所有空格、换行符、缩进，得到无格式纯XML字符串
2. 哈希计算：使用SHA-256算法对压缩后的字符串进行哈希运算
3. 编码转换：将哈希结果转换为Base64编码，即为最终的Hash Value

Dynamics中实现方式 #

• AX2012：

  str compressedXml = strReplace(strReplace(strReplace(xmlContent, '\n', ''), '\r', ''), ' ', '');
  System.Byte[] hashBytes = Cryptography::sha256Hash(System.Text.Encoding::UTF8.GetBytes(compressedXml));
  str hashValue = System.Convert::ToBase64String(hashBytes);
  

• D365：
  在ER配置中使用Hash函数并选择SHA-256算法；或在自定义服务中通过System.Security.Cryptography.SHA256类实现压缩、哈希、编码流程

4. 完整集成流程 #

触发逻辑 #

当Dynamics中销售发票过账完成后，自动触发Zatca Phase 2集成流程：

1. 从Dynamics发票表提取所有必填数据
2. 生成嵌入UUID和Hash Value的合规XML
3. 调用Zatca Phase 2 API（测试/生产环境接口）提交XML
4. 接收Zatca返回的回执（包含QR Code数据、状态码），将回执信息存储到Dynamics发票附加字段
5. 在发票打印/预览页面嵌入QR Code（将返回的QR Code数据转换为图片渲染）

关键注意事项 #

• AX2012需开发自定义服务调用Zatca API，可使用System.Net.WebRequest类实现HTTP请求
• D365可利用OData服务或自定义插件完成API调用，同时通过ER模板实现QR Code的打印集成

5. 测试与验证 #

• 使用Zatca沙箱环境完成全流程测试
• 用Zatca官方XSD校验工具验证XML格式合规性
• 对比手动计算的Hash值与代码生成结果，确保一致性
• 确认Zatca门户可查询到提交的发票数据，回执状态为成功

内容的提问来源于stack exchange，提问作者arif hussain