Egs OnBoarding

After successfully completing the signup, sign-in, and generating a unique API Key, the next important step is to ensure the security of your API Key. This step initiates the onboarding phase. The Onboarding API acts as the bridge for integrating your E-Invoice Generation Solution (EGS) into the ZATCA sandbox environment. Make sure to input the required parameters in the specified format, and you have the flexibility to include additional parameters to align with your specific needs.

Integrating Your API Key: To seamlessly integrate your E-Invoice Generation Solution (EGS), follow these steps:

1. Copy the API Key you received from your api key generation step

2. Go to the EGS onboarding tab here or the EGS onboarding file in postman and select "Header tab"

3. Locate the "x-api-key" value and paste your API Key into the current Token field.

Once you send the request, you'll receive the following confirmation message: "For example EGS eBMSTest1234 has been successfully onboarded.”

Request Parameters:

Example Request

{
  "csrInputs": {
    "otp": "047307",
    "commonName": "CreditNotes-Sales-Simulation",
    "serialNumber": "1-CreditNotes|2-Sales|3-9c15663c-592c-4593-9888-d3620285fb60",
    "organizationIdentifier": "300055134400003",
    "organizationUnitName": "Jeddah",
    "organizationName": "JS Retail Demo",
    "countryName": "SA",
    "invoiceType": "1100",
    "location": "Jeddah",
    "industry": "Manufacturing",
    "isB2B": true,
    "isB2C": true,
    "b2BRequirements": {
      "isSelfBilling": false,
      "isThirdParty": false,
      "isSummaryPresent": false,
      "isExport": false,
      "isNominal": false
    },
    "b2CRequirements": {
      "isThirdParty": false,
      "isSummaryPresent": false,
      "isNominal": false
    }
  }
}

PARAMS	REQUIRED	DATA TYPE	DESCRIPTION	EXAMPLE
csrInputs	YES	pipes	The csr(certificate signing request) details you need to provide for onboarding the EGS.	Refer to the sample request body
otp	YES	string	The OTP that you'll get from the Fatoora Portal(logged in using taxpayer credentials) after following the ZATCA onboarding process as per Antna Guidelines document.	123345
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-300055184400003
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 (Refer to the sample request body for the correct format)
organizationIdentifier	YES	string	It is the organization VAT number. It is a 15 digit number with starting and ending digits as '3'.	300055184400003
organizationUnitName	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. If 11th digit of Organization Identifier is not = 1 then Free text and if 11th digit of Organization Identifier = 1 then needs to be a 10 digit number.	Riyadh
organizationName	YES	string	Name of the Taxpayer. It can be free text.	Antna Technologies Private Limited
countryName	YES	string	Name of the country. 2 letter code (ISO 3166 Alpha-2)	SA
invoiceType	YES	string	The document type that the Taxpayer’s solution unit will be issuing/generating. It can be one or a combination of Standard Tax Invoice (T), Simplified Tax Invoice (S), (X), (Y). The input should be using the digits 0 & 1 and mapping those to “TSXY” where: 0 = False/Not supported 1= True/Supported (X) and (Y) are for future use and should be set to 0 by default for the time being. For example: 1000 would mean Solution will be generating Standard Invoices only. 0100 would mean Solution will be generating Simplified invoices (B2C) only and 1100 means Solution will be generating both Standard (B2B) and Simplified invoices (B2C).	1100
location	YES	string	The address of the Branch or location where the device or solution unit is primarily situated (could be website address for e-commerce). Preferably(not mandatory) in the Short Address format of the Saudi National Address https://splonline. com.sa/en/national- address-1/. Free text will be accepted.	Riyadh
industry	YES	string	Industry or sector for which the device or solution(EGS) will generate invoices. Free text will be accepted.	Petroleum
isB2B	YES	boolean	Indicator for organization engages in Business-to-Business (B2B) transactions	true
isB2C	YES	boolean	Indicator for organization engages in Business-t0-Consumer (B2C) transactions	true
b2BRequirements	YES	json	Details about the B2B business	{...}\
b2CRequirements	YES	boolean	Details about the B2C business	{...}\

---

B2B Requirements

PARAMS	REQUIRED	DATA TYPE	DESCRIPTION	EXAMPLE
isSelfBilling	YES	boolean	Indicates whether the organization practices self-billing.	false
isThirdParty	YES	boolean	Indicates whether third parties are involved in B2B transactions.	false
isSummaryPresent	YES	boolean	Indicate whether a summary is present in B2B transactions.	false
isExport	YES	boolean	Indicates whether an organization is involved in international trade and exports goods to other countries	false
isNominal	YES	boolean	Indicates whether nominal values are used in B2B transactions.	false

---

B2C Requirements

PARAMS	REQUIRED	DATA TYPE	DESCRIPTION	EXAMPLE
isThirdParty	YES	boolean	Indicates whether third parties are involved in B2C transactions.	false
isSummaryPresent	YES	boolean	Indicate whether a summary is present in B2C transactions.	false
isNominal	YES	boolean	Indicates whether nominal values are used in B2C transactions.	false

---

Example Response

EGS eBMSTest1234 has been successfully onboarded.

Response Parameters:

PARAMS	DATA TYPE	DESCRIPTION	EXAMPLE
message	string	Sucess or failure message for egs onboarding	EGS eBMSTest1234 has been successfully onboarded.