Compliance CSID (Certificate)

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 co

Request Method

POST

Request URL

{{BASE_URL}}/api/v1/onboarding/generatecsr

Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.

Request Headers

Parameter	Data Type	Validations and Example	Description
x-evs-auth-token	String		Mandatory. User auth token.
vat	String		Mandatory. VAT or Group VAT of the entity.

Request Body

Parameter	Data Type	Validations and Example	Description
DeviceDetails	Object		Mandatory. Device Details Object
OrganizationDetails	Object		Mandatory. Organization Details Object.

Device Details Object

Parameter	Data Type	Validations and Example	Description
CommonName	String		Mandatory. Name or Asset Tracking Number used by the taxpayer for the Solution Unit being onboarded.
EgsSerialNumber	String		Mandatory. Manufacturer or Solution Provider Name, Model or Version and Serial Number.
Location	String		Mandatory. The address of the Branch or location where the device or solution unit is primarily situated
Industry	String		Mandatory. Industry or sector for which the device or solution will generate invoices.
InvoiceType	String		Mandatory. 1000 for B2B, 0100 for B2C, 1100 for Both.
Otp	String		Mandatory. The one time password generated by the user on the ZATCA. OTP once generated is valid only for 1 hour.

Organization Details Object

Parameter	Data Type		Description
OrganizationIdentifier	String		Mandatory. OrganizationIdentifier Registration Number. 15 digits, starting and ending with 3
OrganizationName	String		Mandatory. Taxpayer/Organization Name.
OrganizationUnitName	String		Mandatory. If Vat is NOT Group Vat, then the branch name of the taxpayer. If Vat is a Group VAT ID, then the 10-digit TIN of the individual group member.
CountryCode	String		Mandatory. Country Code.

Sample Request

{ 
"DeviceDetails":{ 
"CommonName":"ABC-3111111119-311111111100003", 
"EgsSerialNumber":"1-EGS|2-EGS|3-05809ec4-b88e-4c33-a679-44eefa9d6cec", 
"Location":"Jeddah", 
"Industry":"Fashion", 
"InvoiceType":"1100", 
"Otp":"473150" 
}, 
"OrganizationDetails":{ 
"OrganizationIdentifier":"311111111100003", 
"OrganizationName":"ABC Company", 
"OrganizationUnitName":"Jeddah Branch", 
"CountryCode":"SA"
} 
} 

Response Status Codes

HTTP Status Code	Description
200	For a successful CSR/DeviceId generation.
400	For any kind of validation issues.
401	If the user is not authenticated for the operation.
403	If the user is not authorized for the operation.
500	HTTP Internal Server Error. Returned when the service faces internal errors.

Response Schema

Parameter	Data Type	Description
requestID	int	CSR Request Id. Use this for generate PCSID
binarySecurityToken	String	Use this as username for Authorization
secret	String	Use this as password for Authorization
PrivateKey	String	Certificate Private key for invoice signing
Certificate	String	Certificate for invoice signing

Sample Response

Success - HTTP Status Code - 200

{
  "requestID": 1684396684965,
  "binarySecurityToken": "TUlJQ0pUQ0NBY3VnQXdJQkFnSUdBWWd0M2JhbE1B...",
  "secret": "+WpTMThMVVxHN5XdeZokZGtXQkHExmuZ3s8PiRs6v3Y=",
  "PrivateKey": "MHcCAQEEIH2/WCL64Zkb/kbBtPD3waRaMlmvAu4kutu...",
  "Certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUR..."
}

Error - HTTP Status Code - 400

{
    "ErrorCode": "",
    "ErrorMessage": "Invalid country code name, please provide a valid country code name",
    "ErrorSource": "Engine Error"
}

Error - HTTP Status Code - 401

{
    "ErrorCode": "100401",
    "ErrorMessage": "Authentication Failed",
    "ErrorSource": "EVS_Engine"
}

Error - HTTP Status Code - 403

{
  "ErrorCode": "100403",
  "ErrorMessage": "Authorization Failed",
  "ErrorSource": "EVS_Engine"
}

Error - HTTP Status Code - 500

{
    "ErrorCode": "",
    "ErrorMessage": "Invalid country code name, please provide a valid country code name",
    "ErrorSource": "Engine Error"
}

API Validations

1. The VAT for which the device is being registered needs to be already present in Evs Engine before making this API request.

API Constraints

1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.

2. If the auth token is valid, but the user does not have the authorization to generate device ID, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular VAT used in the request.