When you connect your accounting system to the Fatoora platform, the Zakat, Tax and Customs Authority (ZATCA) treats every device that issues invoices as an independent «invoice generation unit». This unit is what the technical specification calls the E-invoice Generation Solution, abbreviated as EGS. Understanding this unit is the cornerstone of any correct integration with Phase Two of e-invoicing, because everything that follows it (the certificate, the counter, the hash chain, the configuration) is built on top of it.
In this technical document we explain precisely what an EGS unit is, why every device, point of sale, or branch is a self-contained unit, and how each unit obtains its own identity from the Authority, then how units are registered and configured in an environment with multiple devices. The goal is for the developer or system administrator to come away with a clear picture before writing the first line of integration.
What is the EGS invoice generation unit?
The invoice generation unit (EGS Unit) is any software component or device capable of creating an electronic invoice compliant with the Authority’s specification, signing it, and sending it to the Fatoora platform. The term does not describe a single large program, but rather each individual «issuance point» within your establishment.
To put it more clearly: if you have a single central accounting system that issues all invoices, then that system is one EGS unit. But if you have five points of sale across five branches, you are dealing with five separate EGS units, even if they all operate under the same tax number and the same trade name.
The reason for this split is purely technical. Each unit signs its invoices with its own cryptographic certificate, maintains an independent sequential counter, and builds a separate hash chain that links every invoice to the one before it. If we grouped multiple devices under a single unit, these chains would break and the Authority would be unable to verify the integrity of the sequence.
The Authority defines the unit through a fixed set of data recorded at configuration time, most notably the trade name, the tax number, the industrial/serial unit identifier, and the branch address. This data is later embedded within the certificate request, so the unit becomes uniquely identified on the platform.
Its own cryptographic stamp certificate (CSID)
An independent invoice counter (ICV)
Its own hash chain (PIH)
Independent onboarding on the Fatoora platform
The difference between the solution and the unit
Many people confuse the «invoicing solution» with the «invoicing unit». The solution is the software product as a whole, such as the Qoyod accounting software. The unit, however, is each running instance of that solution on a specific device or branch. A single solution may generate dozens of units depending on the number of devices connected to it.
This distinction is important in technical documentation because the Authority issues approval for the solution as a product, but it issues an independent certificate and identity for each unit separately. In other words, approving the solution is a necessary but not sufficient condition. You still have to configure each unit so it takes its own identity.
Why is each device, point of sale, or branch treated as an independent EGS unit?
The governing rule in Phase Two: every technically independent issuance point is treated as a separate unit. An independent point is one that creates the invoice and signs it locally before sending it. Three elements make this independence necessary.
First: the certificate specific to each unit (CSID)
Each EGS unit obtains its own cryptographic certificate called the CSID certificate (Cryptographic Stamp Identifier). This certificate is what the unit uses to sign its invoices. Two units cannot share the same certificate, because the Authority uses the certificate to identify the device that actually issued the invoice.
If you tried to sign the invoices of two devices with a single certificate, the invoices would appear as if they were issued by a single device, and this breaks the tracking logic on the platform. That is why registering any unit always begins with requesting its independent certificate.
Second: the independent sequential counter (ICV)
Each unit maintains its own ascending invoice counter called the invoice counter (ICV). This counter starts from one at the first invoice, and increases by one with each subsequent invoice without interruption and without repetition. The counter is not shared between units; rather, each unit has its own counter that starts from zero when it is configured.
This independence is necessary because the Authority expects a continuous sequence for each unit separately. If two units shared the same counter, gaps or duplicate numbers would appear, and both are errors that validation rejects.
Third: the independent hash chain (PIH)
Each unit links its invoices into a chain via the previous invoice hash (PIH). Each invoice carries a hash of the invoice that preceded it within the same unit. The first invoice in the unit uses an agreed-upon initial value, then each invoice builds its hash on top of the previous one.
This chain resembles a blockchain: any later modification to an old invoice breaks the hash of everything after it, so validation detects it immediately. And because the chain is built within a single unit, it is not valid to mix the invoices of two devices into a single chain, otherwise the linkage collapses.
The summary of these three elements: the certificate determines «who issued», the counter determines «the order», and the hash chain determines «the correct succession». The three together only work within the boundaries of a single unit, which is why each device must be a self-contained unit.
Invoice 1 (ICV=1)
Invoice 2 (ICV=2 + PIH of hash 1)
Invoice 3 (ICV=3 + PIH of hash 2)
How does each unit obtain its own identity?
The unit takes its identity in two consecutive stages during configuration. The first stage produces an initial certificate, and the second stage produces the operational certificate. The accounting system executes both steps automatically, but it is useful for the developer to understand their sequence.
The first stage: requesting the initial certificate
The unit begins by generating a cryptographic key pair (private and public), then builds a certificate signing request (CSR) containing the unit’s data. This request is sent along with an activation code (OTP) that the taxpayer obtains from the Fatoora portal. The platform responds with the initial compliance certificate, which is used for the testing stage only.
The field binarySecurityToken is the initial compliance certificate encoded in base64, and the field secret is the shared secret that the unit later uses for authentication. The two values are stored securely within the system because they are the key to every subsequent request.
The second stage: issuing the operational certificate
After the compliance checks pass, the unit requests its operational certificate using the same initial credentials. This certificate is the one used to sign real invoices in the production environment, and it represents the unit’s final identity on the platform.
The output here is the production certificate (Production CSID) belonging to this unit alone. From this moment, the unit becomes fully configured: it has a certificate to sign with, a counter it starts from one, and an initial hash value on top of which it builds its chain. The full details of this step are documented on the Onboarding and connecting with the Fatoora platform.
The unit’s data structure after configuration
After the two stages are complete, the unit maintains an internal state that combines its identity, its signing tools, and its counter position. A simplified representation of this state:
The value icv starts from zero and increases with each invoice, and the value pih starts with the agreed-upon initial value then changes with each new invoice. As for private_key_ref andsecret_ref they refer to a secure store, since the private key or the secret must never be stored in plain text within the database.
How are EGS units registered and configured?
The registration process links three parties: the taxpayer who owns the tax number, the Fatoora platform that issues the certificates, and the accounting system that creates the units. The practical steps are as follows.
The first step: generating the activation code from the Fatoora portal
The taxpayer logs in to the Fatoora portal through their account with the Authority, and selects the option to generate an activation code (OTP) for each unit they want to register. Several codes can be generated at once when registering many devices. Each code is valid for a limited time, so it is used immediately after generation.
The second step: entering the code in the accounting system
The code is entered in the connection screen inside the system, and the system handles the rest of the work: generating the keys, building the certificate request, sending it, and receiving the compliance certificate. All of this happens behind the scenes, and the user sees only a message that configuration succeeded.
The third step: passing the compliance checks
Before granting the production certificate, the platform asks the unit to send sample invoices representing the required cases (standard invoice, simplified invoice, credit note, debit note). The platform verifies that the unit builds the document, the signature, and the hash value correctly.
When a "status": "PASS" appears for each required type, the unit passes the check and moves on to request the production certificate. Any message of errorMessages halts the process until the document structure or the signature is corrected.
The fourth step: starting actual issuance
After obtaining the production certificate, the unit starts issuing real invoices. Standard invoices (B2B) are sent to the platform for clearance before being delivered to the buyer, and simplified invoices (B2C) are delivered to the buyer immediately and reported to the platform within 24 hours. With each invoice the counter increases and the hash value is updated, so the chain stays connected.
Set up your invoicing units without technical complexity
Qoyod handles creating the certificates, managing the counter, and the hash chain for each unit automatically, so you issue invoices compliant with the Zakat, Tax and Customs Authority from day one.
Multi-unit Setups
In large establishments it is rare to have a single unit. A restaurant may own ten points of sale, a retail company may own branches in several cities, and each of these points is an independent EGS unit that needs its own identity. Managing this multiplicity correctly is what separates a sound integration from a faltering one.
The rule: one unit per issuance point
The principle is simple but strict: every device that issues invoices is an independent EGS unit, and every unit has its own certificate, counter, and chain. A unit’s certificate is not reused on another device, and a counter is not shared between two devices. If a single device were mistakenly distributed across two branches, the chains would get mixed and validation would fail.
Common patterns for multiplicity
There are two main patterns for distributing units across the establishment:
The first pattern is distributed configuration: each device carries its certificate and signs locally. This pattern suits branches that may operate without a permanent connection, because signing does not need the internet at the moment of issuance, and then reporting happens when the connection is available.
The second pattern is centralized configuration: a single central system manages several logical units, each with its own identity within the system. This pattern suits establishments that issue their invoices from a central accounting server distributed across different departments or sales lines. Even in this pattern, each logical unit keeps its own independent certificate, counter, and chain.
| Criterion | Distributed setup | Centralized setup |
|---|---|---|
| Signing location | Inside each device | In a central system |
| Connection requirement | Per device | A single point |
| Best suited for | Scattered branches | A unified system |
Managing the unit lifecycle
Multiplicity imposes ongoing management that does not end at configuration. Three tasks recur:
First, adding a new unit when opening a branch or purchasing a device. The new unit goes through the same two configuration stages, and starts its counter from one and its chain from the initial value.
Second, renewing the certificate before it expires. Each certificate has a defined lifetime, and as it approaches, a new certificate must be requested for the same unit without resetting the counter or breaking the chain, because the tax identity of the unit remains the same.
Third, decommissioning a unit when a device is withdrawn from service. The records of the stopped unit are kept in full for reference during any audit, and its identifier is not reused for another device to avoid confusion.
Common errors in setting up multiple units
Among the most common errors that the platform rejects:
Sharing a single certificate between two devices, so the invoices appear as if they are from a single source. The solution is that each device has its own certificate.
Resetting the counter after reinstalling the system on the same device, so duplicate numbers appear. The solution is to restore the last counter position from the backup before resuming issuance.
Building a hash chain with a wrong previous value after an interruption, so the chain breaks. The solution is to read the hash value from the last invoice the unit actually issued, not from a default value.
The signing mechanism within the unit step by step
Signing is the heart of an EGS unit’s work, and understanding it clarifies why each unit needs its own independent identity. When creating any invoice, the unit passes through a fixed series of operations that ends with a signed document ready to send.
First, the unit builds the invoice document in XML format according to the UBL specification, and embeds within it the seller’s and buyer’s data, the line items, and the tax amounts. Second, it computes a hash of the document with the SHA-256 algorithm, and this hash represents the invoice uniquely, so any change of a single character changes it entirely. Third, the unit signs this hash with its private key associated with its certificate, producing a digital signature that proves this specific unit issued the invoice. Fourth, the previous invoice hash (PIH) and the counter number (ICV) are merged into the document, so the invoice joins the unit’s chain.
Finally, the QR (Quick Response) code is generated, carrying a summary of the invoice and the signature data. This code is what the buyer or auditor scans for a quick verification of the invoice’s validity. Each of these steps is performed locally within the unit, and does not need a real-time connection to the platform in the case of a simplified invoice.
Notice lines six and seven: after each invoice the counter advances and the hash value is updated. If two devices shared the same object unit, they would race for the same two values and the chain would collapse. This is the fundamental technical reason behind the independence of each unit.
The difference between the B2B path and the B2C path within the unit
A single unit may issue two types of invoices, and each type has a different path with the platform. Understanding the difference is essential because the unit’s behavior changes according to the type of invoice.
The standard invoice (B2B): clearance before delivery
The standard invoice is directed to another establishment registered for tax. Here the invoice must be sent to the platform for clearance before it is delivered to the buyer. The invoice is not delivered until the platform responds with the clearance result; if it accepts it, it adds its stamp and returns it, and if it rejects it, it halts the process with an error message. This path is real-time and requires a connection at the moment of issuance.
The simplified invoice (B2C): immediate delivery then reporting
The simplified invoice is directed to the end consumer. Here the invoice is delivered to the buyer immediately upon issuance without waiting for the platform, then the platform is notified of it within 24 hours at most. This path suits fast points of sale, because it does not disrupt the payment process, and it allows the unit to work without a real-time connection then report later when the network is available.
In both paths, the unit’s counter advances and its hash value is updated in the same way. The difference is not in building the chain, but in the timing of communication with the platform: clearance before delivery in the standard invoice, and reporting after delivery in the simplified invoice. This means a single unit may mix the two types in one chain without a problem, because the chain follows the order of issuance, not the type of invoice.
Configuration in environments without a permanent connection
Many points of sale operate in locations where the internet may drop. The design of the EGS unit accounts for this reality. Signing does not need a connection because it happens locally with the unit’s key, and the simplified invoice is delivered to the buyer immediately. What needs a connection is reporting, and it has a 24-hour window that is usually enough for the network to return.
In practice, the unit maintains a queue of invoices not yet reported. When the connection returns, these invoices are sent in the same order they were issued, preserving the counter sequence and the hash chain. Any out-of-order sending confuses validation, so the queue must be strict in preserving the sequence.
The standard invoice is different, because it needs clearance before delivery. So in locations that rely on standard invoices, a real-time connection remains a requirement. The design of the multi-unit environment takes this into account: standard issuance points are placed where the connection is guaranteed, while simplified points of sale tolerate temporary interruption.
The role of the accounting system in simplifying EGS units
The preceding technical aspect is precise and intricate, but in reality the taxpayer does not deal with it manually. A compliant accounting system hides this complexity behind simple steps. Upon connection, the system creates the keys and certificates for each unit, tracks its counter, saves the last hash value, and rebuilds the chain after any interruption.
In Qoyod software, for example, each unit is configured by entering the activation code once, then the system handles issuing the signed invoices and sending them for clearance or reporting according to their type, while automatically saving all the chain records. This means the establishment owner focuses on their work, while the Authority’s requirements remain fulfilled in the background. For more context on the requirement as a whole, see the Qoyod e-invoicing software.
Applied example: a hash chain with three branches
Let us take a retail company with three branches: Riyadh, Jeddah, and Dammam. Each branch has a single point-of-sale device. The rule means three independent EGS units, each unit with its own certificate, counter, and chain. When the company opens its accounts, three activation codes are generated from the Fatoora portal, one code per branch.
The Riyadh branch code is entered into its device, so the unit creates its keys, requests its certificate, and starts its counter from one. Then the Jeddah code is entered into the Jeddah device, so the Jeddah unit takes its own certificate and its independent counter that also starts from one. And likewise Dammam. Three units, three certificates, three counters all starting from one but never intersecting.
Now if the Riyadh branch issued a hundred invoices, its counter would be at a hundred, while the Jeddah counter might be at thirty, and the Dammam counter at fifty. Three different numbers because they belong to three units. If the system administrator, with good intentions, tried to unify the counter across the branches, they would break the sequence and expose the invoices to rejection. Multiplicity here is not a luxury, but a necessity imposed by the platform’s design.
Now suppose the Dammam device failed and the system was reinstalled. The common error is for the device to start its counter from one again, so the numbers from one to fifty are repeated. The correct approach is to restore the last counter position (fifty) and the last hash value from the backup, then resume issuance from fifty-one. This way the Dammam unit’s chain stays connected without a gap or repetition.
Governance and compliance considerations for units
Managing units is not limited to the technical aspect; it extends to governance. Each unit represents an official issuance point in the establishment’s name before the Authority, so it needs clear controls.
The first control is protecting the private keys. Each unit’s private key is what proves its identity, and leaking it means another party could sign invoices in the establishment’s name. So the keys are kept in an isolated secure store, and are not written in plain text in databases or configuration files.
The second control is a complete record for each unit: when it was configured, who configured it, which branch it serves, and when its certificate is to be renewed. This record facilitates auditing and prevents the existence of «orphan» units whose source no one knows. In any review by the Authority, the path of each invoice is known back to the unit that issued it.
The third control is a recovery plan. Because breaking the chain after a failure is the most costly error, the backups must include the counter position and the last hash value for each unit, not the invoice data alone. A backup that saves the invoices without the counter state is not enough to resume issuance safely.
These controls together transform multiplicity from a source of risk into a disciplined process. And a good accounting system applies them by default, so the taxpayer is not burdened with tracking them manually.
Frequently asked questions
Is each point of sale considered an independent EGS unit?
Yes. Each device that creates the invoice and signs it locally is treated as an independent unit, with its own certificate, counter, and hash chain, even if all the devices are under the same tax number.
Can two units share the same CSID certificate?
No. The certificate identifies the device that issued the invoice, and sharing it between two units breaks the platform’s tracking logic and is rejected in validation.
Where does the ICV counter value start in a new unit?
It starts from one at the first invoice, and increases by one with each subsequent invoice without interruption and without repetition within the unit itself.
What happens to the hash chain when reinstalling the system?
The last hash value and the last counter position must be restored from the backup before resuming issuance, otherwise the chain breaks and duplicate numbers appear.
Does Qoyod handle configuring the units automatically?
Yes. The user enters the activation code once per unit, and the system handles creating the certificates, managing the counter and the hash chain, and sending the invoices for clearance or reporting.
Does registering several branches require several activation codes?
Yes. The taxpayer generates an activation code for each unit they want to register from the Fatoora portal, and several codes can be generated at once when registering many devices.
