Documentation Topics

Quick Start Guide Signup & Account Management Free Tenant & Subscriptions Add EGS Unit Reporting Simplified Invoice C# Code Samples of Reporting Api Python Code Samples of Reporting Api Clearing Standard Invoice C# Code Samples of Clearing Api Python Code Samples of Clearing Api Additional Zatca Utiilities Add Customers Download Invoices Subscriptions and License aqusition

Welcome to the system documentation. Select a topic from the sidebar to learn more.

Quick Start

Get up and running quickly with our step-by-step guides.

Get Started

Video Tutorials

Watch our video tutorials to see the system in action.

Watch Videos

Add EGS Unit - Documentation - API Documentation

Add EGS Unit - Documentation

Welcome to the system documentation. Select a topic from the sidebar to learn more.

Use this API to onboard your EGS (E-Invoice Generation Solution) in the ZATCA Portal

You have to pass all the required params in the specified format at the minimum to onboard your EGS successfully. You can add additional parameters if applicable as per your preference.

Request Parameters#

PARAMS	REQUIRED	DATA TYPE	DESCRIPTION	EXAMPLE
`commonname`	YES	string	A Unique Name or Asset Tracking Number of your EGS. There is no specific format, any free text will be accepted.	TST-886431145-399999999900003
`serialnumber`	YES	string	Unique identification code for the EGS. Serial number should be in this "1-(.+) 2-(.+) 3-(.+)" regular expression format	1-TST 2-TST 3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt
`organisationid`	YES	string	It is the organization VAT number. It is a 15 digit number with starting and ending digits as '3'.	300055184400003
`organisationunit`	YES	string	The branch name for Taxpayers. In case of VAT Groups , this field should contain the 10-digit TIN number of the individual group member whose EGS Unit is being onboarded.	Riyadh
`organisationname`	YES	string	Name of the Taxpayer. It can be free text.	Maximum Speedtech Limited
`countrycode`	YES	string	Name of the country. 2 letter code (ISO 3166 Alpha-2)	SA
`invoicetype`	YES	string	Type of Invoice this EGS Unit use to generate. STANDARD, SIMPLIFIED or BOTH.	SIMPLIFIED
`location`	YES	string	The address of the Branch or location where the device or solution unit is primarily situated.	ENAB3405
`industry`	YES	string	Industry or sector for which the device or solution(EGS) will generate invoices.	Retail
`entype`	YES	string	Zatca Portal this EGS unit to be registered. NonProduction, Simulation or Production	NonProduction
`buildingno`	YES	string	Four digit building number	3505
`plotno`	YES	string	Plot Number of the EGS Location	2525
`street`	YES	string	Street of the EGS Location	Jasmin Street
`city`	YES	string	City name of EGS Location	Al Jumail
`citysubdivision`	YES	string	City Subdivision	Al Jumail
`postalcode`	YES	string	05 Digit postal code	54251
`companyidtype`	YES	string	Type of ID Number company is registered (NAT,CRN,TIN,OTH,MOM,MLS,700,SAG,GCC,IQA)	CRN
`companyidno`	YES	string	Particular ID Number	2548745

Response Parameters#

PARAMS	DATA TYPE	DESCRIPTION	EXAMPLE
`privatekey`	string	Base64 encoded private key	Refer API sample data in swagger page
`csr`	string	Base64 encoded CSR	Refer API sample data in swagger page
`ccsid`	string	Compliance CSID	Refer API sample data in swagger page
`pcsid`	string	Production CSID	Refer API sample data in swagger page
`secret`	string	Password to access the zatca portal	Refer API sample data in swagger page
`certificate`	string	Production certificate required for the signing of Invoices	Refer API sample data in swagger page

Body parameters

Request Example


