KSA v2: Onboard your EGS

Onboard your E-Invoice Generation Solution (EGS) to the ZATCA sandbox with the KSA ZATCA API v2, using your API key and an OTP from the Fatoora portal. This page documents API v2, a legacy version.

After you sign up, sign in and generate an API key, onboard your E-Invoice Generation Solution (EGS). The onboarding API registers your EGS in the ZATCA sandbox. Send the required parameters in the format shown below. You can add other parameters to fit your needs.

Add your API key

Copy the API key you received when you generated it.
Send it in the x-api-key header of the onboarding request.

When the request succeeds, you receive a confirmation message such as EGS EGS-TEST-1234 has been successfully onboarded.

Endpoint

http

POST https://api.complyance.io/sandbox/v2/egsOnboarding

Example request

Request bodyjson

{
  "csrInputs": {
    "otp": "047307",
    "commonName": "CreditNotes-Sales-Simulation",
    "serialNumber": "1-CreditNotes|2-Sales|3-9c15663c-592c-4593-9888-d3620285fb60",
    "organizationIdentifier": "300000000000003",
    "organizationUnitName": "Jeddah",
    "organizationName": "Acme Trading LLC",
    "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
    }
  }
}

Request parameters

Parameter	Required	Type	Description	Example
`csrInputs`	Yes	object	The certificate signing request (CSR) details you provide to onboard the EGS.	See the example request.
`otp`	Yes	string	The OTP you get from the Fatoora portal, signed in with the taxpayer’s credentials, after you follow the ZATCA onboarding process.	`123345`
`commonName`	Yes	string	A unique name or asset tracking number for your EGS. There is no fixed format: any free text is accepted.	`TST-886431145-300000000000003`
`serialNumber`	Yes	string	A unique identification code for the EGS. It must match the regular expression `1-(.+)\|2-(.+)\|3-(.+)`. See the example request for the format.	`1-TST\|2-TST\|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt`
`organizationIdentifier`	Yes	string	The organization’s VAT number: a 15-digit number that starts and ends with 3.	`300000000000003`
`organizationUnitName`	Yes	string	The taxpayer’s branch name. For a VAT group, the 10-digit TIN of the group member whose EGS unit you are onboarding. If the 11th digit of `organizationIdentifier` is not 1, this is free text. If the 11th digit is 1, it must be a 10-digit number.	`Riyadh`
`organizationName`	Yes	string	The taxpayer’s name. Free text.	`Acme Trading LLC`
`countryName`	Yes	string	The country, as a 2-letter code (ISO 3166 Alpha-2).	`SA`
`invoiceType`	Yes	string	The document types this EGS unit issues: Standard Tax Invoice (T), Simplified Tax Invoice (S), (X) and (Y), written as four digits in the order TSXY. 1 means supported and 0 means not supported. X and Y are reserved for future use and must be 0. For example, `1000` means the EGS issues standard (B2B) invoices only, `0100` means simplified (B2C) invoices only, and `1100` means both.	`1100`
`location`	Yes	string	The address of the branch or location where the EGS unit is mainly based. For e-commerce, this can be a website address. The short address format of the Saudi National Address is preferred but not required. Free text is accepted.	`Riyadh`
`industry`	Yes	string	The industry or sector the EGS issues invoices for. Free text.	`Petroleum`
`isB2B`	Yes	boolean	Whether the organization makes business-to-business (B2B) transactions.	`true`
`isB2C`	Yes	boolean	Whether the organization makes business-to-consumer (B2C) transactions.	`true`
`b2BRequirements`	Yes	object	Details about the B2B business. See B2B requirements.	`{...}`
`b2CRequirements`	Yes	object	Details about the B2C business. See B2C requirements.	`{...}`

B2B requirements

Parameter	Required	Type	Description	Example
`isSelfBilling`	Yes	boolean	Whether the organization uses self-billing.	`false`
`isThirdParty`	Yes	boolean	Whether third parties are involved in B2B transactions.	`false`
`isSummaryPresent`	Yes	boolean	Whether B2B transactions include summary invoices.	`false`
`isExport`	Yes	boolean	Whether the organization exports goods to other countries.	`false`
`isNominal`	Yes	boolean	Whether B2B transactions use nominal values.	`false`

B2C requirements

Parameter	Required	Type	Description	Example
`isThirdParty`	Yes	boolean	Whether third parties are involved in B2C transactions.	`false`
`isSummaryPresent`	Yes	boolean	Whether B2C transactions include summary invoices.	`false`
`isNominal`	Yes	boolean	Whether B2C transactions use nominal values.	`false`

Example response

Response

EGS EGS-TEST-1234 has been successfully onboarded.

Response parameters

Parameter	Type	Description	Example
`message`	string	The success or failure message for EGS onboarding.	`EGS EGS-TEST-1234 has been successfully onboarded.`

If onboarding fails, see the CSR request messages in Error messages.

Next step

Send your first document to the Unify API.