This guide provides detailed instructions for integrating Manager IO with Zatca's e-invoicing system using the provided SDK.
-
Download SDK:
- Visit Zatca SDK Download and download version 238-R3.3.3.
- Select "Version History", choose the latest version, and click the "Download SDK" button.
- Extract the downloaded file to
C:\
.
-
Configuration:
- Copy
C:\zatca-einvoicing-sdk-238-R3.3.3\Data\Input\csr-config-example-EN.properties
toC:\zatca-einvoicing-sdk-238-R3.3.3\Lib\.Net\csr-config-example-EN.properties
. - Edit the copied file using Notepad and save.
- Rename the edited file to
csr.config
.
- Copy
-
Generate CSR:
-
Open Command Prompt and run the following commands:
C: cd \ cd C:\zatca-einvoicing-sdk-238-R3.3.3\Lib\.Net\Test fatooranet.exe csr -csrConfig ..\csr.config -generatedCsr ..\cert.pem -privateKey ..\ec-secp256k1-priv-key.pem -nonprod true
-
Use
-nonprod true
for sandbox testing. Use-sim true
for Simulation Server (not tested), and skip this option for production (not tested). -
This command will generate two files:
C:\zatca-einvoicing-sdk-238-R3.3.3\Lib\.Net\cert.pem
C:\zatca-einvoicing-sdk-238-R3.3.3\Lib\.Net\ec-secp256k1-priv-key.pem
-
-
Generate CCSID:
- In your browser, go to Zatca Integration Sandbox.
- Select "Compliance CSID", click "POST", and then "Try it Out".
- Use the default valid token "123456" for sandbox testing.
- Copy the content of
cert.pem
and paste it into the{ "csr": "csr file content" }
field. - Click "Execute" to receive a response containing the
binarySecurityToken
andsecret
.
-
Generate PCSID:
- Select "Production CSID (Onboarding) API".
- Click "Authorize" and use the
binarySecurityToken
andsecret
from the CCSID generation step for authentication. - Click "POST" and "Try it Out", using the CCSID
requestID
in the request body{"compliance_request_id": "1234567890123"}
. - Click "Execute" to receive a response with the PCSID details.
Use the following endpoints for sandbox testing:
- Reporting:
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/invoices/reporting/single
- Clearance:
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/invoices/clearance/single
- Compliance Check:
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/compliance/invoices
-
Generate New Business or Open Existing Business Data.
-
Create Custom Fields:
-
Navigate to
Settings
->Custom Fields
->Text Custom Fields
. -
Create the following custom fields:
-
PartyTaxInfo: Type : Paragraph text Placement : Customer, Supplier
-
Item TaxCategory Info: Type : Dropdown list Placement : Inventory Item, Non Inventory Item, Inventory Kit Options:
S E | VATEX-SA-29 E | VATEX-SA-29-7 E | VATEX-SA-30 Z | VATEX-SA-32 Z | VATEX-SA-33 Z | VATEX-SA-34-1 Z | VATEX-SA-34-2 Z | VATEX-SA-34-3 Z | VATEX-SA-34-4 Z | VATEX-SA-34-5 Z | VATEX-SA-35 Z | VATEX-SA-36 Z | VATEX-SA-EDU Z | VATEX-SA-HEA Z | VATEX-SA-MLTRY O | VATEX-SA-OOS
-
-
Create four custom fields for transactions:
- Invoice Sub Type
- Payment Means
- Instruction Note (Skip Sales Invoice)
- QR Code (Type: Paragraph text)
-
-
Edit
each custom field to get itsGUID
.
Add the following script to the footer to generate and insert a QR code into the printed document:
<script>
document.addEventListener('DOMContentLoaded', () => {
var qrCodeContent = '%%QR Code%%';
if (qrCodeContent != '-') {
var mainTable = document.querySelector('#printable-content > table');
if (mainTable) {
var newRow = mainTable.insertRow();
var newCell = newRow.insertCell();
newCell.colSpan = 99;
newCell.innerHTML += '<div id="signedQrCode" style="padding: 20px"></div>';
}
new QRCode(document.getElementById("signedQrCode"), {
text: qrCodeContent,
width: 160,
height: 160,
colorDark: "#000000",
colorLight: "#fafafa",
correctLevel: QRCode.CorrectLevel.L
});
var qrcodeDiv = document.getElementById('qrcode');
if (qrcodeDiv) {
qrcodeDiv.remove();
}
}
});
</script>
Add the following information for each Customer and Supplier:
"StreetName": "صلاح الدين | Salah Al-DinX",
"BuildingNumber": "1111",
"CitySubdivisionName": "المروج | Al-Murooj",
"CityName": "الرياض | Riyadh",
"PostalZone": "12222",
"CountryIdentificationCode": "SA",
"TaxSchemeCompanyID": "399999999800003",
"TaxSchemeID": "VAT",
"RegistrationName": "شركة نماذج فاتورة المحدودة | Fatoora Samples LTD"
- Checklist and Add Footer for QR Code.
- Checklist and Add Relay URL: http://localhost:4455/process-form.
- Add Other Settings as Needed.
- Download Latest Release from GitHub.
- Extract to Desired Folder.
- Run ZatcaService.exe and Open http://localhost:4455 in Browser.
- Populate Gateway Setting with Data from Previous Steps and Save Settings.
ZatcaWebServices ready to serve Manager for Invoicing
If you encounter any shortcomings or issues with the web API that need to be added or fixed, you can ask questions or provide feedback through the discussion section of this project. Your feedback and suggestions are highly appreciated to help improve the quality and functionality of this project.