Developer Portal Manual. User Manual (Version 2)

Contents

1. General Information

1.1 Introduction

1.1.1 Objectives

1.1.2 Scope

1.1.3 Intended Audience

1.1.4 Recommended Reading

2. Developer Portal Overview

2.1 Pre-requisites

2.2 Structure / Sitemap

2.3 User Journeys

2.3.1 Accessing the Developer Portal

2.3.2 Creating a Developer Portal Account

2.3.3 Accessing the Compliance and Enablement Toolbox SDK Page

2.3.4 Downloading the SDK

2.3.5 Using the SDK (outside of the Developer Portal)

2.3.6 Accessing the Compliance and Enablement Toolbox Portal Based Validator

2.3.7 Using the Compliance and Enablement Toolbox Portal Based Validator

2.3.8 Accessing the Integration Sandbox Page

2.3.9 Accessing the API and associated Documentation (Swagger Files)

2.3.10 Step by step guide to make a successful call to APIs

2.3.11 API Summary

2.3.12 Accessing the Developer Portal Support Page

3. Change in Security Requirements

4 Frequently Asked Questions (FAQs)

4.1 Business FAQs

4.1.1 Developer Portal Business FAQs

4.1.2 SDK Business FAQs

4.1.3 Compliance and Enablement Toolbox Portal Based Validator Business FAQs

4.1.4 Integration Sandbox Business FAQs

4.2 Technical FAQs

4.2.1 Developer Portal Technical FAQs

4.2.2 SDK Technical FAQs

4.2.3 Compliance and Enablement Toolbox Portal Based Validator Technical FAQs

4.2.4 Integration Sandbox Technical FAQs

5 Appendix

1. General Information

1.1 Introduction

The Developer Portal is a dedicated portal provided by ZATCA for the developers of E-invoicing Generation

Solutions (EGS). It contains two development tools aimed at supporting developers build compliant EGS

units which are:

● The Compliance and Enablement Toolbox Software Development Kit (SDK): an offline downloadable

tool which can be used to validate an XML based e-invoice, credit or debit note files in accordance

with the ZATCA published requirements, standards and guidelines. It also allows validation of the QR

codes as per the prescribed structure. Developers can integrate their EGS units with the SDK locally

(offline) or also test using a Command Line Interface (CLI).

● Integration Sandbox: a test ZATCA backend system which EGS units can integrate with to make API

calls to simulate and test the Onboarding process followed by the submission of test e-invoices, credit

and debit notes for Reporting and Clearance in accordance with the ZATCA published requirements,

standards and guidelines.

In addition to the above, the Developer Portal has a third tool aimed at intermediate or non-technical users

to validate an XML based e-invoice, credit or debit note files from the portal directly. This is referred to as

the Compliance and Enablement Toolbox Portal Based Validator.

Finally, the Developer Portal has a dedicated support page containing a list of Frequently Asked Questions

(FAQs) to help developers troubleshoot during development and testing of their EGS units as well as

provide guidance on E-invoicing requirements in general.

1.1.1 Objectives

The primary objective of the Developer Portal is to support the Developer community in building EGS units

that are compliant with ZATCA's XML implementation standards as well as the Security Features and

Implementation Standards.

● The objective of the SDK is to ensure that XML e-invoices, credit or debit notes being generated by the

EGS units are compliant

● The objective of the Web based validator is to allow less or non-technical users to be able to independently

validate the compliance of XML e-invoices, credit or debit notes and share the results with their developers.

● The objective of the Integration Sandbox is to test the EGS units / solutions / applications are able to

integrate with a test ZATCA backend system via APIs covering the following:

● Submit a test Certificate Signing Request (CSR) to obtain a test Compliance Cryptographic

Stamp Identifier (CCSID) and test Request ID

● Submit a test Request ID to obtain a test Production CSID

● Submit test Standard Documents using the test Clearance API (or using a variant of the test

Reporting API to mimic the process when Clearance is turned off)

● Submit Simplified Documents using the Reporting API

1.1.2 Scope

This user manual acts as a guide for Developers in order to help them access and use the Developer

Portal features and functionalities. It explains in detail the user journey including steps, requirements and

processes needed for accessing the Developer Portal. Moreover, it provides guidance for the relevant

technical aspects and methods to be used to solve common issues that might be faced by the Portal users.

This document covers the following functionalities that are of relevant to the Developer Portal:

● Accessing the Developer Portal

● Website address and browsers supported

● Main dashboard elements

● Registration for the Developer Portal

● Functionalities that require registration

● Authentication and verification process

● Log in to the Developer Portal

● Entering user credentials

● Password reset / Forget Password

● Successful log in

● Accessing and downloading the Compliance and Enablement Toolbox SDK

● Understanding of the SDK and how to use it

● Downloading the SDK

● Accessing and using the Web Based Validator

● Understanding of and the use of the Web Based Validator

● Validating XMLs directly on the Web Based Validator

● Accessing documentation for the APIs

● Using the APIs to integrate with the test ZATCA backend system

● Test the integration calls for Onboarding, Renewal, Reporting, Clearance

● Accessing and using the Integration Sandbox APIs

● Accessing documentation for the APIs

● Using the APIs to integrate with the test ZATCA backend system

● Test the integration calls for Onboarding, Renewal, Reporting, Clearance

1.1.3 Intended Audience

This document is intended to be used by:

● Solution Developers

● Taxpayers

● Other users of relevance

1.1.4 Recommended Reading

Although not a pre-requisite for accessing and using the Developer Portal functionalities, it is strongly

advised that users go through the following documentation:

XML Implementation Standards (E-Invoice XML Implementation Standard)

2. Security Features and Implementation Standards (E-Invoice Security Features and Implementation

Standards)

3. Data Dictionary (E-Invoice Data Dictionary)

4. E-Invoicing Resolution (E-Invoicing Resolution)

2. Developer Portal Overview

2.1 Pre-requisites

The Developer Portal itself is a web-based application and can be run from any modern browser such as

Google Chrome, Microsoft Edge or Apple Safari.

The SDK is a Java based JAR file that can run on all leading platforms including Windows, Linux and

Mac. The Java SDK (JAR) will run on JDK versions >=11 and <15, to comply with secp256k1 as per ZATCA

security regulations.

The Integration Sandbox APIs can be accessed from all leading platforms as those mentioned above.

REST APIs can be accessed from any Rest Client tools (Postman) for testing or using any coding languages

(java, .Net, PHP, Nodejs, etc.) to call the rest services using HTTPs Protocol.