{
    "commonname": "TST-886431145-399999999900003",
    "serialnumber": "1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt",
    "organisationid": "399999999900003",
    "organisationunit": "Riadh",
    "organisationname": "Maximum Speed tech Pvt Limited",
    "countrycode": "SA",
    "invoicetype": "SIMPLIFIED",
    "location": "ENAB3405",
    "industry": "Retail",
    "entype": "NonProduction",
    "otp": "123345",
    "buildingno": "4521",
    "plotno": "2421",
    "street": "Hazan Street",
    "city": "Al Jubail",
    "citysubdivision": "Riyadh",
    "postalcode": "11564",
    "companyidtype": "CRN",
    "companyidno": "2055126887"
}

Curl Syntax

                            
curl -X 'POST' \
    'https://www.pristineinvoice.com/api/ZatcaIntegration/EgsOnboarding' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6InJhbWl0aGFzaWx2YSIsIm5hbWVpZCI6IjI2ZDBkODBhLWFlNGQtNGIyMi1iMzA2LTBmOTIwNTRjMjU1ZiIsImVtYWlsIjoibmlzaGF0aHRyYWRlcnNAZ21haWwuY29tIiwiVGVuYW50SWQiOiI4N0I0QjRBOUUyIiwibmJmIjoxNzUyNzE1NjI2LCJleHAiOjE3NTUzOTQwMjYsImlhdCI6MTc1MjcxNTYyNiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo1MjQ2IiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MjQ2In0.DY3WI7-oi_VmpcySf10C5owx0NwiJKquSFgrUltQSfQwf6oqOPcExbeT8h3S194c0T6_qRK_cfh4e-93O1l-nA' \
    -H 'Content-Type: application/json-patch+json' \
    -d '{
    "commonname": "TST-399999999900003",
    "serialnumber": "1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f12e44yt",
    "organisationid": "399999999900003",
    "organisationunit": "Riadh",
    "organisationname": "Maximum Speed tech Pvt Limited",
    "countrycode": "SA",
    "invoicetype": "SIMPLIFIED",
    "location": "ENAB3405",
    "industry": "Retail",
    "entype": "NonProduction",
    "otp": "123345",
    "buildingno": "4521",
    "plotno": "2421",
    "street": "Hazan Street",
    "city": "Al Jubail",
    "citysubdivision": "Riyadh",
    "postalcode": "11564",
    "companyidtype": "CRN",
    "companyidno": "2055126887"
}'

Parameters#

Name	In	Type	Required	Description
body	body	object	false	none

Example responses

