BR-CL-KSA-14QR code is longer than 1000 characters
Mutabiq checks Saudi ZATCA Phase 2 e-invoice XML before you submit it: pre-validation against published ZATCA requirements, not an approval by the authority. This page explains one rule, BR-CL-KSA-14.
Five checks a month on the Free plan. The file is checked in memory and is never stored.
The message ZATCA prints
[KSA-14]Field character limit for QR Code field has been exceeded. The maximum character limit for this field is 1000 characters.
Also cited in this report
BR-KSA-27
[BR-KSA-27]-The document must contain a QR code (KSA-14), and this code must be base64Binary.
What Mutabiq reports
One entry for each way this rule can be reported.
Reported as
What kind of value was found — empty, not_15_digits and the like — never the value itself.
QR code is longer than 1000 characters
Reported aslonger_than_1000longer than 1000 characters
What is wrong
The QR code field (KSA-14) - the text of cbc:EmbeddedDocumentBinaryObject in the cac:AdditionalDocumentReference whose ID is QR - is more than 1000 characters long, and ZATCA rejects the document under BR-CL-KSA-14. The length is counted on the value exactly as written, so whitespace inside it counts. Earlier releases of ZATCA's checker set the limit at 500; the current release accepts up to 1000.
What to check in your ERP
A signed simplified invoice's QR carries the signature, the public key and the stamp's signature besides the five invoice fields, and it normally fits within 1000 characters. When it does not, look first at the seller name in tag 1, which is often the longest field, and then at line breaks or spaces the export writes inside the base64 value: the payload must be one unbroken base64 string.
QR code element is empty
Reported asemptypresent but empty
What is wrong
The QR code field (KSA-14) exists but holds no characters at all, and ZATCA rejects the document under BR-CL-KSA-14, which requires the field to be between 1 and 1000 characters long. An element holding only spaces is not empty by this measure, because its length is counted as written; BR-KSA-27 reports that case on a simplified invoice.
What to check in your ERP
An empty QR element usually means the export writes the reference block before the QR has been generated, or writes the block for a document it never generates a QR for. If the document should carry a QR, generate it before the XML is written; if your process does not produce one for this document, leave the whole cac:AdditionalDocumentReference for QR out rather than writing it empty.
QR code is longer than 500 characters
Reported aslonger_than_500longer than 500 characters
What is wrong
The QR code field (KSA-14) — the text content of cbc:EmbeddedDocumentBinaryObject inside the cac:AdditionalDocumentReference whose id is QR — is more than 500 characters long. Only rule packs before 2.0.0 report this: SDK 3.0.8's BR-CL-KSA-14 set the ceiling at 500 characters, and its message read: field character limit for QR field has been exceeded, the maximum limit for this field is 500. In SDK 3.4.8, which rule pack 2.0.0 reads, the same rule allows up to 1000 characters (KSA:379-380), so a QR code of 501 to 1000 characters passes, a longer one is reported as longer than 1000 characters, and a report produced under 2.0.0 never carries this note. Two things about the rule held under 3.0.8 and still hold: it applies to every invoice, standard and simplified alike, and the length is measured on the value exactly as written, so whitespace inside it counts. Under 3.0.8 the published Detailed Technical Guideline, which gives the field up to 700 characters, disagreed with the checker, and the checker's 500 was the number that decided.
What to check in your ERP
A QR code of 501 to 1000 characters is no longer refused, so a document this note was raised on may pass as it stands under rule pack 2.0.0: check it again before changing anything. If the payload is longer than you expect, the causes are the same as before. The payload is base64 of the tag-length-value sequence, and base64 is about a third longer than the bytes it encodes. The seller name at tag 1 is often the longest field: send the registered name and nothing after it, bearing in mind that Arabic costs two bytes per letter in UTF-8 where English costs one. On a signed document tags 6 to 9 carry the hash, the signature, the public key and the stamp signature, which are fixed sizes you cannot trim. And an XML writer that wraps the base64 across several indented lines adds line breaks and spaces that count toward the limit. Fix it in the QR generator or the export template inside your e-invoicing module, not by cutting characters off the encoded value, which would make the QR unreadable.
The clause that runs
Quoted from the validation-rule stylesheet ZATCA publishes, at the file and line named below. The executed guard is what the check runs; the reported test is what it prints when it fails, and the two are not always the same.
Executed guard
exists(cac:AdditionalDocumentReference[normalize-space(cbc:ID) = 'QR']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject) and (string-length(cac:AdditionalDocumentReference[normalize-space(cbc:ID) = 'QR']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject) > 1000 or string-length(cac:AdditionalDocumentReference[normalize-space(cbc:ID) = 'QR']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject) < 1)
Reported test
exists(cac:AdditionalDocumentReference[normalize-space(cbc:ID) = 'QR']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject) and (string-length(cac:AdditionalDocumentReference[normalize-space(cbc:ID) = 'QR']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject) > 1000 or string-length(cac:AdditionalDocumentReference[normalize-space(cbc:ID) = 'QR']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject) < 1)
As shipped in ZATCA SDK 3.4.8: the copy quoted here is, byte for byte, the file that release ships. The date in the file name is the name ZATCA gives the file; the rules in it are those of SDK 3.4.8.
A worked example
A synthetic document from the measured test corpus that trips this rule, shown where it differs from one that passed. Mutabiq's report names the class of the value, never the value itself.