PHPackages                             ahmedabdelnaby/zatca-tools - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. ahmedabdelnaby/zatca-tools

ActiveLibrary[Utility & Helpers](/categories/utility)

ahmedabdelnaby/zatca-tools
==========================

A helper to generate the QR code and signed it for ZATCA e-invoicing

01.9kPHP

Since Feb 17Pushed 1y agoCompare

[ Source](https://github.com/ahmed-abdelnaby-fahmy/ZATCA)[ Packagist](https://packagist.org/packages/ahmedabdelnaby/zatca-tools)[ RSS](/packages/ahmedabdelnaby-zatca-tools/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

🧾 ZATCA (Fatoora) QR-Code & Invoice Signing
===============================================

[](#-zatca-fatoora-qr-code--invoice-signing)

 A PHP library to generate QR codes and sign invoices for ZATCA e-invoicing compliance in Saudi Arabia.
 [🐛 Report Bug](https://github.com/ahmed-abdelnaby-fahmy/zatca-tools/issues/new) · [✨ Request Feature](https://github.com/ahmed-abdelnaby-fahmy/zatca-tools/discussions/new)

---

✅ Requirements
--------------

[](#-requirements)

- 🐘 **PHP** >= 8.0
- 🔡 `mbstring` extension
- 📜 `ext-dom` extension

---

📦 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require ahmedabdelnaby/zatca-tools
```

---

🚀 Usage
-------

[](#-usage)

This package supports both **Phase 1** and **Phase 2** of ZATCA compliance.

- **Phase 1:** 🔲 QR code generation.
- **Phase 2:** ✍️ Invoice signing & 🏢 System integration with ZATCA.

---

### 1️⃣ **Generating CSR (Certificate Signing Request)**

[](#1️⃣-generating-csr-certificate-signing-request)

Before signing invoices, you need to generate a CSR and register your merchant in **ZATCA APIs**.

```
use ZATCA\Tools\GenerateCSR;
use ZATCA\Tools\Models\CSRRequest;

$data = CSRRequest::make()
    ->setUID('string $OrganizationIdentifier')
    ->setSerialNumber('string $solutionName', 'string $version', 'string $serialNumber')
    ->setCommonName('string $commonName')
    ->setCountryName('SA')
    ->setOrganizationName('string $organizationName')
    ->setOrganizationalUnitName('string $organizationalUnitName')
    ->setRegisteredAddress('string $registeredAddress')
    ->setInvoiceType(true, true) // invoice types, default is true, true
    ->setCurrentZatcaEnv('sandbox') // Supports ['sandbox', 'simulation', 'core']
    ->setBusinessCategory('string $businessCategory');

$CSR = GenerateCSR::fromRequest($data)->initialize()->generate();

// Save 🔑 private key
openssl_pkey_export_to_file($CSR->getPrivateKey(), 'private-key.pem');

// Save 📝 CSR content
file_put_contents('csr.pem', $CSR->getCsrContent());
```

🔹 **Now, submit the CSR to ZATCA APIs to receive your certificate.**

---

### 2️⃣ **Signing Invoices & Generating QR Code**

[](#2️⃣-signing-invoices--generating-qr-code)

After receiving a certificate from ZATCA, you can **sign invoices** and **generate QR codes**.

```
use ZATCA\Tools\Helpers\Certificate;
use ZATCA\Tools\Models\InvoiceSign;

$xmlInvoice = 'xml invoice text';

$certificate = (new Certificate(
    'certificate plain text (base64 decoded)', // 📜 Get from ZATCA
    'private key plain text' // 🔑 Generated in CSR step
))->setSecretKey('🔒 secret key text'); // 🔑 Get from ZATCA

$invoice = (new InvoiceSign($xmlInvoice, $certificate))->sign();

// Get invoice details 📄
$invoice->getHash();      // 🏷️ Invoice Hash
$invoice->getInvoice();   // 📝 Signed XML Invoice
$invoice->getQRCode();    // 🔲 QR Code in Base64 format
```

---

### 3️⃣ **Generating QR Code from Invoice Data**

[](#3️⃣-generating-qr-code-from-invoice-data)

```
use ZATCA\Tools\GenerateQrCode;
use ZATCA\Tools\Helpers\UXML;
use ZATCA\Tools\Helpers\Certificate;

$xmlInvoice = 'xml invoice text';

$certificate = (new Certificate(
    'certificate plain text (base64 decoded)',
    'private key plain text'
))->setSecretKey('secret key text');

$tags = UXML::fromString($xmlInvoice)->toTagsArray($certificate);

$QRCodeAsBase64 = GenerateQrCode::fromArray($tags)->toBase64();
```

---

### 4️⃣ **Generating Basic QR Code (Phase 1)**

[](#4️⃣-generating-basic-qr-code-phase-1)

```
use ZATCA\Tools\GenerateQrCode;
use ZATCA\Tools\Tags\InvoiceDate;
use ZATCA\Tools\Tags\InvoiceTaxAmount;
use ZATCA\Tools\Tags\InvoiceTotalAmount;
use ZATCA\Tools\Tags\Seller;
use ZATCA\Tools\Tags\TaxNumber;

$generatedString = GenerateQrCode::fromArray([
    new Seller('Company Name'),
    new TaxNumber('1234567891'),
    new InvoiceDate('2024-02-17T14:25:09Z'),
    new InvoiceTotalAmount('500.00'),
    new InvoiceTaxAmount('75.00')
])->toBase64();
```

---

### 5️⃣ **Display QR Code in HTML**

[](#5️⃣-display-qr-code-in-html)

```
$displayQRCodeAsBase64 = GenerateQrCode::fromArray([
    new Seller('Company Name'),
    new TaxNumber('1234567891'),
    new InvoiceDate('2024-02-17T14:25:09Z'),
    new InvoiceTotalAmount('500.00'),
    new InvoiceTaxAmount('75.00')
])->render();
```

Now, use it in an `` tag:

```