Response Example


    {
        "privatekey": "LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tXFxyXFxuTUhRQ0FRRUVJT1Qwck9CcE5mR1FtOFgxL29oLzhYUGNwY2RyWTlsYU5FZXlrb2Z2M0xYZm9BY0dCU3VCQkFBS1xcclxcbm9VUURRZ0FFcUdRWC9OZ2dBNStKYWFjMkRuRnRBVDFwVmNzanZ4WWowSDg1QnErZWk3bkhTRWdhUHVBbVdWNjlcXHJcXG5keEsvRmRzeFdtM3hUK2RkZGJRYjlGV2tkQ3BEaFE9PVxcclxcbi0tLS0tRU5EIEVDIFBSSVZBVEUgS0VZLS0tLS0=",
        "csr": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS1cXHJcXG5NSUlDRXpDQ0Fia0NBUUF3ZlRFTE1Ba0dBMVVFQmhNQ1UwRXhFakFRQmdOVkJBc01DVUZNSUVwVlFrRkpUREV4XFxyXFxuTUM4R0ExVUVDZ3dvUlhOMFlXSnNhWE5vYldWdWRDQktWVVJGU0NCQlRDMUJSRTlWUVZRZ1EyOXRiV1Z5WTJsaFxcclxcbmJERW5NQ1VHQTFVRUF3d2VWRk5VTFRJd05UVXhNalk0T0RjdE16RXdNRGc0T1RFME9UQXdNREF6TUZZd0VBWUhcXHJcXG5Lb1pJemowQ0FRWUZLNEVFQUFvRFFnQUVRZTEvWnh5d2xSRVZRWkluL2k2TnROWHV1Y3RiL2JQZWFFU3RpWUZmXFxyXFxuTS9mQzl6OWRlY0lqTWZqL0N5ZU1zaGtnTkFlTEhJd1RkWlA3ektvSG02NEdXS0NCM0RDQjJRWUpLb1pJaHZjTlxcclxcbkFRa09NWUhMTUlISU1DRUdCU3NHQVFRQmdqY1VBZ1FVRXhKYVFWUkRRUzFEYjJSbExWTnBaMjVwYm1jd2dhSUdcXHJcXG5BMVVkRVFTQm1qQ0JsNlNCbERDQmtURTdNRGtHQTFVRUJBd3lNUzFVVTFSOE1pMVVVMVI4TXkxbFpESXlaakZrXFxyXFxuT0MxbE5tRXlMVEV4TVRndE9XTTFPQzFrT1dFNFpqRXhaVFEwTldZeEh6QWRCZ29Ka2lhSmsvSXNaQUVCREE4elxcclxcbk9UazVPVGs1T1RrNU1EQXdNRE14RFRBTEJnTlZCQXdNQkRBeE1EQXhFVEFQQmdOVkJCb01DRVZPUVVJek5EQTFcXHJcXG5NUTh3RFFZRFZRUVBEQVpTWlhSaGFXd3dDZ1lJS29aSXpqMEVBd0lEU0FBd1JRSWhBTjgzYWhPTGc4NHZtTXNzXFxyXFxuZmJkQmU4Nnd1MkozYzlSQkJMUnRGY2s5dE54T0FpQXYxNmlCSmU2L3RGNFE3cnp0NVlCeUk2TjBZSnc3bW1lRTQrTytQK20wS2c9PVxcclxcbi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQ==",
        "ccsid": "TUlJQ09qQ0NBZUNnQXdJQkFnSUdBWmR6akRxL01Bb0dDQ3FHU000OUJBTUNNQlV4RXpBUkJnTlZCQU1NQ21WSmJuWnZhV05wYm1jd0hoY05NalV3TmpFMU1USXlOREUwV2hjTk16QXdOakUwTWpFd01EQXdXakI5TVFzd0NRWURWUVFHRXdKVFFURVNNQkFHQTFVRUN3d0pRVXdnU2xWQ1FVbE1NVEV3THdZRFZRUUtEQ2hGYzNSaFlteHBjMmh0Wlc1MElFcFZSRVZJSUVGTUxVRkVUMVZCVkNCRGIyMXRaWEpqYVdGc01TY3dKUVlEVlFRRERCNVVVMVF0TWpBMU5URXlOamc0Tnkwek1UQXdPRGc1TVRRNU1EQXdNRE13VmpBUUJnY3Foa2pPUFFJQkJnVXJnUVFBQ2dOQ0FBUWhhRnZIVjhPRURMbk1tbmlRUVB1VWtsQmdrUmlybHc2bVZxMklKT0N4V1BIVEx2YmdIRlhQbkFXV1ZvcHFIaTVVWjRyazlWNkpvWUVocWFITjluWk1vNEcyTUlHek1Bd0dBMVVkRXdFQi93UUNNQUF3Z2FJR0ExVWRFUVNCbWpDQmw2U0JsRENCa1RFN01Ea0dBMVVFQkF3eU1TMVVVMVI4TWkxVVUxUjhNeTFsWkRJeVpqRmtPQzFsTm1FeUxURXhNVGd0T1dNMU9DMWtPV0U0WmpFeFpUUTBOV1l4SHpBZEJnb0praWFKay9Jc1pBRUJEQTh6T1RrNU9UazVPVGs1TURBd01ETXhEVEFMQmdOVkJBd01CREF4TURBeEVUQVBCZ05WQkJvTUNFVk9RVUl6TkRBMU1ROHdEUVlEVlFRUERBWlNaWFJoYVd3d0NnWUlLb1pJemowRUF3SURTQUF3UlFJZ2NGVmdPU3h5ZnFxaUx0WU9nbjB0aWRRMk9DNzVOMmRVdC9INlJSU3UxclVDSVFDRWU4VDB2WGFLZ2hHS0FFd2ptaEEzeXROOTlPMmN6RGE3Wlo4aXhNWWxodz09",
        "pcsid": "TUlJQ09qQ0NBZUNnQXdJQkFnSUdBWmR6akRxL01Bb0dDQ3FHU000OUJBTUNNQlV4RXpBUkJnTlZCQU1NQ21WSmJuWnZhV05wYm1jd0hoY05NalV3TmpFMU1USXlOREUwV2hjTk16QXdOakUwTWpFd01EQXdXakI5TVFzd0NRWURWUVFHRXdKVFFURVNNQkFHQTFVRUN3d0pRVXdnU2xWQ1FVbE1NVEV3THdZRFZRUUtEQ2hGYzNSaFlteHBjMmh0Wlc1MElFcFZSRVZJSUVGTUxVRkVUMVZCVkNCRGIyMXRaWEpqYVdGc01TY3dKUVlEVlFRRERCNVVVMVF0TWpBMU5URXlOamc0Tnkwek1UQXdPRGc1TVRRNU1EQXdNRE13VmpBUUJnY3Foa2pPUFFJQkJnVXJnUVFBQ2dOQ0FBUWhhRnZIVjhPRURMbk1tbmlRUVB1VWtsQmdrUmlybHc2bVZxMklKT0N4V1BIVEx2YmdIRlhQbkFXV1ZvcHFIaTVVWjRyazlWNkpvWUVocWFITjluWk1vNEcyTUlHek1Bd0dBMVVkRXdFQi93UUNNQUF3Z2FJR0ExVWRFUVNCbWpDQmw2U0JsRENCa1RFN01Ea0dBMVVFQkF3eU1TMVVVMVI4TWkxVVUxUjhNeTFsWkRJeVpqRmtPQzFsTm1FeUxURXhNVGd0T1dNMU9DMWtPV0U0WmpFeFpUUTBOV1l4SHpBZEJnb0praWFKay9Jc1pBRUJEQTh6T1RrNU9UazVPVGs1TURBd01ETXhEVEFMQmdOVkJBd01CREF4TURBeEVUQVBCZ05WQkJvTUNFVk9RVUl6TkRBMU1ROHdEUVlEVlFRUERBWlNaWFJoYVd3d0NnWUlLb1pJemowRUF3SURTQUF3UlFJZ2NGVmdPU3h5ZnFxaUx0WU9nbjB0aWRRMk9DNzVOMmRVdC9INlJSU3UxclVDSVFDRWU4VDB2WGFLZ2hHS0FFd2ptaEEzeXROOTlPMmN6RGE3Wlo4aXhNWWxodz09",
        "secret": "q3mmGFL5rclJOonKJn5sB3nCC7e4GbSwWmDmWHS4uZg=",
        "certificate": "MIID3jCCA4SgAwIBAgITEQAAOAPF90Ajs/xcXwABAAA4AzAKBggqhkjOPQQDAjBiMRUwEwYKCZImiZPyLGQBGRYFbG9jYWwxEzARBgoJkiaJk/IsZAEZFgNnb3YxFzAVBgoJkiaJk/IsZAEZFgdleHRnYXp0MRswGQYDVQQDExJQUlpFSU5WT0lDRVNDQTQtQ0EwHhcNMjQwMTExMDkxOTMwWhcNMjkwMTA5MDkxOTMwWjB1MQswCQYDVQQGEwJTQTEmMCQGA1UEChMdTWF4aW11bSBTcGVlZCBUZWNoIFN1cHBseSBMVEQxFjAUBgNVBAsTDVJpeWFkaCBCcmFuY2gxJjAkBgNVBAMTHVRTVC04ODY0MzExNDUtMzk5OTk5OTk5OTAwMDAzMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEoWCKa0Sa9FIErTOv0uAkC1VIKXxU9nPpx2vlf4yhMejy8c02XJblDq7tPydo8mq0ahOMmNo8gwni7Xt1KT9UeKOCAgcwggIDMIGtBgNVHREEgaUwgaKkgZ8wgZwxOzA5BgNVBAQMMjEtVFNUfDItVFNUfDMtZWQyMmYxZDgtZTZhMi0xMTE4LTliNTgtZDlhOGYxMWU0NDVmMR8wHQYKCZImiZPyLGQBAQwPMzk5OTk5OTk5OTAwMDAzMQ0wCwYDVQQMDAQxMTAwMREwDwYDVQQaDAhSUlJEMjkyOTEaMBgGA1UEDwwRU3VwcGx5IGFjdGl2aXRpZXMwHQYDVR0OBBYEFEX+YvmmtnYoDf9BGbKo7ocTKYK1MB8GA1UdIwQYMBaAFJvKqqLtmqwskIFzVvpP2PxT+9NnMHsGCCsGAQUFBwEBBG8wbTBrBggrBgEFBQcwAoZfaHR0cDovL2FpYTQuemF0Y2EuZ292LnNhL0NlcnRFbnJvbGwvUFJaRUludm9pY2VTQ0E0LmV4dGdhenQuZ292LmxvY2FsX1BSWkVJTlZPSUNFU0NBNC1DQSgxKS5jcnQwDgYDVR0PAQH/BAQDAgeAMDwGCSsGAQQBgjcVBwQvMC0GJSsGAQQBgjcVCIGGqB2E0PsShu2dJIfO+xnTwFVmh/qlZYXZhD4CAWQCARIwHQYDVR0lBBYwFAYIKwYBBQUHAwMGCCsGAQUFBwMCMCcGCSsGAQQBgjcVCgQaMBgwCgYIKwYBBQUHAwMwCgYIKwYBBQUHAwIwCgYIKoZIzj0EAwIDSAAwRQIhALE/ichmnWXCUKUbca3yci8oqwaLvFdHVjQrveI9uqAbAiA9hC4M8jgMBADPSzmd2uiPJA6gKR3LE03U75eqbC/rXA==",
        "requestid": "8874454154755",
        "status": "success",
        "result": "Full Zatca Response",
        "message": "Erro Message"
    }

