Onboarding

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

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.

Shell

# You can also use wget
curl -X POST https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/csrRequest \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Javascript

const inputBody = '{
  "csrInputs": {
    "otp": "123345",
    "commonName": "TST-886431145-300055184400003",
    "serialNumber": "1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt",
    "organizationIdentifier": "300055184400003",
    "organizationUnitName": "Riyadh",
    "organizationName": "Complyance",
    "countryName": "SA",
    "invoiceType": "1100",
    "location": "Riyadh",
    "industry": "Civil"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/csrRequest',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Ruby

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/csrRequest',
  params: {
  }, headers: headers

p JSON.parse(result)

Python

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/csrRequest', headers = headers)

print(r.json())

PHP

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/csrRequest', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

Java

URL obj = new URL("https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/csrRequest");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

Go

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/csrRequest", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Request Parameters

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.	Complyance 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

Response Parameters

PARAMS	DATA TYPE	DESCRIPTION	EXAMPLE
status	string	Status of onboarding by ZATCA. Onboarding involves multiple internal steps(API calls) with the ZATCA platform and, for API simplification the status is classified as success or failure on the whole. The enum value is according to the respective scenarios listed below: 1) Successfully onboarded with ZATCA's Fatoora Portal - SUCCESS2) OnboardiNg failed with ZATCA's Fatoora Portal due to various errors - ERROR This field will not be present for request level errors(field format errors)	SUCCESS
errors	list	If onboarding fails because of error from the APIs in ZATCA layer, the corresponding API error messages will be returned here. Please log this error response for RCA.	[...]
code	string	Error status code of the failed ZATCA API.	400 BAD_REQUEST
message	string	Error message from the corresponding API	OTP is required field

Body parameter

{
  "csrInputs": {
    "otp": "123345",
    "commonName": "TST-886431145-300055184400003",
    "serialNumber": "1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt",
    "organizationIdentifier": "300055184400003",
    "organizationUnitName": "Riyadh",
    "organizationName": "Complyance",
    "countryName": "SA",
    "invoiceType": "1100",
    "location": "Riyadh",
    "industry": "Civil"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none

Example responses

OK

{
  "status": "SUCCESS",
  "errors": []
}

{
  "status": "ERROR",
  "errors": [
    {
      "code": "400 BAD_REQUEST",
      "message": "OTP is required field"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	Inline

Response Schema

Response Headers

Status	Header	Type	Format	Description
200	Date	string		none
200	Content-Type	string		none
200	Content-Length	integer		none
200	Connection	string		none
200	x-amzn-RequestId	string		none
200	x-amz-apigw-id	string		none
200	X-Amzn-Trace-Id	string		none

To perform this operation, you must be authenticated by means of one of the following methods: oauth2Auth