Request for Clarification on ZATCA Invoice XML Structure

XML and business rules
1

Hi team,

I hope you’re doing well.

I am currently working on generating invoice XMLs in compliance with ZATCA’s requirements. Although my generated XMLs pass the basic XSD validations, I continue to receive the following business rule warning and hash errors:

  • Warning: BR-KSA-EN16931-11
    Invoice line net amount (BT-131) must equal (Invoiced quantity (BT-129) × Item net price (BT-146) / item price base quantity (BT-149)) + Sum of invoice line charge amount (BT-141) - Sum of invoice line allowance amount (BT-136)
  • Errors:
    • invalid-invoice-hash
    • invoiceHash_QRCODE_INVALID

I came across a sample signed invoice (example_invoice.xml) which passes all validations, including the hash and QR code checks. I am very confused about how such invoices are structured and how the hash and signature are correctly calculated.

Could you please guide me on the correct process to generate such an invoice, particularly:

  • How to compute the correct invoice hash and ensure it matches both the API and the QR code.
  • How the invoice line net amount is calculated to avoid the BR-KSA-EN16931-11 warning.
  • Any best practices or tools you recommend for creating valid XML that passes all ZATCA validations.
    {
    “validationResults”: {
    “infoMessages”: [
    {
    “type”: “INFO”,
    “code”: “XSD_ZATCA_VALID”,
    “category”: “XSD validation”,
    “message”: “Complied with UBL 2.1 standards in line with ZATCA specifications”,
    “status”: “PASS”
    }
    ],
    “warningMessages”: [
    {
    “type”: “WARNING”,
    “code”: “BR-KSA-EN16931-11”,
    “category”: “KSA”,
    “message”: “Invoice line net amount (BT-131) must equal (Invoiced quantity (BT-129) * (Item net price (BT-146) / item price base quantity (BT-149))) + Sum of invoice line charge amount (BT-141) - Sum of invoice line allowance amount (BT-136)”,
    “status”: “WARNING”
    }
    ],
    “errorMessages”: [
    {
    “type”: “ERROR”,
    “code”: “invalid-invoice-hash”,
    “category”: “INVOICE_HASHING_ERRORS”,
    “message”: “The invoice hash API body does not match the (calculated) Hash of the XML”,
    “status”: “ERROR”
    },
    {
    “type”: “ERROR”,
    “code”: “invoiceHash_QRCODE_INVALID”,
    “category”: “QRCODE_VALIDATION”,
    “message”: “Invoice xml hash does not match with qr code invoice xml hash”,
    “status”: “ERROR”
    }
    ],
    “status”: “ERROR”
    },
    “reportingStatus”: “NOT_REPORTED”,
    “clearanceStatus”: null,
    “qrSellertStatus”: null,
    “qrBuyertStatus”: null
    }
    i try this on postman i get this error can you please tell me each step with detail and how i do that