Responses#

Attribute	format	Description	Usage
privatekey	Base 64 Encoded	Private key Generated for EGS unit	Required to decode before using
CSR	Base 64 Encoded	Certificate Requested generated along with the private key	Required to decode before using
CSID	Not Encoded	Binary security token received in Compliance API	Can store as is
PSID	Not Encoded	Binary security token received in Production API	Can store and use as is
Certificate	Not Encoded	Decoded binary security toke (PSID)	Can store and use as is
PSID	Not Encoded	Binary security token received in Production API	Can store and use as is
RequestId	Not Encoded	Request Id in Compliance API	Required only at the PCSID Request
status	Not Encoded	success or failure message	success or fail indicator
result	Encoded in base64	Full production api response
message	Not Encoded	Last Error message

To perform this operation, you must be authenticated by means of valid License Token

Onboarding EGS unit using Add Egs Unit form in Registration menu. Above mentioned Parameters are valid for the Input parameters in this form as well.

You can register any number of EGS units in your Paid subscription Plans. you can onboard one EGS unit in the free plan

Figure 1: EGS Onboarding Form

Once Registration successfull, it will be automatically navigates to the EGS Unit Information Page. POS Unit Details page contains all neccessary information of EGS unit as shown bellow.

Figure 2: EGS Unit Information

You can view all onboarded EGS units in All EGS Units sub menu in the Registration menu

Figure 3: All Egs Units

Free Plan Notes:

Free plan have all E-invicing related functionality of paid subscription plans. But POS unit information may not be fully visible to the free-plan subscribers. but that information is securely stored in your tenant and will be used against your invoice submissions.

}