2.2 Structure / Sitemap

The Developer Portal is comprised of the following:

Developer Portal

Access Portal Based

Access Developer Portal

Validator

Support Page

Access SDK Page

Access Integration Sandbox Page

● Download SDK

● Access API Documentation

● SDK Support

(Swagger Files)

Validate XMLs

Access FAQs

● SDK Documentation

● Test APIs for Onboarding,

● SDK Version History

Renewal, Reporting and Clearance

Outside Developer Portal

Using the SDK

Using the Integration Sandbox (APIs)

● Test APIs to obtain Compliance

CSID and Production CSID (as part of

Onboarding process)

● Test compliance of XML

● Test APIs to obtain new Compliance

● Test compliance of QR

CSID and Production CSID (Test the

Code (Generation Phase)

Renewal process)

● Test Compliance of QR

● Test API to submit documents for

Code (Integration Phase)

Reporting

● Test API to submit documents for

Clearance

2.3 User Journeys

The recommended steps for Solution Developers are:

Read the XML Implementation Standards, Security Features Implementation Standards and Data

Dictionary

2. Access the Developer Portal

3. Create a Developer Portal Account

4. Login to the Developer Portal as a Registered User

5. Access the SDK Page

6. Read the SDK Support and Documentation

7. Download the SDK

8. Test XML compliance using the SDK via CLI / local integration

9. Access the Integration Sandbox Page

10. Go through the API Documentation on Swagger

11. Test the APIs through Swagger

12. Test the APIs via integration

13. Leveraging the Developer Portal Support page FAQs for troubleshooting

The recommended steps for Non-technical users are:

Access the Developer Portal

2. Accessing the Compliance and Enablement Toolbox Portal Page

3. Test XML compliance

4. Provide the error messages / responses (if any) to Solution Developers

5. Leveraging the Developer Portal Support page FAQs for troubleshooting

2.3.1 Accessing the Developer Portal

The process for accessing the Developer Portal is as follows:

Access the Developer Portal through the following weblink (https://sandbox.zatca.gov.sa/ ).

2. The user is directed to the Developer Portal main dashboard / landing page

In this page the user can access the below sections without registration or login:

Developer Portal Support Page which includes the FAQs.

2. Web Based Validator for Non-Technical Users.

2. The following sections would require the user to create a Developer Portal account:

Compliance and Enablement Toolbox SDK Page.

2. Integration Sandbox Page.

Note: The User can chose to toggle the language between English and Arabic by using the icon on the

top right-hand side of the page.

Developer Portal main landing page

2.3.2 Creating a Developer Portal Account

As mentioned above, a Developer Portal account is required for accessing the Compliance and Enable-

ment Toolbox SDK page and the Integration Sandbox page. You can ignore this step if you only wish to

access the Web Based Validator or the Developer Portal Support page.

Once the user is on the main dashboard of the Developer Portal, they can click on the "Sign up" button at

the top right-hand side as seen in the Figure below.

● Email ID

● First Name

● Last Name

● Company Name (optional field)

● Password

● Confirm Password

In the Sign Up page (as seen in the Figure below), the user will be prompted to create a new account by

providing the following details:

The email must be a valid email and the password must be at least 8 characters comprising of at least one

number, one letter each in lower and upper case, and one symbol.

After completing all the necessary fields, the user should click on the CAPTCHA verification followed by

the Sign up button.

After the user has signed up and created their account credentials, they can proceed to the Login page

where they will be prompted to:

● Fill in the User Name and Password (as created by the user).

● Click the CAPTCHA.

● In addition, the user can click "Forgot Password"

● In the case where the user does not have an account set up and requires one, the user can click on the

2.3.2 of the User Manual for registration.

● After filling in all the information, the user should click on the Login button in order to proceed to the

main dashboard again where the user will now also be able to access the Compliance and Enable-

ment Toolbox SDK page and the Integration Sandbox page.

● A logged in user can logout at any time by clicking on the logout option on the header. The user can

also change the password at any time by clicking on the arrow next to the user profile icon in header.

2.3.3 Accessing the Compliance and Enablement Toolbox SDK Page

The Compliance and Enablement Toolbox (SDK) which is an offline downloadable tool that can be used to

validate an XML based e-invoice, credit or debit note files in accordance with the ZATCA published XML

Implementation Standards. It also allows validation of the QR codes as per the prescribed structure. Developers

can integrate their EGS units with the SDK locally (offline) or also test using a CLI.

The process for accessing and downloading the Compliance and Enablement Toolbox SDK through the

Developer Portal is as follows:

● The user should be registered and logged into the Developer Portal successfully

● The user should click on "Compliance and Enablement Toolbox and SDK" to view the SDK functionalities.

Accessing the Compliance and Enablement Toolbox (SDK)

After the user has accessed the Compliance and Enablement Toolbox SDK Page, the user can:

● Access the SDK support, which includes aspects such as how to use the SDK and how it works, as well

as the minimum software requirements and the instructions of relevance to each Operating System/

environment.

● Access documentation such as the XML Implementation Standards (E-Invoice XML Implementation

Standard), Security Features and Implementation Standards (E-Invoice Security Features and

Implementation Standards) & Data Dictionary (E-Invoice Data Dictionary)

● Download the SDK after accepting the terms and conditions.

● View the version history which contains earlier releases of the SDK.

2.3.5 Using the SDK (outside of the Developer Portal)

Please refer to the ZATCA E-Invoice Java SDK (CLI) Manual on the below link by downloading the SDK

and then navigate to readme folder.

https://zatca.gov.sa/ar/E-Invoicing/SystemsDevelopers/ComplianceEnablementToolbox/Pages/Down-

loadSDK.aspx.

2.3.6 Accessing the Web Based Validator for Non-Technical Users

The user can test - using a web portal - the compliance of the XMLs of standard e-invoices, credit or debit notes

generated so that they can know if they are in line with the ZATCA e-invoicing specifications and regulations

or so that they can be alerted to any errors which are causing non-compliance with the ZATCA specifications

and regulations. It is aimed at intermediate or non-technical users to validate XML based e-invoices, credit

or debit note files from the portal directly, i.e. without the need to download the SDK or possess the technical

know-how to run it.

This section details the process of accessing the "Web Based Validator for Non-Technical Users" in order to

test the compliance of the e-invoice, credit and debit note XMLs. Users can access the "Web Based Validator

for Non-Technical Users" Page through the Developer Portal (no prior registration or login is required). On this

page, users can view information related to what the Web Based Validator aims to achieve and the user can

access this and begin uploading the XMLs that they would want to test and validate.

The process for accessing the "Web Based Validator for Non-Technical Users" page is as follows:

● The User accesses the "Web Based Validator for Non-Technical Users" on the Developer Portal (no prior

registration or log in required).

The portal validation page is a standalone application and compliance does not necessarily imply the

e-invoices, credit or debit notes have been accepted by ZATCA. All Taxpayer E-invoicing solution unit will

need to pass the testing requirements as part of Registration/Taxpayer Onboarding prior to submitting

e-invoices, credit or debit notes to ZATCA.

● The User has to acknowledge the disclaimer in order to proceed to test their XML files.

Web based validator Disclaimer

2.3.7 Using the Web Based Validator for Non-Technical Users

An XML file can be validated according to its structure (schema), fields, or ZATCA requirements (i.e. The VAT

registration number must be 15 numeric digits). The way this works is that the user submits an XML and the

portal will read it, analyze it, and return the status of the validation.

Note that the Web Based Validator can be used to validate up to 5 XMLs and if more than 1 XML is provided, the

validator also checks for the sequence in terms of Previous Invoice (Document) Hash. Note that for a single

XML the Previous Document Hash check is always considered as valid or True.

If not compliant, the following message is shown.

Web based validator - XML complete and errors found

The non-technical user is expected to share the validation outcomes with the Solution Developer to take

necessary action.

2.3.8 Accessing the Integration Sandbox Page

The Integration Sandbox as covered in this user manual comprises of two components - the Sandbox specific

front-end web pages (which is part of the Developer Portal and access to which requires a Developer Portal

registered user account) and an API based Sandbox backend to integrate with.

A registered and logged in user can access the Integration Sandbox page from the main dashboard while a

non-registered and non-logged in user is taken to the login screen. Once on the Integration Sandbox page

the user is given a high level summary of the current version release of the Sandbox as well as links to any

previous releases.

The ZATCA e-invoicing integration Sandbox is meant to be used for testing purposes only. Any inputs

submitted on the Sandbox are not considered as acknowledged, approved or accepted by ZATCA. Taxpayers

will be required to login using SSO credentials for the Taxation portal (ERAD) prior to officially be able to submit

official documents. Test CSIDs provided by the Sandbox cannot be used in the Core E-invoicing Solution.

Developers must also take into account that documents or requests submitted on the Core E-invoicing Solution

will be subjected to additional validations such as security features, prohibited functionalities, additional

business rule validations and/or referential checks based such as validating Seller/Buyer information entered

in the documents, validations based on previously submitted documents.

API Integration sandbox landing page

On the left navigation bar of the page the user is able to access the links to the API documentation which

are maintained as Swagger files (each API call is described in section 2.3.10 below along with the possible

outcomes).

2.3.9 Accessing the API and associated Documentation (Swagger Files)

Access to the Swagger files is provided from the Integration Sandbox page. API documentation is provided

covering all the API calls that can be tested on the Sandbox such as:

● Test request for Compliance CSID as part of a new onboarding (requires a signed test CSR to be submitted

- details provided in the Swagger files)

● Test request for Production CSID as part of a new onboarding (requires a test Compliance CSID to be

submitted)

Note: The Core E-invoicing Solution will require specific compliance checks to be completed in between

the Compliance CSID and Production CSID requests and the latter will return an invalid response until these

compliance checks are completed. This invalid response can be tested in the Sandbox by providing a specific

input which is covered in the Swagger files below.

● Test request for a new Production CSID as part of renewal (requires a test Compliance CSID to be sub-

mitted)

● Test submission of documents for Clearance (requires a test Production CSID)

● Test submission of documents for Reporting (requires a test Production CSID)

Although the Sandbox uses test CSIDs, it is important to note that the VAT Registration number used to obtain

the test CSID must match with the VAT Registration number in the Renewal CSR and/or e-invoices, credit

notes, debit notes and QR codes submitted in all subsequent calls made using that specific test CSID. In other

words for every VAT Registration Number that is used in the Sandbox integration, a separate CSID will have

to be requested. Of course the VAT Registration Numbers can be dummy inputs.

● Please refer to the API Documentation through the following LINK.

Note: Please make sure to log-in in order to view the API documentation

2.3.10 Step by step guide to make a successful call to APIs

For Reporting and Clearance (testing the submission of E-invoices, credit and debit notes)

● The users' E-Invoice Generation Solution (EGS) needs to generate compliant XML documents. For

more details on generating compliant XML documents please refer to the XML Implementation

Standards and the Data Dictionary (E-Invoice specifications (zatca.gov.sa). It is also recommend to

test the compliance using the Compliance and Enablement Toolbox SDK (Download SDK (zatca.

gov.sa) or Portal based validator for non-technical users (Compliance and Enablement Toolbox

portal).

● For Simplified documents (and optionally for Standard documents), the EGS also needs to generate

compliant QR codes. For more details on generating compliant QR codes please refer to the

Security Features and Implementation Standards (E-Invoice Security Features and Implementation

Standards).

● Note that EGS must obtain a test Cryptographic Stamp Identifier (CSID) first, by using the test

integration calls for Onboarding or Renewal.

2. For Cryptographic Stamp Identifier (testing the Onboarding and Renewal processes).

● The users' EGS needs to generate a compliant CSR to obtain a test CSID. For more details on

generating a compliant CSR and CSID specifications please refer to (E-Invoice Security Features and

Implementation Standards).

● Note that EGS must obtain a test Cryptographic Stamp Identifier (CSID) first, by using the test

integration calls for Onboarding, in order to test the integration call for Renewal which requires a test

CSID to be included in the request.

2.3.10.1 Compliance CSID

● Step 1: Navigate to Developer Portal link

● Step 2: Login with correct credentials

● Step 3: Navigate to API Integration Sandbox

● Result (400)

2.3.11 API Summary

Table 1

The following table gives a more detailed summary of the differences between the Integration Sandbox

releases in terms of the APIs as well associated components. The current release also indicates the new

additions/changes made in comparison to the previous release.

Release 1 (No-

Release 1.5 (Feb-

Function-

Release 2 (Current -

Description

vember

ruary

ality

April 2022)

2021)

2022)

Invoices APIs:

●

Reporting API (configured to

Clearance enabled)

● Clearance API (configured to

Invoices APIs:

Clearance enabled)

● Reporting API

● Reporting API (configured to

● Clearance API

Clearance disabled)

Invoices APIs:

● NEW

● Reporting API

Onboarding APIs:

● Clearance API (configured to

The list of APIs that are

● Clearance API

● Compliance CSID

Clearance disabled) -

covered in each release

API

● NEW

including

APIs

Onboarding APIs:

● Production CSID API

references to the

● CSID API (for

● (for Onboarding)

Onboarding APIs:

functionalities they are

● Onboarding)

● Production CSID API

● Compliance CSID API

part of

● CSID API (for

(for Renewal)

● Production CSID API (for On-

● Renewal)

● Compliance Checks

boarding)

APIs (for Onboard-

● Production CSID API (for Re-

ing / Renewal)

newal)

● Invoices API

● Compliance Checks APIs (for

Onboarding / Renewal)

● Invoices API

● Invoices API (Clearance dis-

abled) -- NEW

● As per updated data dictionary,

● As per updated data

XML Implementation Stan-

The treatment of

dictionary, XML

dards and Security Features

validations and

Implementation

and Implementation Standards

●

As per original

exceptions as part

Standards and

(including updates to CSR and

(published) data

of the Reporting

Security Features

CSID standards)

dictionary, XML

and Clearance

and Implementation

● Seller Address field will be

Implementation

process.

Standards (includ-

accepted with warning for Tax-

Standards and

Exceptions here

ing updates to CSR

payer devices / solution units to

Security Features

refer to warnings

and CSID standards)

differentiate Between a warning

and Implementation

Validation

which are similar to

● Seller Address field

and an error response

Standards

Engine

errors but do not

will be accepted

● Two variants of the Reporting

●

No exceptions

(For Invoices)

cause the

with warning for

and Clearance APIs which are

(Invoices are

submitted

Taxpayer devices /

configured with Clearance

either accepted or

invoices/documents to

solution units to dif-

disabled is being provided -

rejected)

be rejected but are still

ferentiate between

● NEW

●

Not possible to test

indicated in

a warning and an

● Note: In the Core Einvoicing

for Sandbox behav-

the response so

error response

Solution there will only be one

ior When Clearance

that they can be

● Not possible to test

API each for Reporting and

is disabled

corrected in future

for Sandbox behav-

Clearance which at any point of

submissions.

ior when Clearance

time willeither be configured

is disabled

to Clearance being enabled or

disabled

The formats and fields

for the Certificate Signing

As per the original (pub-

CSR and CSID

Request (CSR) and the

lished) Security Features

As per the updated Secu-

As per the updated Security Features

(For

resultant Cryptographic

and Implementation

rity Features and Imple-

and Implementation Standards

Onboarding)

Stamp Identifier (CSID)

Standards

mentation Standards

that is used as part of the

Onboarding process.

● Covers the APIs

Covers the Reporting and Clear-

●

mentioned

ance APIs above with provision

● Provision for 1

for 1 Exception

Exception (Non-

●

Covers the Reporting and

compliance in the

Clearance APIs above with pro-

● Covers the APIs

Seller’s Address

vision for turning off Clearance

mentioned above

field is accepted as

Swagger

The API documentation

(through two additional variants

●

No provisions for

a warning)

Files (API

associated with the

of the Reporting and Clearance

Exceptions or turn-

● No provisions for

Specifications)

Swagger files.

APIs) -

ing off Clearance

turning off Clear-

●

NEW

ance

● Covers the two separate APIs

● Covers the two

for Compliance and Production

separate APIs for

CSIDs

Compliance and

Production CSIDs

Table 2

The following table provides a summary description of the APIs including the key outputs and inputs/pre-

requisites for each API.

API Name

Description

Output

Pre-requisites

This API should be used to test submitting

Simplified e-invoices, credit or debit note to

the ZATCA backend system as part of the

Reporting process

●

If no errors or warnings:

●

A test Production CSID obtained

When Clearance is disabled, this API can

Accepted

from API #5 or #6 below

also be used to test submitting Standard

●

If error in Seller Address:

e-invoices, credit or debit notes for Report-

●

Simplified invoice, credit or debit

Accepted with warning

ing

note in XML format

Reporting API

message

Note: In the Integration Sandbox there will

●

Standard invoice, credit or debit

●

If errors other than Seller

be two variants of the Reporting API, one

note in XML format when Clear-

Address: Rejected with

which is configured to Clearance being

ance is disabled

error messages

enabled (i.e. it will not accept Standard

documents) and one which is configured

to Clearance being disabled (i.e. it will also

accept Standard documents to be submitted

for Reporting)

●

If no errors or warnings:

This API should be used to test submitting

Accepted and document

test Standard e-invoices, credit or debit note

is returned with test ZAT-

to the ZATCA backend system as part of the

CA stamp and QR code

Clearance process

When Clearance is disabled, this API will

●

If error in Seller Address:

return a 303 Response indicating that the

Accepted with warning

Reporting API be used to submit Standard

message and document

●

A test Production CSID obtained

documents as well

is returned with test ZAT-

from API #5 or #6 below

Note: In the Integration Sandbox there will

CA stamp and QR code

Clearance API

●

Standard invoice, credit or debit

be two variants of the Clearance API, one

●

If errors other than Seller

note in XML format

which is configured to Clearance being en-

Address: Rejected with

abled (i.e. it will validate and clear Standard

error messages

documents) and one which is configured to

●

Response 303 when

Clearance being disabled (i.e. it will return

Clearance is disabled

response 303 stating that Clearance is

asking the Reporting

currently disabled and the Reporting API

API to be used to submit

must be used to submit Standard documents

Standard documents

as well)

● Valid request: Test Com-

This API should be used to test submitting

pliance CSID and a test

● Public Private Key pair

Compliance

test CSRs (Certificate Signing Requests) to

Request ID are obtained

●

Signed CSR

CSID API

the ZATCA backend system as part of the

● Invalid request: Error

Onboarding and renewal process

message(s)

● Valid request: Test Pro-

● A test Compliance CSID obtained

Production

This API will be used to submit a test Re-

duction CSID is obtained

from APIs #3 above

CSID API (for

quest ID to a test ZATCA backend system as

● Invalid request: Error

● A test (dummy) request ID

Onboarding)

part of the Onboarding process

message(s)

● Valid request: Test Pro-

● A test Compliance CSID obtained

Production

This API will be used to submit a test Re-

duction CSID is obtained

from APIs #3 above

CSID API (for

quest ID to a test ZATCA backend system as

● Invalid request: Error

● A test (dummy) request ID

Renewal)

part of the Onboarding process

message(s)

These APIs should be used to test the

compliance check for the device / solution

unit (EGS) as part of the Onboarding and/or

Renewal processes

● All Compliance checks

● A test Compliance CSID obtained

Compliance

passed

from APIs #3 above

Checks APIs

The compliance checks include checking

● One or more compliance

● Standard and/or Simplified invoic-

(for Onboard-

compliance of Standard and/or Simplified

checks failed with error

es, credit or debit notes in XML

ing / Renewal)

documents when Clearance is enabled

messages

format

(Compliance Invoice API) or when Clear-

ance is disabled (Compliance Invoice

Clearance Disabled API);

2.3.12 Accessing the Developer Portal Support Page

The Developer Portal Support Page can be accessed from the main dashboard of the Developer Portal and

does not require any prior registration / log in. Through this page, the user can view the different types of

support available which includes the Toolbox and Sandbox documentation. In addition, the user can view the

FAQ section to find readily available answers to common inquiries they may have on the Developer Portal

tools and functionalities as well as more specific questions on testing the compliance of their XMLs. Users can

also find the support contact information that they can access should they require any support. This includes

phone number / hotline, international phone number and the email address. Users could also provide any

suggestions or complaints they may have.

The user can access the Developer Portal Support Page from the main Developer Portal page.

The following categories are available to users:

● General support

● SDK support

● Integration Sandbox support

● Compliance and Enablement Toolbox support

3. Change in Security Requirements

ZATCA has updated its E-invoicing security solution from a Certificate Based Header to Oauth2 Basic

Authentication and below are the key changes between these two solutions:

Certificate Based Authentication

Basic Authentication

The updated solution will include a Basic Authenti-

The current solution includes using the CSID

cation header with the CSID as the Username and a

Description

in as a header value in authentication-certif-

Secret Value as the Password. Secret value will be

icate

issue with the CSID. An additional accept-version:

v2 header must be added to V2 API calls.

CSID is issued for the compliance checks and

CSID and Secret are issued for the compliance

Onboarding

is included in the authentication-certificate

checks, CSID should be used as the user and the

header for all compliance calls

Secret as the password

Production CSID and Secret issued and all eInvoic-

ing calls (reporting and clearance) should include

Production CSID is issued and all eInvoicing

the Basic Authentication header with CSID as the

E-invoicing

calls (reporting and clearance) include the

user and Secret as the password. An additional

authentication-certificate header

accept-version: v2 header must be added to V2 API

calls

Basic Authentication Format:

● Authorization: Basic {Base64 Encoded String}

● {Base64 Encoded String} = A script containing the CSID, a Colon and the Secret encoded with Base64

(CSID:Secret)

4. Frequently Asked Questions (FAQs)

4.1 Business FAQs

4.1.1 Developer Portal Business FAQs

Question

Answer

The Developer Portal is a dedicated Portal provided by ZATCA

to the e-invoice generation solution developers and the

developers community. It provides tailored information in line

with e-invoicing requirements and in particular it provides

What is the Developer Portal?

access to a Software Development Kit (SDK) and a Portal-

based validator which allows for checking the compliance

of specific XML electronic invoices with the e-invoicing

requirements. It also provides access to ZATCA's Integration

Sandbox.

Through the Developer Portal, users can access:

● A Support page, which includes guidance and support

information on the Developer Portal functionalities

● The SDK page, used for testing the compliance of XML files

What are the main tools or

with the e-invoicing requirements

functionalities provided by the

● The Portal-based validator page, which enables non-

Developer Portal?

technical users to check the compliance of XML files by

uploading them to the Portal

● The Integration Sandbox, which allows developers to test the

integration of their systems with a Sandbox environment

Question

Answer

The Developer Portal is publicly available to everyone.

The users can access the Compliance and Enablement

Toolbox (SDK and Web-based Validator) and Support

What are the requirements for

pages without the need for prior registration. However,

using the Developer Portal?

users who desire to access the SDK and the Integration

Sandbox must register by providing the details requested

on the page.

Developers of e-invoice solutions or developers

representing taxpayers' in-house teams or non-technical

Who are the intended users to

users representing taxpayers (such as tax or accounts

teams) who would like to validate the compliance of

specific document files (e.g. XML files) with the e-invoicing

requirements.

4.1.2 SDK Business FAQs

Question

Answer

The SDK is an offline downloadable tool which can be used

What is the Compliance and

to validate the XMLs files in accordance with the E-Invoicing

Enablement Toolbox SDK?

requirements. It also allows validation of the QR codes as

per a prescribed structure.

TheSDKcanbefoundbynavigating to the "Systems Developers"

page on the ZATCA website, followed by the "Compliance and

Where can I find the SDK?

Enablement Toolbox" page. Through the "Compliance and

Enablement Toolbox" page, users can download the SDK after

accepting the disclaimer.

It is not mandatory for Taxpayers to use the SDK. However,

ZATCA encourages developers to use the SDK to ensure

compliance with the E-Invoicing requirements for the QR

Do I have to use the SDK?

Code (required from 4 December, 2021) and XML (required

starting from 1 January, 2023 onwards).

Developers should also use the SDK for offline testing to reduce

load on the Integration Sandbox.

The purpose of the SDK is to assist the developers to check

if the QR Code structure and XML file meets the E-Invoicing

Once the XML validation is

requirements and to return specific error messages for

successful, is it deemed to be

correction. Successful validation of XMLs using the SDK should

accepted by ZATCA?

not be deemed as any form of acceptance or approval by

ZATCA.

The users will be able to validate the following fields:

Seller's Name.

2. VAT registration number of the seller.

3. Timestamp of the electronic invoice or credit/debit note

What are the QR code fields

(date and time).

that will be validated in the

Generation phase and which

4. Electronic invoice or credit/debit note total (with VAT).

are required for the 4th of

5. VAT total.

December 2021?

Additional fields from the specification and otherwise may

be included, but will be disregarded by ZATCA for the 4th of

December requirements.

The users will be able to validate the following fields:

Seller's Name.

2. VAT registration number of the seller.

3. Timestamp of the electronic invoice or credit/debit note

(date and time).

4. Electronic invoice or credit/debit note total (with VAT).

What are the QR code fields that

5. VAT amount.

will be validated in the Integration

phase starting from 1 January

6. Hash of XML electronic invoice or credit/debit note.

2023 onwards?

7. Elliptic Curve Digital Signature Algorithm (ECDSA)

signature.

8. ECDSA public key: The public key BLOB format contains

only the public portion of an ECDSA key used to generate

the Cryptographic Stamp. Length of the public key BLOB

for a 256-bit key is 64 bytes (72 bytes including magic

number and field length information on some systems).

9. For Simplified Tax Invoices and their associated notes,

the ECDSA signature of the cryptographic stamp’s public

key by ZATCA’s technical Certificate Authority (CA) is

required.

● An ECDSA signature is encoded according to

IEEE P1363. This signature format encodes

the (r, s) tuple as the concatenation of the big-

endian representation of r and the big-endian

representation of s.

● Each of these values is encoded using the number

of bytes required to encode the maximum integer

value in the key's mathematical field.

● For example, an ECDSA signature from 256-bit

elliptic curves (like secp256k1) encodes each of r

and s as 32 bytes, and produces a signature output

of 64 bytes.

Continue

Please find below an example:

public static byte[] extractR(String digitalSignature) throws

Exception {

MessageDigest digest = MessageDigest.

getInstance("SHA-256");

byte[] hash =

digest.digest(Base64.getDecoder().

decode(digitalSignature.getBytes(StandardCharsets.

UTF_8)));

return Arrays.copyOfRange(hash, 0, 32);

}

/**

* Extract S Component

* @return

* @throws Exception

4.1.3 Web Based Validator Business FAQs

Question

Answer

The Web-based validator can be accessed by anyone

What is the Web Based

from the Developer Portal. It is mainly built to enable

Validator for Non-Technical

non-technical users, (such as some tax and accounting

Users?

teams,) to test and validate XMLs as per e-invoicing

requirements.

The intended users of the Web Based Validator are

the non-technical users such as tax teams or accounts

Who is eligible to use the Web

teams for taxpayers. Anyone can accesses the

Based Validator?

Developer Portal (publicly available) to use the Web

Based Validator.

In case an XML has error(s), specific error messages

will be displayed. XMLs can be validated either via

What if XML has error(s)?

the Portal-based validator or the SDK again after the

error(s) are fixed.

It is not mandatory for Taxpayers to use the SDK or the

Is it mandatory to use the

Web Based Validator. However, ZATCA encourages

Compliance and Enablement

the technical and non-technical users (such as tax

Toolbox SDK or Web Based

teams or accounts teams) to use the SDK and Web

Validator?

Based Validator to ensure compliance with e-invoicing

requirements.

4.1.4 Integration Sandbox Business FAQs

Question

Answer

The Integration Sandbox (ISB) is a test platform developed

by ZATCA to simulate some of the core e-invoicing platform

(Fatoora) functionalities that will be available in the production

What is the Integration

system. Its primary objective is to allow Solution Developers

Sandbox?

to build compliant E-invoice Generation Solutions that can

submit requests to the ISB and obtain relevant responses to

indicate if their integration calls have been successful or if they

have any errors.

The Compliance and Enablement Toolbox (CET)

comprises of:

1. An offline SDK tool to validate QR Code and XMLs; and

2. A Portal-based Validator for non-technical users

(such as tax or accounts teams) to validate XMLs.

What is the difference

between the Compliance and

The Integration Sandbox allows testing integration of

Enablement Toolbox and the

taxpayer's E-invoicing solutions with a sandbox environment

Integration Sandbox?

using test APIs to send requests and documents in a similar

manner to how it would be done on the core e-invoicing

platform. This sandbox will perform validations that are part

of the SDK and some additional checks that cannot be done

offline or are specific to API requests. The SDK requires

XML files / QR code strings as inputs while the Integration

Sandbox requires an API request as input.

If my invoices are compliant

XMLs validated by the Toolbox are expected to receive

as per the Compliance and

successful responses on the Integration Sandbox also

Enablement Toolbox, will

unless there are issues with the API request itself.

they also pass the Integration

However, the Sandbox can also run some additional

Sandbox?

validations.

The intended users of the Integration Sandbox are e-invoicing

solution developers. Developers can register by providing

Will the Integration Sandbox be

the requested information and access the API documentation

available to Taxpayers only?

on the Developer Portal. VAT Registration details are not a

pre-requisite to register and access the Integration Sandbox.

No. Taxpayers who are required to integrate with ZATCA

Does passing the Integration

will have to undergo an Onboarding and Compliance

Sandbox mean the E-invoice

process to be able to submit electronic documents to ZATCA

Generation Solution can be used

starting from 1 January 2023 onwards. E-invoice Generation

by a Taxpayer to submit invoices

Solutions which undergo adequate testing on the Sandbox

to ZATCA?

will have a higher probability of completing that onboarding

and compliance process smoothly.

Can multiple invoices be

Yes. However, each invoice, credit or debit note should be

submitted to the Integration

part of a separate API call.

Sandbox?

Do invoices need to be submitted

The Integration Sandbox does not mandate that the invoices

in sequence to the Integration

should be submitted in sequence.

Sandbox?

Does ZATCA store the invoices

submitted to the Integration

No.

Sandbox?

Does the Integration Sandbox

No, dummy information can be provided as long as they

require actual taxpayer details

meet the syntax and content specifications and the XML

on the XML files?

implementation standards and validation rules.

No. The Integration Sandbox is not intended to validate actual

If an invoice has been cleared by

invoices and is for testing purposes only. The successful

the Integration Sandbox, can it be

validation of an XML using the Integration Sandbox should not

issued to a buyer?

be deemed as any kind of acceptance or approval by ZATCA.

Can I use the same username and

password that I used to access

Yes, the registration and login process is common for both

the Compliance and Enablement

the Compliance and Enablement Toolbox SDK and the

Toolbox SDK on the Developer

Integration Sandbox.

Portal to log into the Integration

Sandbox?

The CSID is technically a cryptographic certificate, which

is a credential that allows for authenticated signing and

encryption of communication. The certificate is also known

as a public key certificate or an identity certificate. It is an

electronic document used as proof of ownership of a public

What is a Cryptographic Stamp

key.

Identifier (CSID)?

The CSID is used to uniquely identify an Invoice Generation

Solution Unit in possession of a taxpayer for the purpose of

stamping (technically cryptographically signing) Simplified

Invoices and for accessing the Reporting and Clearance APIs

using TLS authentication.

A Compliance CSID is an intermediate CSID provided in

response to the CSR submission from an EGS or other solution.

In the Core E-invoicing Solution, the Compliance CSID is

What is the difference between

required to complete some compliance checks before the EGS

a Compliance and Production

or other solution is able the Production CSID which is required

CSID?

for authenticating the EGS or other solution to ZATCA. In the

Sandbox, the compliance checks are not required, and the

purpose is to therefore to test the integration calls of obtaining

the Compliance and Production CSIDs.

Yes. As long as the VAT Registration number on the CSID

matches the VAT Registration Number on the documents. In

other words, for every VAT Registration Number being tested

across any API call, a CSID with the same VAT Registration

Can I use the same CSID for any

Number is required. Note that the VAT Registration number can

invoice submission?

be any dummy number that meets the syntax specifications

(15 digits, starting with 3 and ending with 3).

Only a test Production CSID can be used for submitting

invoices, credit or debit notes as well as QR codes.

Errors are associated with invalid invoices, credit or debit

notes causing the rejection of such submissions. Warnings are

What is the difference between

associated with accepted documents which are still not fully

an error and warning?

compliant with the specifications and standards. Currently the

only warning case is an error with the Seller Address and is

meant for EGS units to be able to read warning messages.

4.2 Technical FAQs

4.2.1 Developer Portal Technical FAQs

Question

Answer

Where can I find more

User manuals contains detailed information on SDK,

information on the Compliance

Portal-based validator and the Integration Sandbox.

and Enablement Toolbox SDK,

These can be found in the dedicated pages on the

the Portal based validator and

Developer Portal.

the Integration Sandbox?

4.2.2 SDK Technical FAQs

Question

Answer

An XML is a way to present information in a structured

and machine readable format. The ZATCA e-invoice

What is an XML?

format is based on XML and several other XML-based

standards.

A CLI is a way to access and utilize a software application

using commands and it is text-based. CLI tools like the

fatoora tool can be used in scripts to create automations.

Sample: fatoora validatexml -f (invoicename.xml)

What is Command Line

In this example, we are naming an application called

Interface (CLI)?

"fatoora", in which we want to use the validatexml feature

with a-f command.

The second part that we add is: (invoicename.xml) which is

the path and filename of the XML to be validated.

Java is a programming language that runs on different

operating systems (OS), such as Windows and Linux. A JAR is

What is a Java and JAR?

a package file format that is generally used to aggregate many

Java class files and associated metadata and resources (text,

images, etc.) into one file for distribution.

Can I validate the Arabic language

No, since the CLI does not support Arabic characters

fields in a QR code within the CLI?

display.

What JAVA version should I

The prerequisite is using the Java SDK (JAR) versions

install before using the SDK?

>=11 and <15.

What should the user do when

When faced with a JAVA error, the user needs to install JAVA

faced with a JAVA error?

(versions >=11 and <15) before running and using the SDK.

4.2.3 Web Based Validator for Non-Technical Users Technical FAQs

Question

Answer

A QR code is a coded representation of readable text. In the

What is a QR code?

context of e-invoicing, the QR code should contain specific

information in a specific format.

In the context of e-invoicing, users should scan the QR

How can the users access

code on e-invoices, debit notes and credit notes by using

information contained in the QR

the ZATCA VAT app. This app is available on the Google

code?

Playstore and iOS App Store free of charge.

If an XML has error(s), specific error message(s) will be

displayed. Error(s) are likely to occur in cases such as when a

What can I do if an XML has

mandatory field is missing or a value is in an incorrect format.

error(s)?

The user may require the assistance of a technical expert to

solve the error(s).

4.2.4 Integration Sandbox Technical FAQs

Question

Answer

The "Reporting API" reports a single simplified invoice,

credit note, or debit note. Specifically, it accepts a simplified

invoice, credit note, or debit note encoded in base64 and

validates it to ensure:

Compliance to the UBL2 XSD.

What is the “Reporting API”?

2. EN 16931 Rules subset.

3. KSA Specific Rules set. KSA Rules set will override EN

16931 Rules set in case the same rule exists in both sets.

4. QR Code validation

5. Cryptographic Stamp validation

The user will need to do a POST Method on endpoint /

invoices/reporting/single and pass it on "authentication-

How can the user access

certificate" and accept-language as a parameter in the

"Reporting API"?

header. More information can be found on the Integration

Sandbox section of the Developer Portal.

The body object should Contain 2 Values: the first one is

called "invoiceHash" and the second one is called "invoice".

Example:

What's the Request Body the

{

user should send while calling

"invoiceHash": "string",

"Reporting API"?

"invoice": "string"

}

More information can be found on the Integration Sandbox

section of the Developer Portal.

The response will be 200 HTTP Ok with a Retrieved

object containing

4 values

: "invoiceHash","Status"

,"Warnings", "errors" .

Retrieved object Example:

{

What should the user expect

"invoiceHash": "TODO Add Invoice Hash",

as a response if calling the

"status": "Reported",

"Reporting API" was a success?

"warnings": null,

"errors": null

}

More information can be found on the Integration

Sandbox section of the Developer Portal.

The "Clearance API" clears a single standard invoice, credit

note, or debit note. Specifically, it accepts standard invoice,

credit note, or debit note encoded in base64 and validates it

to ensure:

Compliance to the UBL2 XSD.

What is the “Clearance API”?

2. EN 16931 Rules subset.

3. KSA Specific Rules set. KSA Rules set will override EN

16931 Rules set in case the same rule exists in both sets.

On successful validation, the api then applies a

cryptographic stamp from ZATCA side and generates a

QR Code string. After that the XML is returned back.

The user will need to do a POST Method on

endpoint /invoices/clearance/single and pass it on

How can the user access

"authentication-certificate" and accept-language

"Clearance API"?

as a parameter in the header. More information can

be found on the Integration Sandbox section of the

Developer Portal.

The body object should Contain 2 Values: the first one is

called "invoiceHash" and the second one is called "invoice".

Example:

What's the Request Body the

{

user should send while calling

"invoiceHash": "string",

"Clearance API"?

"invoice": "string"

}

More information can be found on the Integration Sandbox

section of the Developer Portal.

The response will be 200 HTTP Ok with a Retrieved

object containing

4 values

: "invoiceHash","Status"

,"Warnings", "errors" .

Retrieved object Example:

{

What should the user expect as

"invoiceHash": "TODO Add Invoice Hash",

a response if calling "Clearance

"status": "Reported",

API" was a Success?

"warnings": null,

"errors": null

}

More information can be found on the Integration

Sandbox section of the Developer Portal.

Code - Description

●

200- HTTP OK

●

202- Accepted with Errors, simplified invoice accepted

What are the Response causes

with warning errors

(Code & Description) that can

●

303- HTTP See Other. Returned when the submitted

appear while calling "Reporting

invoice is a Standard Invoice while clearance is activated

single API"?

●

400- HTTP Bad Request. Returned when the submitted

request is invalid

●

500- HTTP Internal Server Error. Returned when the

service faces internal errors

Code - Description

●

200- HTTP OK

●

202- Accepted with Errors, clearance invoice accepted

What are the Response causes

with warning errors

(Code & Description) that can

●

303- HTTP See Other. Returned when the submitted

appear while calling "Clearance

invoice is a Standard Invoice while clearance is

single API"?

activated

●

400- HTTP Bad Request. Returned when the submitted

request is invalid

●

500- HTTP Internal Server Error. Returned when the

service faces internal errors

A certificate signing request (CSR) is one of the first steps

towards getting a Cryptographic Stamp Identifier for a device

/ solution unit. The CSR contains information (e.g. common

name, organization, country) the ZATCA Certificate Authority

What is a CSR ?

(CA) will use to create your CSID. It also contains the public

key that will be included in your CSID and is signed with the

corresponding private key. Please refer to the CSID API

Swagger files for more details

5.2 Developer Portal Security Information

The Developer Portal uses HTTPS, as a secure method of communication between the browser and the

server. The user account is protected by a username and password. The session stays alive for 8 hours

after which the user will need to sign in again.

5.3 Generate CSR

5.3.1 Initiate a CSR configuration file (Open SSL Config. File)

As a part of the first-time onboarding and renewal process, the Taxpayer's EGS Unit(s) must submit a

CSR to the E-invoicing Platform once an OTP is entered into the EGS unit. The CSR is an encoded text

that the EGS Unit(s) submits to the E-invoicing Platform and the ZATCA CA in order to receive a Com-

pliance CSID, which is a self-signed certificate issued by the E-invoicing Platform allowing clients to

continue the Onboarding process.The certificate signing request is encoded text that service providers/

own solution will submit it to ZATCA CA. The digital certificate will be stored in the taxpayer device/s

and EGS identification data will rely on the data provided by the taxpayer through ZATCA Portal without

further validation and therefore, the taxpayer is fully responsible for the accuracy and legitimacy of the

data provided. Also, CSR contains the public key that will be included in the certificate, the private key is

usually created at the same time that service providers/ own solution create the CSR by their selves.

The CSR inputs (Open SSL Config. File) are as follows:

CSR Inputs

Business Term

Description

Specification

Provided by the Taxpayer for

Name or Asset

Common

each Solution unit: Unique

Tracking Number for

Free text

Name

Name or Asset Tracking

the Solution Unit

Number of the Solution Unit

Automatically filled and not by the

taxpayer: Unique identification code

Free text

Manufacturer or

for the EGS.

Validate the format

Solution Provider

Manufacturer serial number for

EGS Serial

with a Regular

Name, Model or

each solution unit including

Number

Expression (1-...| 2-...

Version and Serial

| 3-

)

Number

Manufacturer or Solution

Provider Name | 2-Model or

Version | 3-SerialNumber

VAT Registration Number of the

VAT or Group

Taxpayer (Taxpayer / Taxpayer

Organization

15 digits, starting and

VAT Registration

device to provide this to allow

Identifier

ending with 3

Number

to check if the OTP is correctly

associated with this TIN)

If 11th digit of

Organization Identifier

The branch name for taxpayers.

is not = 1 then Free

In case of VAT Groups this field

text

Organization

should contain the 10-digit TIN

Organization Unit

Unit Name

number of the individual group

If 11th digit of

member whose EGS Unit is

Organization Identifier

being onboarded

= 1 then needs to be a

10 digit number

Organization

Taxpayer Name

Organization/Taxpayer Name

Free text

Name

Country Name

Name of the country

2 letter code

The document type that the

Taxpayer’s solution unit will be

issuing/generating. It can be one

4-digit binary number

Invoice Type

(Functionality

Functionality Map

or a combination of Standard Tax

(0s and 1s only, cannot

Map)

Invoice (T), Simplified Tax Invoice

all be 0s)

(S), Buyer QR code (C), Seller’s

QR code in self-billing (Z).

The input should be using the

digits 0 & 1 and mapping those to

“TSCZ” where:

0 = False/Not supported

1= True/Supported

4-digit

binary

Invoice Type

number (0s and 1s

(Functionality

Functionality Map

For example: 1000 would mean

only, cannot all be

Map)

Solution will be generating

0s)

Standard Invoices only. 0100

would mean Solution will be

generating Simplified invoices

only. and 1100 means Solution

will be generating both Standard

and Simplified invoices

The address of the Branch or

location where the device or

Location of Branch

Location

solution unit is primarily situated

Free Text

or EGS Unit

(could be website address for

e-commerce)

Organization

Taxpayer Name

Organization/Taxpayer Name

Free text

Name

Industry or sector for which the

Industry

Industry or Location

device or solution will generate

Free Text

invoices

The screenshot below represents the information the user must use to generate a CSR (using Open SSL

Command Tool) and its configuration file as shown below. For further information, please see link: /

index.html (openssl.org)

5.3.2 Generate public/private key pair

● According to security implementation document the Key pair shall be generated according to FIPS

186. Further, reasonable techniques shall be used to validate the suitability of the generated key

pair.

● The suitability of keys shall be done according to either the ECC Full Public Key Validation Routine or

the ECC Partial Public Key Validation Routine. [Source: Sections 5.6.2.3.2 and 5.6.2.3.3, respective-

ly, of NIST SP 56A: Revision 2].

● Keys must be marked as non-exportable in order to prohibit key export out of the security module

where the key was generated

● A hardware or software based security module can be used to generate and store the key pair as

long as the above requirements are met.

5.3.2.1 Generate Private Key

The service providers/ own solution need to keep the private key secret. The created certificate will

only work with a particular private key that was generated. So if the private key lost, the certificate

will no longer work. we are generating a pair of ECDSA keys with the P-256 (secp256k1) curve, the

PrivateKey.pem file will be the generated private key, change the file name to YourPrivateKey.pem.

the following command show how to generate a private key using OpenSSL:

Sample contents of the PrivateKey.pem private key in PEM format:

5.3.2.2 Generate Public Key

The compressed public key will be created by extracting it from the private key, extracting ECDSA

keys with the P-256 (secp256k1) curve, the PublicKey.pem file will be the extracted public key,

change the file name to YourPublicKey.pem. The following command show how to extract a public

key using OpenSSL:

By using the compressed public key only X values will be used in the elliptic curves: