Report Document

Use this API to report your EGS(E-Invoice Generation Solution) generated B2C documents(Simplified Tax Invoice or Simplified Tax Invoice Credit Note or Simplified Tax Invoice Debit Note )to the ZATCA's sandbox environment.

You have to pass all the required params in the specified format at the minimum to report your document 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/reportDocument \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Javascript

const inputBody = '{
  "invoiceData": {
    "documentType": "SIMPLIFIED_TAX_INVOICE",
    "referenceId": "",
    "documentIssueDateTime": "2022-12-30T09:58:24.000Z",
    "documentDueDateTime": "2022-12-30T09:58:24.000Z",
    "sellerName": "ahmad abdurrahman",
    "sellerAddress": {
      "addrLine1": "12, Masjid Street",
      "addrLine2": "Amjad Building",
      "additionalNo": "1234",
      "buildingNumber": "1234",
      "city": "Dammam",
      "state": "Riyadh",
      "zipCode": "12313",
      "district": "Riyadh",
      "country": "SA"
    },
    "buyerName": "Zahid Gani",
    "documentLineItems": [
      {
        "lineItemDesc": "HP Laptop/Hp Laptop",
        "lineItemPrice": 578,
        "lineItemQty": 1,
        "lineItemTaxableAmount": 573,
        "discountOnLineItem": 5,
        "vatRateOnLineItem": 15,
        "lineItemVatAmount": 85.95,
        "lineItemSubTotal": 658.95
      },
      {
        "lineItemDesc": "HP Laptop/Hp Laptop",
        "lineItemPrice": 578,
        "lineItemQty": 1,
        "lineItemTaxableAmount": 573,
        "discountOnLineItem": 5,
        "vatRateOnLineItem": 15,
        "lineItemVatAmount": 85.95,
        "lineItemSubTotal": 658.95
      }
    ],
    "totalExcludingVat": 1112,
    "totalTaxableAmountExcludingVat": 1146,
    "vatTotal": 166.8,
    "documentTotal": 1278.8,
    "discountOnDocumentTotal": 34,
    "isSpecialBillingAgreement": "false",
    "isTransactionType": "false",
    "isSelfBilled": "false",
    "isThirdParty": "false",
    "isNominalSupply": "false",
    "isExport": "false",
    "isSummary": "false",
    "supplyDate": "2022-12-30T09:58:24.000Z",
    "sellerVatRegistrationNumber": "300055184400003",
    "sellerGroupVatRegistrationNumber": "",
    "additionalSellerIdType": "CRN",
    "additionalSellerIdNumber": "1112233344",
    "specialTaxTreatment": "0",
    "currency": "SAR",
    "documentId": "001"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('https://t5wtfl1d2e.execute-api.ap-south-1.amazonaws.com/test/api/v1/proto/reportDocument',
{
  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/reportDocument',
  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/reportDocument', 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/reportDocument', 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/reportDocument");
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/reportDocument", data)
    req.Header = headers

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

Request Parameters:

PARAMS	REQUIRED	DATA TYPE	DESCRIPTION	EXAMPLE
invoiceData	YES	json	The csr(certificate signing request) details you need to provide for onboarding the EGS.	{...}\
documentType	YES	string	For the following documents types, use the corresponding enums: 1) Simplified Tax Invoice - SIMPLIFIED_TAX_INVOICE 2) Simplified Tax Invoice Credit Note - SIMPLIFIED_TAX_INVOICE_CREDIT_NOTE3) Simplified Tax Invoice Debit Note - SIMPLIFIED_TAX_INVOICE_DEBIT_NOTE	SIMPLIFIED_TAX_INVOICE
referenceId	CONDITIONAL	string	ID of the original document(reference document) for which this document is generated. Applicable only for document types: 1) Simplified Tax Invoice Credit Note2) Simplified Tax Invoice Debit Note Example: If the document type is Simplified Credit Note, the reference id should be Invoice number for which this credit note is being created.	2022100627
documentIssueDateTime	YES	string	Document Issue Date and Time in "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format.	2022-10-21T12:53:13.000Z
documentDueDateTime	NO	string	Document Due Date and Time in "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format.	2022-10-21T12:53:13.000Z
sellerName	YES	string	Name of the seller	Company Name
sellerAddress	YES	json	Address of the seller with the below mentioned fields.	{ "addrLine1": "Makkah", "addrLine2": "Al Alam Street", "additionalNo": "1234", "buildingNumber": "1234" "city": "Riyadh", "state": "Riyadh", "zipCode": "24211", "district": "Riyadh", "country": "SA" }\
buyerName	CONDITIONAL	string	Buyer Name is mandatory to be filled as per the transactions mentioned in article 53 (7) and for private education and private healthcare to citizens.	Vignesh K
buyerAddress	NO	json	Buyer address	{ "addrLine1": "Makkah", "addrLine2": "Al Alam Street", "additionalNo": "1234", "buildingNumber": "1234" "city": "Riyadh", "state": "Riyadh", "zipCode": "24211", "district": "Riyadh", "country": "SA" }\
addrLine1	YES	string	Address Line 1	Makkah
addrLine2	YES	string	Address Line 2	Al Alam Street
buildingNumber	YES	string	Building Number	2221
additionalNo	YES	string	Additional Number(4 digits)	2134
city	YES	string	City	Riyadh
state	YES	string	State	Riyadh
zipCode	YES	string	Postal Code(5 digits)	24211
country	YES	string	Country code. 2 letter code (ISO 3166 Alpha-2)	SA
documentLineItems	YES	array	Line items list	[...]
lineItemDesc	YES	string	Line item description	Ball point pen
lineItemPrice	YES	number	Line item price	10.00
lineItemQty	YES	number	Line item quantity	10.00
lineItemTaxableAmount	YES	number	Line item taxable amount lineItemTaxableAmount = (lineItemPrice * lineItemQty) - discountOnLineItem	100.00
discountOnlineItem	YES	number	Discount in amount applied on the line item	0.00
vatRateOnLineItem	YES	number	Vat Rate applied to the line item	15.00
lineItemVatAmount	YES	number	Vat amount of the line item lineItemVatAmount = (lineItemTaxableAmount * vatRateOnLineItem)/100	15.00
lineItemSubTotal	YES	number	Total of the Line Item lineItemSubTotal = lineItemTaxableAmount + lineItemVatAmount	115.00
totalExcludingVat	YES	number	totalExcludingVat = documentTotal - totalVat	100.00
totalTaxableAmountExcludingVat	YES	number	totalTaxableAmountExcludingVat = sum of all lineItemTaxableAmount of line items - discountOnDocumentTotal(if applied)	100.00
vatTotal	YES	number	vatTotal = sum of all lineItemVatAmount of line items	15.00
documentTotal	YES	number	documentTotal = totalTaxableAmountExcludingVat + vatTotal	115.00
isSpecialBillingAgreement	YES	boolean	If transaction for the following conditions: 1) Self-billed invoice 2) Third party billed invoice on behalf of the supplier	false
isTransactionType	YES	boolean	If transaction is any of the following(not mutually exclusive): 1) Nominal Supply 2) Export 3) Summary	false
isSelfBilled	YES	boolean	If isSpecialBillingAgreement is true and self - billed condition	false
isThirdParty	YES	boolean	If isSpecialBillingAgreement is true and Third party condition	true
isNominalSupply	YES	boolean	If isTransactionType is true and nominal supply condition	false
isExport	YES	boolean	If isTransactionType is true and export condition	false
isSummary	YES	boolean	If isTransactionType is true and summary invoice condition	false
supplyDate	YES	string	Goods/Service supply Date and Time in "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format.
sellerVatRegistrationNumber	YES	string	Seller Vat registration number	300055184400003
additionalSellerIdType	YES	string	For the following Seller ID types, use the corresponding enums in bold: 1) Commercial registration number with "CRN" as schemeID 2) Momra license with "MOM" as schemeID - 3) MLSD license with "MLS" as schemeID 4) Sagia license with "SAG" as schemeID 5) Other OD with "OTH" as schemeID In case multiple IDs exist then one of the above must be entered following the sequence specified above	CRN
additionalSellerIdNumber	YES	string	Additional seller ID number of the ID type chosen	1112233344
sellerGroupVatRegistrationNumber	CONDITIONAL	string	Group Vat registration number of the seller	300244974200003
additionalBuyerIdType	CONDITIONAL	string	Required only for private education or private healthcare supplies to Citizens. This field should contain the National ID only for invoices pertaining to private education and private healthcare to citizens. National ID is mandatory to be filled for private education and private healthcare to citizens. Enum - NATIONAL_ID	NATIONAL_ID
additionalBuyerIdNumber	CONDITIONAL	string	Buyer's NATIONAL ID number	112233445566
discountOnDocumentTotal	NO	number	Discount applied on document total	0.00
specialTaxTreatment	CONDITIONAL	string	Where Tax is not charged at the standard rate, this field should have a narration “Tax treatment applied to the supply” as per Article 53 of the VAT Implementing Regulation. Narration to be entered if Tax is not charged at basic rate.	0
vatCurrency	CONDITIONAL	string	If document currency is not "SAR", please provide vatCurrency. 'vatTotal' will be always accounted in 'SAR' even when the document currency is not in 'SAR'	SAR
noteIssuanceReason	CONDITIONAL	string	Reason for issuing credit/debit note. Reasons for issuance of credit / debit note as per Article 40 (paragraph 1) and Article 54 (3) of KSA VAT regulations, a Credit and Debit Note is issued for these 5 instances: 1) Cancellation or suspension of the supplies after its occurrence either wholly or partially 2) In case of essential change or amendment in the supply, which leads to the change of the VAT due; 3) Amendment of the supply value which is pre-agreed upon between the supplier and consumer; 4) In case of goods or services refund. 5)In case of change in Seller's or Buyer's information	Cancellation or suspension of the supplies after its occurrence either wholly or partially
currency	YES	string	Transaction Currency of the document	SAR
documentId	YES	number	A unique identification of the Invoice - Invoice Reference number(IRN)	2022100627

