Generate Einvoice APIs

Input Type
We accept two forms of inputs to generate the einvoice these are
XML (In accordance to UBL2.1 regulations)
JSON (custom built by MI to support the requirments of UBL2.1 and ZATCA Phase II accordance
XML
The xml input needs to be base64 encoded. I have attached some sample documents which can referred to.
Standard_Invoice.xml
6KB
Text
Standard Invoice Document
Standard_Debit_note.xml
6KB
Text
Standard Debit Note Document
Standard_Credit_note.xml
6KB
Text
Standard Credit Note Document
Simplified_Invoice.xml
6KB
Text
Simplified Invoice Document
Simplified_Credit_note.xml
6KB
Text
Simplified Credit Note Document
Simplified_Debit_note.xml
6KB
Text
Simplified Debit Note Document
Before the invoice is reported or cleared to ZATCA we will add the following xpaths within the XML
For Standard Documents
UUID
IssueDate
IssueTime
Invoice Counter Value (ICV)
Previous Invoice Hash (PIH)
For Simplified Documents
UBL Extensions
UUID
IssueDate
IssueTime
Invoice Counter Value (ICV)
Previous Invoice Hash (PIH)
QR Code
XML Signature
JSON
If you cannot provide an XML document as input you can provide the required document information via a JSON input. We have constructed a schema which supports the requirements to generate all the document types acceptable by ZATCA. I have attached some documents for the various documents for your reference.
Standard_Invoice.json
3KB
Code
Standard Invoice Document
Standard_Debit_Note.json
3KB
Code
Standard Debit Note Document
Standard_Credit_Note.json
3KB
Code
Standard Credit Note Document
Simplified_Invoice.xml
6KB
Text
Simplified Invoice Document
Simplified_Debit_note.xml
6KB
Text
Simplified Debit Note Document
Simplified_Credit_Note.json
3KB
Code
Simplified Credit Note Document
A detailed description of schema can be found here . Using this schema we generate a UBL2.1 compliant XML document with addition to the xpaths mentioned above and process REPORT or CLEAR the invoice to ZATCA.
Generate Einvoice API
XML Input
​
post
https://qa-globalback.mastersindia-einv.com/api/v2/ksa_einvoice/generate_einvoice/
JSON Input
Text
Description
URL
​https://qa-globalback.mastersindia-einv.com/api/v2/ksa_einvoice/generate_einvoice/​
Method Type
POST
Headers
"Productid": "einvoicing_global"  (keep as is)
"Service": "online_service" (keep as is)
"Authorization": "JWT <token>" (Used from token-auth API)                             
Body
{ "invoice_id": "100", "issue_date": "2023-06-05", "issue_time": "23:40:23", "invoice_type": { "type": "invoice", "txn_type": "simplified", "txn_sub_type": "self_billed" }, "doc_currency_code": "SAR", "tax_currency_code": "SAR", "supplier_party": { "party_identification": { "scheme_id": "MLS", "id": "123457890" }, "postal_address": { "street_name": "King Abdulaziz Road", "building_num": 8228, "plot_identification_num": 2121, "city_subdivision": "Al Amal", "city": "string", "postal_zone": 12643, "country_sub_entity": "Riyadh Region", "country_code": "SA" }, "vat_info": { "vat_number": 312343768911433, "registration_name": "Al Salam Supplies Co. LTD" } }, "customer_party": { }, "actual_delivery_date": { "year": 2023, "month": 1, "day": 1 }, "latest_delivery_date": { "year": 2023, "month": 1, "day": 2 }, "payment_means": { "code": 10, "instruction_note": "Paid in full" }, "allowance_charge": [{ "charge_indicator": false, "allowance_charge_reason": "Sample Allowance", "allowance_charge_amt": { "amt": 0.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 12 } }], "legal_monetary_total": { "line_extension_amt": { "amt": 900.00, "currency": "SAR" }, "allowance_total_amt": { "amt": 0.00, "currency": "SAR" }, "tax_exclusive_amt": { "amt": 900.00, "currency": "SAR" }, "tax_inclusive_amt": { "amt": 1035.00, "currency": "SAR" }, "payable_amt": { "amt": 1035.00, "currency": "SAR" }, "prepaid_amt": { "amt": 0.00, "currency": "SAR" } }, "tax_total": { "tax_amt": { "amt": 135.00, "currency": "SAR" }, "sub_total": { "taxable_amt": { "amt": 900.00, "currency": "SAR" }, "tax_amt": { "amt": 135.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 15 } } }, "invoice_lines": [ { "qty": 1, "unit_code": "PCE", "line_extension_amt": { "amt": 200.00, "currency": "SAR" }, "tax_amt": { "amt": 30.00, "currency": "SAR" }, "total_amt": { "amt": 230.00, "currency": "SAR" }, "price_amt": { "amt": 200.00, "currency": "SAR" }, "item": { "name": "Item A", "tax_category": { "id": "S", "percent": 15 } } }, { "qty": 2, "unit_code": "PCE", "line_extension_amt": { "amt": 700.00, "currency": "SAR" }, "tax_amt": { "amt": 105.00, "currency": "SAR" }, "total_amt": { "amt": 805.00, "currency": "SAR" }, "price_amt": { "amt": 350.00, "currency": "SAR" }, "item": { "name": "Item B", "tax_category": { "id": "S", "percent": 15 } } } ] }
Response (Simplified Documents)
{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "REPORTED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }
Response (Standard Documents)
{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "CLEARED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }
Technical Guidelines (Online APIs)
We can consider the ID in the XML and JSON input as primary key (cbc:ID in XML and invoice_id in JSON). eg if an invoice is passed with id "1" then we sign and submit the invoice.  If the reporting status is successful then we update our database and archive the invoice. If another invoice is passed with id "1" again. Then we return the reponse of the earlier API and do not report the invoice again to ZATCA.
Taking the above scenario further, if invoice id "1" is rejected by ZATCA. Then the API caller can fix the errors and pass the invoice with the same id again. In this scenario we resubmit the invoice to ZATCA with a new counter and QR code. This process can repeated until the invoice is succesfully reported to ZATCA.
Both XSL and XSD validation are done for the invoice prior to sending the request to ZATCA
Both Standard and Simplified documents are notified to ZATCA in real time
​
Generate Einvoice Offline API
This API would be exposed within the offline utility after the successful onboarding of the utility. Thus the API call would have to be via localhost to connect to the utility (or via a local VPN IP). The default port which it will use to start the webserver is 4100
XML Input
post
http://127.0.0.1:
4100/api/v1/generate_einvoice/
JSON Input
Name
Description
URL
http://127.0.0.1:4100/api/v1/generate_einvoice/​
Method Type
POST
Body
{ "invoice_id": "100", "issue_date": "2023-06-05", "issue_time": "23:40:23", "invoice_type": { "type": "invoice", "txn_type": "simplified", "txn_sub_type": "self_billed" }, "doc_currency_code": "SAR", "tax_currency_code": "SAR", "supplier_party": { "party_identification": { "scheme_id": "MLS", "id": "123457890" }, "postal_address": { "street_name": "King Abdulaziz Road", "building_num": 8228, "plot_identification_num": 2121, "city_subdivision": "Al Amal", "city": "string", "postal_zone": 12643, "country_sub_entity": "Riyadh Region", "country_code": "SA" }, "vat_info": { "vat_number": 312343768911433, "registration_name": "Al Salam Supplies Co. LTD" } }, "customer_party": { }, "actual_delivery_date": { "year": 2023, "month": 1, "day": 1 }, "latest_delivery_date": { "year": 2023, "month": 1, "day": 2 }, "payment_means": { "code": 10, "instruction_note": "Paid in full" }, "allowance_charge": [{ "charge_indicator": false, "allowance_charge_reason": "Sample Allowance", "allowance_charge_amt": { "amt": 0.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 12 } }], "legal_monetary_total": { "line_extension_amt": { "amt": 900.00, "currency": "SAR" }, "allowance_total_amt": { "amt": 0.00, "currency": "SAR" }, "tax_exclusive_amt": { "amt": 900.00, "currency": "SAR" }, "tax_inclusive_amt": { "amt": 1035.00, "currency": "SAR" }, "payable_amt": { "amt": 1035.00, "currency": "SAR" }, "prepaid_amt": { "amt": 0.00, "currency": "SAR" } }, "tax_total": { "tax_amt": { "amt": 135.00, "currency": "SAR" }, "sub_total": { "taxable_amt": { "amt": 900.00, "currency": "SAR" }, "tax_amt": { "amt": 135.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 15 } } }, "invoice_lines": [ { "qty": 1, "unit_code": "PCE", "line_extension_amt": { "amt": 200.00, "currency": "SAR" }, "tax_amt": { "amt": 30.00, "currency": "SAR" }, "total_amt": { "amt": 230.00, "currency": "SAR" }, "price_amt": { "amt": 200.00, "currency": "SAR" }, "item": { "name": "Item A", "tax_category": { "id": "S", "percent": 15 } } }, { "qty": 2, "unit_code": "PCE", "line_extension_amt": { "amt": 700.00, "currency": "SAR" }, "tax_amt": { "amt": 105.00, "currency": "SAR" }, "total_amt": { "amt": 805.00, "currency": "SAR" }, "price_amt": { "amt": 350.00, "currency": "SAR" }, "item": { "name": "Item B", "tax_category": { "id": "S", "percent": 15 } } } ] }
Response (Simplified Documents)
{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "REPORTED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }
Response (Standard Documents)
{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "CLEARED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }
Technical Guidelines (Offline APIs)
We can consider the ID in the XML and JSON input as primary key (cbc:ID in XML and invoice_id in JSON). eg if an invoice is passed with id "1" then we sign and submit the invoice.  If the reporting status is successful then we update our database and archive the invoice. If another invoice is passed with id "1" again. Then we return the reponse of the earlier API and do not report the invoice again to ZATCA.
Taking the above scenario further, if invoice id "1" is rejected by ZATCA. Then the API caller can fix the errors and pass the invoice with the same id again. In this scenario we resubmit the invoice to ZATCA with a new counter and QR code. This process can repeated until the invoice is succesfully reported to ZATCA.
Both XSL and XSD validation are done for the invoice prior to sending the request to ZATCA
Standard Documents if onboarded, will be processed in real time (as mandated by ZATCA)
Simplified Documents will be signed and returned back to the caller. Within 24hr window a sync job will be triggered to report the invoice to ZATCA
Invoices which are rejected from ZATCA will be visible in the utility dashboard and will be available to user to modify and update
We keep the records of invoices which have been reported successfully for 7 days. Post that any invoices with an id which was used earlier will be treated as a new invoice again. Our cloud service will return the saved response for the ID. This is done to save space within the device the utility is installed in
Need Help in Getting Started 
Contact Us | Masters India
Masters India

Text	Description
URL	https://qa-globalback.mastersindia-einv.com/api/v2/ksa_einvoice/generate_einvoice/
Method Type	POST
Headers	"Productid": "einvoicing_global" (keep as is) "Service": "online_service" (keep as is) "Authorization": "JWT <token>" (Used from token-auth API)
Body	{ "invoice_id": "100", "issue_date": "2023-06-05", "issue_time": "23:40:23", "invoice_type": { "type": "invoice", "txn_type": "simplified", "txn_sub_type": "self_billed" }, "doc_currency_code": "SAR", "tax_currency_code": "SAR", "supplier_party": { "party_identification": { "scheme_id": "MLS", "id": "123457890" }, "postal_address": { "street_name": "King Abdulaziz Road", "building_num": 8228, "plot_identification_num": 2121, "city_subdivision": "Al Amal", "city": "string", "postal_zone": 12643, "country_sub_entity": "Riyadh Region", "country_code": "SA" }, "vat_info": { "vat_number": 312343768911433, "registration_name": "Al Salam Supplies Co. LTD" } }, "customer_party": { }, "actual_delivery_date": { "year": 2023, "month": 1, "day": 1 }, "latest_delivery_date": { "year": 2023, "month": 1, "day": 2 }, "payment_means": { "code": 10, "instruction_note": "Paid in full" }, "allowance_charge": [{ "charge_indicator": false, "allowance_charge_reason": "Sample Allowance", "allowance_charge_amt": { "amt": 0.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 12 } }], "legal_monetary_total": { "line_extension_amt": { "amt": 900.00, "currency": "SAR" }, "allowance_total_amt": { "amt": 0.00, "currency": "SAR" }, "tax_exclusive_amt": { "amt": 900.00, "currency": "SAR" }, "tax_inclusive_amt": { "amt": 1035.00, "currency": "SAR" }, "payable_amt": { "amt": 1035.00, "currency": "SAR" }, "prepaid_amt": { "amt": 0.00, "currency": "SAR" } }, "tax_total": { "tax_amt": { "amt": 135.00, "currency": "SAR" }, "sub_total": { "taxable_amt": { "amt": 900.00, "currency": "SAR" }, "tax_amt": { "amt": 135.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 15 } } }, "invoice_lines": [ { "qty": 1, "unit_code": "PCE", "line_extension_amt": { "amt": 200.00, "currency": "SAR" }, "tax_amt": { "amt": 30.00, "currency": "SAR" }, "total_amt": { "amt": 230.00, "currency": "SAR" }, "price_amt": { "amt": 200.00, "currency": "SAR" }, "item": { "name": "Item A", "tax_category": { "id": "S", "percent": 15 } } }, { "qty": 2, "unit_code": "PCE", "line_extension_amt": { "amt": 700.00, "currency": "SAR" }, "tax_amt": { "amt": 105.00, "currency": "SAR" }, "total_amt": { "amt": 805.00, "currency": "SAR" }, "price_amt": { "amt": 350.00, "currency": "SAR" }, "item": { "name": "Item B", "tax_category": { "id": "S", "percent": 15 } } } ] }
Response (Simplified Documents)	{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "REPORTED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }
Response (Standard Documents)	{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "CLEARED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }

Name	Description
URL	http://127.0.0.1:4100/api/v1/generate_einvoice/
Method Type	POST
Body	{ "invoice_id": "100", "issue_date": "2023-06-05", "issue_time": "23:40:23", "invoice_type": { "type": "invoice", "txn_type": "simplified", "txn_sub_type": "self_billed" }, "doc_currency_code": "SAR", "tax_currency_code": "SAR", "supplier_party": { "party_identification": { "scheme_id": "MLS", "id": "123457890" }, "postal_address": { "street_name": "King Abdulaziz Road", "building_num": 8228, "plot_identification_num": 2121, "city_subdivision": "Al Amal", "city": "string", "postal_zone": 12643, "country_sub_entity": "Riyadh Region", "country_code": "SA" }, "vat_info": { "vat_number": 312343768911433, "registration_name": "Al Salam Supplies Co. LTD" } }, "customer_party": { }, "actual_delivery_date": { "year": 2023, "month": 1, "day": 1 }, "latest_delivery_date": { "year": 2023, "month": 1, "day": 2 }, "payment_means": { "code": 10, "instruction_note": "Paid in full" }, "allowance_charge": [{ "charge_indicator": false, "allowance_charge_reason": "Sample Allowance", "allowance_charge_amt": { "amt": 0.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 12 } }], "legal_monetary_total": { "line_extension_amt": { "amt": 900.00, "currency": "SAR" }, "allowance_total_amt": { "amt": 0.00, "currency": "SAR" }, "tax_exclusive_amt": { "amt": 900.00, "currency": "SAR" }, "tax_inclusive_amt": { "amt": 1035.00, "currency": "SAR" }, "payable_amt": { "amt": 1035.00, "currency": "SAR" }, "prepaid_amt": { "amt": 0.00, "currency": "SAR" } }, "tax_total": { "tax_amt": { "amt": 135.00, "currency": "SAR" }, "sub_total": { "taxable_amt": { "amt": 900.00, "currency": "SAR" }, "tax_amt": { "amt": 135.00, "currency": "SAR" }, "tax_category": { "id": "S", "percent": 15 } } }, "invoice_lines": [ { "qty": 1, "unit_code": "PCE", "line_extension_amt": { "amt": 200.00, "currency": "SAR" }, "tax_amt": { "amt": 30.00, "currency": "SAR" }, "total_amt": { "amt": 230.00, "currency": "SAR" }, "price_amt": { "amt": 200.00, "currency": "SAR" }, "item": { "name": "Item A", "tax_category": { "id": "S", "percent": 15 } } }, { "qty": 2, "unit_code": "PCE", "line_extension_amt": { "amt": 700.00, "currency": "SAR" }, "tax_amt": { "amt": 105.00, "currency": "SAR" }, "total_amt": { "amt": 805.00, "currency": "SAR" }, "price_amt": { "amt": 350.00, "currency": "SAR" }, "item": { "name": "Item B", "tax_category": { "id": "S", "percent": 15 } } } ] }
Response (Simplified Documents)	{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "REPORTED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }
Response (Standard Documents)	{ "info_messages": [ { "code": "XSD_ZATCA_VALID", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications" } ], "warning_messages": [], "error_messages": [], "status": "CLEARED", "invoice": "Final invoice in B64 Format", "message": "Operation Successful" }

Authentication

Get Invoice Process Status

Last modified 1mo ago