Issuing a Production CSID

Overview

Assuming you have completed the previous step and onboarding, you can now generate a production CSID.

Remember to use the binarySecurityToken, secret, and requestID from the last response as your username and password respectively.

Onboarding

If you have not yet completed the onboarding process (which is simply submitting invoices, debit, and credit notes to the compliance endpoint), you will get responses that look like so:

{
  "code": "Missing-ComplianceSteps",
  "message": "The compliance certificate is not done with the following compliance steps yet [standard-compliant,standard-credit-note-compliant,standard-debit-note-compliant,simplified-compliant,simplified-credit-note-compliant,simplified-debit-note-compliant]"
}

NOTE: The steps you are required to complete differ based on the CSR type you chose.

Example

# Extract values from the previous request
username = response["binarySecurityToken"]
password = response["secret"]
compliance_request_id = response["requestID"]

# Construct a client with the username and password
client = ZATCA::Client.new(username: username, password: password)

# Send the request to ZATCA
response = client.issue_production_csid(compliance_request_id: compliance_request_id)

Response will look like so:

# =>
{
  "requestID"=>1111,
  "tokenType"=>"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3",
  "dispositionMessage"=>"ISSUED",
  "binarySecurityToken"=>"REDACTED",
  "secret"=>"REDACTED"
}

The certificate is contained within binarySecurityToken. It's Base64-encoded, and once you decoded you get a cert without the header blocks.

Let's extract it and bring back the PEM headers.

certificate = response["binarySecurityToken"]
decoded_certificate = Base64.strict_decode64(certificate)
pem_certificate = "-----BEGIN CERTIFICATE-----\n#{decoded_certificate}\n-----END CERTIFICATE-----"

# Let's write that to a file
File.write("zatca-issued-certificate.pem", pem_certificate)

So the binarySecurityToken is actually two things.

1. In its untouched form (without decoding or anything), it is the username we will use for future API requests (alongside the secret as the password).
2. When Base-64 decoded and having certificate header blocks around it, it is the PEM certificate we will use alongside our private key to sign invoices with

ZATCA Documentation

This Production CSID is a simulation of ZATCA rootCA moreover it is used to sign einvoice documents and authenticate einvoicing api calls. Specifically, it is sent via the authentication header for those api calls.