Response Parameters

PARAMS	DATA TYPE	DESCRIPTION	EXAMPLE
isReported	boolean	Reporting status of the B2C document with ZATCA. Please refer to the zatcaResponse field if this field is false to know more about the specific error from ZATCA.	true
zatcaResponse	list	Proxy of ZATCA Reporting API response. Will be populated for both success and failure scenarios.	{ "validationResults": { "infoMessages": [ { "type": "INFO", "code": "XSD_ZATCA_VALID", "category": "XSD validation", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications", "status": "PASS" }\ ], "warningMessages": [], "errorMessages": [], "status": "PASS" }, "reportingStatus": "REPORTED", "timestamp": 0, "status": 0 }\

Body parameter

{
  "invoiceData": {
    "documentType": "SIMPLIFIED_TAX_INVOICE",
    "referenceId": "",
    "documentIssueDateTime": "2022-12-30T09:58:24.000Z",
    "documentDueDateTime": "2022-12-30T09:58:24.000Z",
    "sellerName": "ahmad abdurrahman",
    "sellerAddress": {
      "addrLine1": "12, Masjid Street",
      "addrLine2": "Amjad Building",
      "additionalNo": "1234",
      "buildingNumber": "1234",
      "city": "Dammam",
      "state": "Riyadh",
      "zipCode": "12313",
      "district": "Riyadh",
      "country": "SA"
    },
    "buyerName": "Zahid Gani",
    "documentLineItems": [
      {
        "lineItemDesc": "HP Laptop/Hp Laptop",
        "lineItemPrice": 578,
        "lineItemQty": 1,
        "lineItemTaxableAmount": 573,
        "discountOnLineItem": 5,
        "vatRateOnLineItem": 15,
        "lineItemVatAmount": 85.95,
        "lineItemSubTotal": 658.95
      },
      {
        "lineItemDesc": "HP Laptop/Hp Laptop",
        "lineItemPrice": 578,
        "lineItemQty": 1,
        "lineItemTaxableAmount": 573,
        "discountOnLineItem": 5,
        "vatRateOnLineItem": 15,
        "lineItemVatAmount": 85.95,
        "lineItemSubTotal": 658.95
      }
    ],
    "totalExcludingVat": 1112,
    "totalTaxableAmountExcludingVat": 1146,
    "vatTotal": 166.8,
    "documentTotal": 1278.8,
    "discountOnDocumentTotal": 34,
    "isSpecialBillingAgreement": "false",
    "isTransactionType": "false",
    "isSelfBilled": "false",
    "isThirdParty": "false",
    "isNominalSupply": "false",
    "isExport": "false",
    "isSummary": "false",
    "supplyDate": "2022-12-30T09:58:24.000Z",
    "sellerVatRegistrationNumber": "300055184400003",
    "sellerGroupVatRegistrationNumber": "",
    "additionalSellerIdType": "CRN",
    "additionalSellerIdNumber": "1112233344",
    "specialTaxTreatment": "0",
    "currency": "SAR",
    "documentId": "001"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none

Example responses

OK

{
  "zatcaResponse": {
    "validationResults": {
      "infoMessages": [
        {
          "type": "INFO",
          "code": "XSD_ZATCA_VALID",
          "category": "XSD validation",
          "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
          "status": "PASS"
        }
      ],
      "warningMessages": [],
      "errorMessages": [],
      "status": "PASS"
    },
    "reportingStatus": "REPORTED",
    "timestamp": 0,
    "status": 0
  },
  "isReported": true
}

{
  "isReported": false
}

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	Access-Control-Allow-Origin	string		none
200	Access-Control-Allow-Headers	string		none
200	x-amz-apigw-id	string		none
200	Access-Control-Allow-Methods	string		none
200	Access-Control-Expose-Headers	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