Generating a CSR

Overview

Before we can start using ZATCA's API, we need to create a certificate. To create a certificate we need to generate a CSR (Certificate Signing Request).

We will fill the CSR with our organization's info and send it to ZATCA's API. ZATCA will then give us back credentials with which we'll make another API request which will give us our certificate.

1- Get an OTP from Fatoora Portal

1. Login to Fatoora Portal
2. Click Renew Existing Cryptographic Stamp Identifier (CSID)
3. Enter how many OTPs you want to generate
4. Save the OTPs somewhere, we need one of them below

NOTE: These instructions are for the production environment, if you would like to use the simulation environment, please click "Fatoora Simulation Portal-Try it out" after logging in to Fatoora Portal and follow the steps from step 2.

2- Generate a CSR

Note: Please see instructions on how to generate a private key

vat_id = "310000000000000"

# Four digits, each digit acting as a bool. The order is as follows: Standard Invoice, Simplified, future use, future use
invoice_type = "1100"

options = {
  common_name: "The common name to be used in the certificate",
  organization_identifier: vat_id,
  organization_name: "The name of your organization",
  organization_unit: "A subunit in your organization",
  country: "SA",
  invoice_type: invoice_type, 
  address: "Riyadh 1234 Street",
  business_category: "Your business category",

  # The solution provider name
  egs_solution_name: "mrsoolsdk",

  # The model of the unit the stamp is being generated for
  egs_model: "1",

  # If you have multiple devices each should have a unique serial number
  egs_serial_number: "1"
}

# ENSURE THAT YOU USE YOUR OWN PRIVATE KEY by passing private_key_path and private_key_password.
# Otherwise the SDK will generate a passwordless one and delete it (this is only for testing purposes)
# Modes:
# :production (Via Fatoora Portal)
# :sandbox (Via Developer Portal)
# :simulation (Via Fatoora Portal - Simulation)
# For the sandbox set production_mode to false, otherwise set it to true. It is true by default.
private_key_path = "path/to/your/key.pem"
generator = ZATCA::Signing::CSR.new(csr_options: options, mode: :production, private_key_path: private_key_path)

# This is the CSR as PEM
csr = generator.generate

# ZATCA's API expects us to encode the PEM to Base64
csr_base64 = Base64.strict_encode64(csr)

3- Send the CSR to ZATCA to get Credentials from them

# Construct an unauthenticated API client, this is the only endpoint that is unauthenticated.
# Make sure the client environment matches the CSR environment
client = ZATCA::Client.new(username: "", password: "", environment: :simulation)

# Get this OTP from Fatoora portal
otp = "111111" 
response = client.issue_csid(csr: csr_base64, otp: otp)

# Response should look like this
{
  "requestID"=>1111,                                           
  "dispositionMessage"=>"ISSUED",                                       
  "binarySecurityToken"=> "REDACTED",
  "secret"=>"REDACTED",
  "errors"=>nil
}

You need to securely store binarySecurityToken and secret. In future requests you will use binarySecurityToken as the username and secret as the password. You will also need the requestID in the next request.

ZATCA Documentation

This is a compliance CSID (CCSID) that is issued by the einvoicing system as it is a prerequisite to complete the compliance steps. The CCSID is sent in the authentication certificate header in the compliance api calls.

The CSR specification required to perform the Compliance API call is covered in section 4.3 of the Developer Portal user manual.

4- Going Through the Onboarding Process

With this certificate you now have to go through the onboarding process where you must check the compliance of invoices, credit notes, and debit notes to be able to generate a production CSID.

To check what onboarding steps you have left you can use the issue production CSID 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.