ZATCA电子发票报错：哈希不匹配及XSD验证失败求助

一、先处理XML不符合UBL 2.1标准（XSD_ZATCA_INVALID） #

XML格式不规范是触发哈希不匹配的常见诱因，优先解决这个问题：

• 校验XML结构：用ZATCA官方提供的UBL 2.1 XSD schema对XML做校验，推荐使用xmllint命令行工具快速定位问题：

  xmllint --noout --schema zatca_ubl_invoice.xsd your_invoice.xml
  

  重点排查必填字段缺失、格式错误（如日期格式必须为YYYY-MM-DD、数值精度不符合要求）、节点层级错误。
• 核对命名空间：确保XML根节点的命名空间严格为urn:oasis:names:specification:ubl:schema:xsd:Invoice-2，所有子节点的前缀需对应正确的UBL命名空间，禁止自定义未声明的前缀或拼写错误。
• 检查规范更新：ZATCA可能近期调整了UBL规范要求，对比两个月前的成功XML与当前XML，找出新增必填字段或修改的字段规则（如税务登记号格式、发票类型编码）并修正。

二、解决发票哈希不匹配（invalid-invoice-hash） #

XML验证通过后，聚焦哈希计算和请求提交环节：

• 强制XML规范化处理：ZATCA要求哈希计算前必须对XML执行C14N规范化（消除格式差异，保留语义等价），不能直接用原始XML字符串计算。修正Python哈希代码如下：

  from lxml import etree
  import hashlib
  
  def compute_zatca_hash(xml_bytes):
      # 解析XML并应用C14N规范化（无注释、保留命名空间）
      root = etree.fromstring(xml_bytes)
      canonical_xml = root.c14n(with_comments=False, exclusive=False)
      # 计算SHA-256哈希并转大写（ZATCA要求大写格式）
      return hashlib.sha256(canonical_xml).hexdigest().upper()
  

• 核对请求体细节：确保API请求中提交的哈希值是无空格、无换行的大写SHA-256字符串，同时确认请求体中的发票UUID、提交时间等字段与XML内的对应字段完全一致。
• 统一编码格式：确认XML文件以UTF-8编码保存，计算哈希时直接读取UTF-8编码的字节流，避免编码转换导致的哈希值偏差。

内容的提问来源于stack exchange，提问作者Hosen MD Altaf