Register New Device

This is an API for registration of the new device.

Request Method

POST

Request URL

{{BASE_URL}}/api/onboarding/register-device

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

Request Authorization

Parameter	Data Type	Validations and Example	Description
Bearer Token	String		Mandatory

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	EVS-1234567890-312345678912343	Mandatory. Name or Asset Tracking Number used by the taxpayer for the Solution Unit being onboarded.
EgsSerialNumber	String	1-EVS|2-EVS|3-da28a417-4018-4257-829d-12d41410c9c3	Mandatory. Manufacturer or Solution Provider Name, Model or Version and Serial Number.
Location	String	JBRA6534	Mandatory. The address of the Branch or location where the device or solution unit is primarily situated
Industry	String	IT	Mandatory. Industry or sector for which the device or solution will generate invoices.
InvoiceType	String	1100	Mandatory. 1000 for B2B, 0100 for B2C, 1100 for Both.
Otp	String	123456	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	312345678912343	Mandatory. OrganizationIdentifier Registration Number. 15 digits, starting and ending with 3
OrganizationName	String	Evincible Solutions	Mandatory. Taxpayer/Organization Name.
OrganizationUnitName	String	Jeddah branch	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	SA	Mandatory. Country Code.

Sample Request

{
    "DeviceDetails": {
        "CommonName": "EVS-3111337109-3xxxxxxxxxxxxx3",
        "EgsSerialNumber": "1-EVS|2-EVS|3-1d26e99e-9ade-4e15-87e0-43b1591d6e35",
        "Location": "JBRA6534",
        "Industry": "IT",
        "InvoiceType": "1100",
        "Otp": "123456"
    },
    "OrganizationDetails": {
        "OrganizationIdentifier": "3xxxxxxxxxxxxx3",
        "OrganizationName": "Evincible Solutions",
        "OrganizationUnitName": "Jeddah Branch",
        "CountryCode": "SA"
    }
}

Response Status Codes

HTTP Status Code	Description
200	For a successful Device Id 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.

Response Schema

Parameter	Data Type	Description
Status	String	Mandatory
DeviceId	String	Mandatory
ErrorList	Array	optional
ErrorList.ErrorCode	String	optional
ErrorList.ErrorMessage	String	optional
ErrorList.ErrorSource	String	optional

Sample Response

Success - HTTP Status Code - 200

{
    "status": "GENERATED",
    "deviceId": "DFF3195F-37A9-4415-AB2B-64C4B5FB7338",
    "errorList": null
}

Error - HTTP Status Code - 400

{
    "status": null,
    "deviceId": null,
    "errorList": [
        {
            "errorCode": "Invalid-OTP",
            "errorMessage": "The provided OTP is invalid",
            "errorSource": "Zatca Error"
        }
    ]
}

Error - HTTP Status Code - 401

{
    "status": null,
    "deviceId": null,
    "errorList": [
        {
            "errorCode": "100401",
            "errorMessage": "Invaild Vat or Invoice type",
            "errorSource": "EVS_Engine"
        }
    ]
}

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 name or vat number and password. If it is not present or is invalid, the API will return HTTP Status Code 400.

2. If the user name and password is valid, but the user does not have the authorization to generate Invoice, 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.