PHPackages                             hyderkamran/laravel-zatca - 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. [API Development](/categories/api)
4. /
5. hyderkamran/laravel-zatca

ActiveLibrary[API Development](/categories/api)

hyderkamran/laravel-zatca
=========================

Laravel package for ZATCA (Saudi Arabia) e-invoicing integration

201PHP

Since Jun 3Pushed 1mo agoCompare

[ Source](https://github.com/haider-kamran/laravel-zatca)[ Packagist](https://packagist.org/packages/hyderkamran/laravel-zatca)[ RSS](/packages/hyderkamran-laravel-zatca/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel ZATCA E-Invoicing
=========================

[](#laravel-zatca-e-invoicing)

A production-grade, open-source Laravel package for complete compliance with Saudi Arabia's ZATCA E-Invoicing requirements (Phase 1 & Phase 2).

Features
--------

[](#features)

- **E-Invoicing**: Full support for B2B (Standard) and B2C (Simplified) invoices.
- **XML Generation**: Robust UBL 2.1 XML building, correctly typed and schema-compliant.
- **QR Generation**: Mandatory TLV (Tag-Length-Value) Base64 encoding for QR codes (all 9 tags supported).
- **Phase 1 Compliance**: Generate XML and QR codes locally.
- **Phase 2 Compliance**: Full API integration for Clearance (Standard) and Reporting (Simplified) workflows.
- **Sandbox Support**: Switch seamlessly between ZATCA Developer Portal (Sandbox) and Core API (Production).
- **Cryptography Engine**: Built-in support for ECDSA secp256k1 private keys, C14N XML canonicalization, and SHA-256 hashing.
- **CSID Lifecycle**: Artisan commands for CSR generation, compliance checks, and CSID onboarding.
- **Eloquent Integration**: A simple `HasZatca` trait to drop into your existing `Invoice` models.

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10.x / 11.x
- `ext-openssl`
- `ext-simplexml`

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require hyderkamran/laravel-zatca
```

Publish the configuration file and migrations:

```
php artisan vendor:publish --tag="zatca-config"
php artisan vendor:publish --tag="zatca-migrations"
```

Run the migrations to create the `zatca_certificates` and `zatca_submissions` tables:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

Set your organization and seller details in `config/zatca.php` or your `.env` file:

```
ZATCA_ENVIRONMENT=sandbox
ZATCA_SELLER_NAME="Acme Corp"
ZATCA_SELLER_VAT_NUMBER="300000000000003"
ZATCA_SELLER_CR_NUMBER="1234567890"

ZATCA_ORG_NAME="Acme Corp"
ZATCA_ORG_UNIT="IT Department"
ZATCA_COMMON_NAME="acme-zatca-system"
ZATCA_EGIC="300000000000003"
```

Usage
-----

[](#usage)

### 1. Generate CSR & Private Key

[](#1-generate-csr--private-key)

Run the interactive command to generate a ZATCA-compliant CSR and secp256k1 private key.

```
php artisan zatca:generate-csr --env=sandbox --save-db
```

Submit this CSR to the ZATCA portal to retrieve an OTP.

*(Note: Currently `activate-csid` command will be implemented to automatically store the CSID and secret from the OTP. For now, you can manually issue the API call via `Zatca::client()->issueComplianceCsid()` and store it in your DB).*

### 2. Eloquent Trait Integration

[](#2-eloquent-trait-integration)

Add the `HasZatca` trait to your existing Invoice model:

```
use Hyderkamran\LaravelZatca\Traits\HasZatca;
use Hyderkamran\LaravelZatca\Enums\InvoiceType;

class Invoice extends Model
{
    use HasZatca;

    public function getZatcaInvoiceType(): InvoiceType
    {
        return $this->is_b2b ? InvoiceType::STANDARD : InvoiceType::SIMPLIFIED;
    }

    public function toZatcaSeller(): array
    {
        return [
            'name'       => 'Acme Corp',
            'vat_number' => '300000000000003',
            // ...
        ];
    }

    public function toZatcaBuyer(): array
    {
        return [
            'name'       => $this->customer->name,
            'vat_number' => $this->customer->vat_number,
        ];
    }

    public function toZatcaItems(): array
    {
        return $this->items->map(fn($item) => [
            'name'     => $item->name,
            'quantity' => $item->qty,
            'price'    => $item->price,
        ])->toArray();
    }
}
```

### 3. Generate XML and Submit

[](#3-generate-xml-and-submit)

Once your model is configured, submission is one method call away:

```
$invoice = Invoice::find(1);

// Phase 1: Generate XML locally
$xml = $invoice->generateZatcaXml();

// Phase 2: Submit to ZATCA directly (auto-signs and routes to Clearance or Reporting)
$response = $invoice->submitToZatca();

if ($response->isSuccessful()) {
    echo "Invoice submitted successfully!";
} else {
    print_r($response->errors);
}
```

### Fluent API (Without Models)

[](#fluent-api-without-models)

You can also use the Facade to build and submit invoices manually:

```
use Hyderkamran\LaravelZatca\Facades\Zatca;

$invoiceService = Zatca::invoice()
    ->simplified()
    ->seller(['name' => 'Acme', 'vat_number' => '300000000000003'])
    ->buyer(['name' => 'John Doe'])
    ->items([
        ['name' => 'Service A', 'quantity' => 1, 'price' => 100],
    ])
    ->vat(15);

// Get Base64 QR Code Image
$qrBase64 = $invoiceService->generateQrCode();

// Get valid XML
$xml = $invoiceService->generate();

// Submit
$response = Zatca::submit($invoiceService);
```

Credits
-------

[](#credits)

- [Kamran Haider](https://github.com/haider-kamran)

Support
-------

[](#support)

Please open an issue in GitHub if you encounter any problems or have feature requests.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

If you discover a security vulnerability within this package, please send an e-mail to the maintainer. All security vulnerabilities will be promptly addressed.

License
-------

[](#license)

The MIT License (MIT).

###  Health Score

20

—

LowBetter than 12% of packages

Maintenance59

Moderate activity, may be stable

Popularity4

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3443560?v=4)[Syed Kamran Haider](/maintainers/kamranhaider)[@kamranhaider](https://github.com/kamranhaider)

### Embed Badge

![Health badge](/badges/hyderkamran-laravel-zatca/health.svg)

```
[![Health](https://phpackages.com/badges/hyderkamran-laravel-zatca/health.svg)](https://phpackages.com/packages/hyderkamran-laravel-zatca)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k18](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)