BR-KSA-03 📑 Invoice Types & Structure error

BR-KSA-03: Invalid Universally Unique Identifier (UUID / KSA-1)

BR-KSA-03: المعرف الفريد العالمي غير صالح (UUID / KSA-1)

Official ZATCA Specification:

The invoice must contain a unique identifier ('UUID') (KSA-1) given by the machine that issued the document. This value must contain only letters, digits, and dashes (RFC 4122 standard).

XPath Context: /ubl:Invoice/cbc:UUID

📌 Overview & Impact

The invoice must contain a valid UUID (KSA-1) conforming to RFC 4122 standard (letters, digits, dashes).

الوصف بالعربية: يجب أن تحتوي الفاتورة على معرّف فريد عالمياً (UUID) وفق معيار RFC 4122 يحتوي على أحرف وأرقام وشرطات فقط.

⚠️ Common Causes for Rejection

  • ✕ Missing <cbc:UUID> element in the invoice XML root
  • ✕ UUID format does not conform to RFC 4122 (8-4-4-4-12 hex digits with hyphens)
  • ✕ UUID contains special characters, spaces, or invalid casing
  • ✕ Reusing an identical UUID across multiple distinct invoices on the same EGS

✅ How to Fix & Resolve

1

Generate RFC 4122 Version 4 UUID

Use a compliant UUID v4 generator (e.g. crypto.randomUUID() in Node.js or java.util.UUID.randomUUID()).

2

Verify Regex Pattern

Validate that the UUID string matches ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$.

3

Place Under Invoice Root

Insert the <cbc:UUID> element immediately following <cbc:ID> in the UBL 2.1 invoice XML.

💻 Code Comparison: Invalid vs Compliant UBL 2.1 XML

❌ Invalid XML (Rejected by ZATCA) Invalid Payload 
<!-- Missing or malformed UUID -->
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>INV-2026-001</cbc:ID>
  <cbc:UUID>12345-INVALID-UUID</cbc:UUID>
</Invoice>
✓ Valid XML (Compliant UBL 2.1) Valid Payload 
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>INV-2026-001</cbc:ID>
  <cbc:UUID>9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d</cbc:UUID>
  <cbc:IssueDate>2026-08-29</cbc:IssueDate>
</Invoice>

Verify Your Invoice XML Online

Use Qeemah's free developer tools to inspect transforms, C14N digests, and Phase 2 QR codes.

Inspect XML & Hash → Decode QR Code →

❓ Frequently Asked Questions

Can I regenerate the UUID if ZATCA rejects the invoice?

If an invoice is rejected by ZATCA clearance/reporting API, you must fix the error and generate a new sequential invoice or credit note according to your system's chaining rules.

🔗 Related ZATCA Rules

BR-KSA-04

BR-KSA-04: Invoice Issue Date Cannot Be in Future

The document issue date (BT-2) must be less than or equal to the current server date (KSA timezone AST / UTC+3).

BR-KSA-05

BR-KSA-05: Invalid Invoice Type Code (BT-3)

Invoice type code must be one of the agreed UN/CEFACT 1001 codes: 388 (Tax Invoice), 381 (Credit Note), 383 (Debit Note), or 386 (Prepayment).

BR-KSA-06

BR-KSA-06: Invalid Invoice Transaction Subtype Code (NNPNESB / KSA-2)

The invoice transaction code (KSA-2) must exist in @name attribute of InvoiceTypeCode and respect the 7-digit NNPNESB structure.

Stop Fighting Cryptic ZATCA XML Errors

Qeemah handles Phase 2 e-invoicing, cryptographic signing, and real-time clearance automatically. Integrate in minutes.

Start Free Trial Now → Browse All ZATCA Error Codes