ZATCA e-Invoice Extension

Installation & Setup Guide

This guide covers the complete setup process for the ZATCA e-Invoice Extension for Manager.io. Follow each section in order for a successful deployment.

Important: Create a full backup of your Manager database before proceeding. Test thoroughly in the Simulation Environment before switching to Production.

Prerequisites

Manager.io — Desktop or Server edition with API access enabled
ZATCA Account — Access to ZATCA Fatoora Portal for OTP generation
Business Details — Company name, VAT number, CR number, and Saudi address
Network Access — Server must be able to reach ZATCA endpoints

Install Extension in Manager

Option A — Extension Directory (Recommended)

Open Manager and click Extensions in the top menu
Find ZATCA e-Invoice Extension in the extension list and click it
The extension landing page opens — click Install next to your business
All four placements (Sales Invoice, Credit Note, QR Batch, Business Details) are installed automatically

Option B — Manual Installation

Use this only if the extension is not listed in the Extension Directory.

Open Manager → Settings → Extensions
Click Add New Extension, set Sources to Url
Enter the extension URL:

Create four separate extensions using the same URL with these placements:

Placement	Purpose	Required
`sales-invoice-view`	Submit invoices to ZATCA	Yes
`credit-note-view`	Submit credit notes to ZATCA	Yes
`sales-invoices`	QR code batch update	Optional
`business-details-form`	Edit business address	Optional

All placements use the same URL. The extension automatically detects which page it's on and shows the appropriate interface.

Setup Custom Fields

The extension automatically creates required custom fields when you run the Setup Wizard (Step 1 of the onboarding process). These fields store certificate data, invoice counters, and QR codes.

The custom fields are created automatically. You do not need to create them manually.

ZATCA Onboarding (CCSID/PCSID)

The Setup Wizard guides you through the complete ZATCA onboarding process:

1 Custom Fields

Creates all required custom fields in Manager automatically.

2 Business Info

Review and confirm business details for the CSR certificate.

3 Generate CSR

Generate Certificate Signing Request and private key.

4 Get CCSID & PCSID

Obtain compliance and production certificates from ZATCA using your OTP.

OTP: Generate a 6-digit OTP from the ZATCA Fatoora Portal before starting Step 4.

Customer Setup

For Standard (B2B) invoices, customers must have the following custom fields filled in Manager:

Field	Description	Required
Registration Name	Customer's legal business name	Yes
Company ID (VAT)	Customer's VAT registration number	Yes (B2B)
Street Name	Street address	Yes
Building Number	Building number	Yes
City	City name	Yes
District	City subdivision / district	Yes
Postal Code	ZIP / postal code	Yes
Country Code	ISO country code (e.g. SA)	Yes

For Simplified (B2C) invoices, customer details are optional but recommended.

Invoice Submission Flow

1. Create Invoice

Create a Sales Invoice or Credit Note in Manager as usual.

2. Review & Submit

Open the invoice → the extension validates and signs it automatically.

3. ZATCA Response

Invoice is cleared/reported. QR code is saved to the invoice.

Invoice SubType	Mode	Description
`0100000`	Clearance	Standard B2B — invoice must be cleared by ZATCA before issuing
`0200000`	Reporting	Simplified B2C — invoice is reported to ZATCA after issuing

QR Code Batch Update

The QR Code Batch Update tool allows you to update QR codes on existing invoices in bulk. It handles both:

Phase II invoices — uses the ZATCA-generated QR code stored in the invoice
Phase I invoices — generates a TLV-based QR code from invoice data

This tool is only available when the extension is running inside Manager.io, as it requires direct communication with Manager to read and update invoice data. Access it via Settings → Extensions in Manager.

PDF Invoice Download

For invoices that have been Cleared or Reported by ZATCA, you can generate a formatted PDF invoice directly from the status page.

Preview PDF

Opens the generated PDF in a new browser tab for review before saving.

Download PDF

Downloads the PDF with the ZATCA-standard filename format: {VAT}_{Date}T{Time}_{InvoiceNo}.pdf

What's included in the PDF

Layout — matches the standard Manager.io print template: header, bill-to, line items table, totals, and QR code
Language — LTR (English) when contextData.direction = "ltr"; RTL (Arabic) when direction = "rtl" — selected automatically from Manager's language setting
QR Code — rendered from the stored TLV data; scannable for ZATCA portal verification
Amount in Words — spelled out in English (LTR) or Arabic (RTL)
Embedded XML — the signed ZATCA UBL XML is embedded as an attachment inside the PDF (PDF/A-3A, ISO 19005-3)

XML attachment

The PDF file contains the signed UBL XML as an embedded file attachment (PDF/A-3A compliant). Open the PDF in Adobe Acrobat and go to View → Navigation Panels → Attachments to access the .xml file. The XML used is:

CLEARED — the cleared invoice XML returned by ZATCA
REPORTED — the signed request payload sent to ZATCA

The PDF buttons appear only for invoices with status CLEARED or REPORTED. Phase I invoices and unsubmitted invoices do not have PDF generation available.

Troubleshooting

Make sure you're viewing a Sales Invoice or Credit Note. The extension only works on these two document types. Also verify the extension placement is set to sales-invoice-view or credit-note-view.

Check the error dialog for the specific step and source. Common causes:

Network: Server cannot reach ZATCA — check firewall/proxy settings
OTP expired: Generate a new 6-digit OTP from the Fatoora portal
Invalid CSR: Re-generate the CSR and try again

Ensure the invoice has: a customer selected, an invoice number, at least one line item with a tax code, and a valid issue date. For B2B invoices, the customer must also have address and VAT details filled in.

For Simplified invoices, the QR code is generated locally and must include the digital signature. Ensure the certificate (PCSID) is valid and not expired. Re-onboard if the certificate has expired.