Cryptographic stamp (KSA-15) missing from a simplified document

What does this mean?

Who stamps what: a tax invoice (B2B) is sent to the Authority for clearance, and the Authority adds its stamp and QR code and returns the file stamped. A simplified invoice and its notes have no clearance: the Authority's detailed guidelines require the taxpayer's e-invoicing solution to stamp them with the cryptographic stamp identifier (CSID) the Authority issued to it, to include a QR code with nine tags, and then to report them within 24 hours. That is why the rule runs only on a document whose transaction type code (KSA-2) starts with 02 — the simplified invoice and its credit and debit notes. How that code is built is in BR-KSA-06.

What exactly is checked: the executable test in the Authority's SDK is that the document contains a cac:Signature element and that it is not empty. That is UBL's signature reference block, and it carries two fixed values: cbc:ID set to urn:oasis:names:specification:ubl:signature:Invoice, and cbc:SignatureMethod set to urn:oasis:names:specification:ubl:dsig:enveloped:xades. The stamp itself — the XAdES signature with its certificate, the invoice hash and the signature value — lives in the ext:UBLExtensions block at the top of the file, and this rule does not open it.

So the stamp is spread over several checks. Neighbouring rules check the fixed values themselves: BR-KSA-28 the signature information ID, an error; BR-KSA-29 the referenced signature ID, a warning; and BR-KSA-30 the signature method, an error. And whether the signature holds — is the hash the hash of this document, does the signature verify against the certificate — is checked in a separate stage of the Authority's validator, outside these rules, with messages such as wrong invoice hashing and wrong signature Value.

This code is rated a warning in the SDK, so do not read it as permission to send without a stamp: the guidelines require the stamp on a simplified document, and the signature carried in the seventh tag of the QR code does not exist until the document is stamped. The stamp is also a link in the chain: the hash it signs is the hash the next document carries as its previous invoice hash.

Why does it happen?

Ordered from the most common to the least — your cause is most likely the first or the second.

• Assuming the Authority stamps every invoice the way it stamps a tax invoice, and sending the simplified one to the reporting API unstamped.
• Sending the file as it was before signing: the signing function returns a new document, and the code sends the variable that holds the old one.
• The hashing step removes cac:Signature — correctly, for the hash — and the stripped copy is then saved as the final document, so the file goes out with a stamp at the top and without the block this rule looks for.
• Signing invoices but not notes: the simplified credit or debit note goes through another code path that never reaches the signer.
• An empty <cac:Signature/> in the template, meant to be filled by the signer, and never filled.

How to fix it

4 steps, then send the invoice again.

1. 1
   Stamp the simplified document in your system before it leaves

   With the private key of the stamp certificate the Authority issued to the e-invoicing unit that issues the document: compute the hash, sign it, build the stamp block, then build the QR code from the hash and the signature, and only then hand the document to the customer and report it to the Authority within 24 hours. The six steps of computing the hash are in BR-KSA-26.

2. 2
   Write both blocks

   The ext:UBLExtensions block is the first element in the document, holding the signature information and the XAdES signature. The cac:Signature block sits in the body of the document, after the additional document references (ICV, then PIH, then QR) and before the seller party: <cac:Signature><cbc:ID>urn:oasis:names:specification:ubl:signature:Invoice</cbc:ID><cbc:SignatureMethod>urn:oasis:names:specification:ubl:dsig:enveloped:xades</cbc:SignatureMethod></cac:Signature>. Both values are fixed, character for character, and BR-KSA-29 and BR-KSA-30 check them.

3. 3
   Send the signer's output as it is

   The hash is computed over the canonicalised document, and canonicalisation keeps the spaces and line breaks inside the content. So reformatting the file after signing — indentation, new lines — changes what was signed, and the signature check fails even with every block in its place. Store the text that came out of the signer, and send exactly that.

4. 4
   Check the document before you report it

   Three signs are enough: a non-empty ds:SignatureValue inside ext:UBLExtensions, the cac:Signature block with its two values, and a QR code carrying the Phase 2 fields. The last one can be read with the QR code reader, which tells you whether it is a Phase 1 or a Phase 2 code.

This code does not block acceptance, so the invoice you have is compliant. Correct the data so the warnings disappear from future invoices.

Frequently asked questions