Register

POST https://apistaging.taxizer.com/v1/Devices/Register

Generates a Device on our server and produces the CSID via ZATCA.

This endpoint is designed for the registration of devices within our system. It handles the generation of a unique Device ID on our server and coordinates with ZATCA to generate the CSID (Cryptographic Stamp Identifier).

Request Body

Parameter	Data Type	Field Validations	Description
DeviceDetails	Object	Mandatory	Device Details Object.
Organization Details	Object	Mandatory.	Organization Details Object.
OTP	string	Mandatory	Should be a valid OTP from fatoora protal.
Environment	string	Enum: Development, Simulation, Production	Development : any string will be accepted as OTP, Simulation, Production: Valid OTP has to be provided
invoiceFormat	string	Enum: Xml, Pdf, Model	Xml,Pdf : invoice hash should be managed before reporting the invoice, Model: invoice hash will be managed from our service.

---

Device Detail Object

Parameter	Data Type	Field Validations	Description
egsSerialNumber	string	Mandatory	unique string identifier assigned to each device.
location	string	Mandatory	The address of the branch or location where the device or solution unit is primarily located.
industry	string	Mandatory	Industry or sector for which the device or solution will generate invoices.
invoiceType	string	RegEx: ^(?!0{4})[01]{2}[00]{2}$	Optional. Describes the types of tax invoices the system supports using a 4-character string "TSXY": T: Standard Tax Invoice (1 = supported, 0 = not supported) S: Simplified Tax Invoice (1 = supported, 0 = not supported) X and Y: Reserved for future use (should always be set to 0 currently) 1000: Supports only Standard Tax Invoices. 0100: Supports only Simplified Tax Invoices. 1100: Supports both Standard and Simplified Tax Invoices.

---

Organization Details Object

Parameter	Data Type	Field Validations	Description
Vat	String	15 digits, starting and ending with 3	VAT or group VAT registration number
OrganizationName	String	Mandatory. Can not be empty	The name of the organization with which the device will be registered.
OrganizationUnitName	String	Mandatory	If the VAT is not a Group VAT, use the branch name of the taxpayer. If the VAT is a Group VAT ID, use the 10-digit TIN of the individual group member.
CountryCode	String	Mandatory, Two-character country code as per ISO 3166-1 Alpha-2 standard	Country Code.

---

Request Example

JSON

{
  "Device": {
    "EgsSerialNumber": "SN123456789",
    "Location": "Headquarters",
    "Industry": "Retail",
    "InvoiceType": "Standard"
  },
  "Organization": {
    "Vat": "3-------------3",
    "OrganizationName": "Tech Innovations Inc.",
    "OrganizationUnitName": "Riyadh Branch 2814",
    "CountryCode": "SA"
  },
  "Environment": "Simulation",
  "OTP": "233582",
  "InvoiceFormat": "Xml"
}

---

Response Status Codes

HTTP Status Code	Description
200	For successful generation of CSR/DeviceId.
400	For any validation issues, the errors will be listed in the errorList.
401	If the user is not authenticated.

Response Body

❗️

If your device invoice type is XML or PDF, you must save the CSID, private key, and secret for this device to manage the invoice counter and invoice hash. Additionally, you can optionally save the CSR for backup.

Parameter	Data Type	Description
deviceId	UUID	The Device ID that was generated in our server.
csid	String	Cryptographic Stamp Identifier generated from zatca
CSR	String	Certificate Signing Request used for generating the CSID.
privateKey	String	generated with the CSR
secret	String	generated from zatca associated with the CSID.
invoiceType	Enum Simplified Standard Both	Simplified: Supports only Standard Tax Invoices. Standard: Supports only Simplified Tax Invoices. Both: Supports both Standard and Simplified Tax Invoices.
status	String	Enum: Success, Failed