PHPackages                             sevaske/zatca-api - 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. sevaske/zatca-api

ActiveLibrary[API Development](/categories/api)

sevaske/zatca-api
=================

2.0.2(4mo ago)414.4k↑89.5%31MITPHPPHP ^7.4||^8.0CI passing

Since Jul 9Pushed 4mo ago2 watchersCompare

[ Source](https://github.com/sevaske/zatca-api)[ Packagist](https://packagist.org/packages/sevaske/zatca-api)[ RSS](/packages/sevaske-zatca-api/feed)WikiDiscussions v2 Synced today

READMEChangelog (7)Dependencies (7)Versions (9)Used By (1)

[![php Version](https://camo.githubusercontent.com/0b3954e6fc6c9801eaae54623e1402030ba579e12a0b5110c78beaf28a83f623/68747470733a2f2f62616467656e2e6e65742f7061636b61676973742f7068702f73657661736b652f7a617463612d617069)](https://camo.githubusercontent.com/0b3954e6fc6c9801eaae54623e1402030ba579e12a0b5110c78beaf28a83f623/68747470733a2f2f62616467656e2e6e65742f7061636b61676973742f7068702f73657661736b652f7a617463612d617069)[![Packagist Stars](https://camo.githubusercontent.com/465b0dddc011500d0e1be305932c41c68bd7f155de63bfdfecbdce60623142f1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f73657661736b652f7a617463612d617069)](https://packagist.org/packages/sevaske/zatca-api)[![Packagist Downloads](https://camo.githubusercontent.com/25a932c61139379b851bdee5bbb489d8ff19590e68a01aab3de7d3ca2f39e026/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73657661736b652f7a617463612d617069)](https://packagist.org/packages/sevaske/zatca-api)[![Packagist Version](https://camo.githubusercontent.com/4b8dc060f37db8164dc8f7928dd9a7d0ff12b7f18fc290e22b59b2efa84c5493/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73657661736b652f7a617463612d617069)](https://packagist.org/packages/sevaske/zatca-api)[![License](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://packagist.org/packages/sevaske/zatca-api)

ZATCA API PHP Client
====================

[](#zatca-api-php-client)

This is a simple PHP library to work with the ZATCA API. You can send invoice data and manage certificates easily.

⚠️ **Note:** This is an unofficial library and not maintained by ZATCA. I do not provide personal support or consulting.

If you’re looking for a library to generate XML invoices, you can use this one:

---

Features
--------

[](#features)

- Full coverage of ZATCA API endpoints (reporting, clearance, compliance)
- Authentication via certificate and secret or auth token
- Supports middleware for request/response processing
- Typed response objects for easy validation and error handling
- Supports multiple environments: sandbox, simulation, production
- Follows PSR standards (PSR-4, PSR-7, PSR-17, PSR-18)
- Works with any PSR-18 compatible HTTP client (e.g., Guzzle)

Environments
------------

[](#environments)

EnvironmentPurposeCertificatessandboxCSR + basic testingSandbox certificatesimulationCompliance invoices (6 required)Compliance certproductionReal invoicesProduction certInvoice types
-------------

[](#invoice-types)

- **Reporting (B2P)**
    Used for invoices issued to consumers.
- **Clearance (B2B)**
    Used for invoices issued to VAT-registered businesses.

Authentication flow
-------------------

[](#authentication-flow)

1. Generate CSR (outside this library)
2. Request compliance certificate
3. Create `ZatcaAuth` from certificate + secret
4. Submit simulation invoices
5. Request production certificate
6. Switch client to `production` environment

Immutability
------------

[](#immutability)

Methods like `withEnvironment()` and `withMiddleware()` return a **new client instance**.
The original client is not modified.

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

[](#installation)

```
composer require sevaske/zatca-api:^2.0
```

Usage
-----

[](#usage)

#### Client Initialization

[](#client-initialization)

Create HTTP client and factories for PSR-17 / PSR-18. For example, GuzzleHttp

```
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Sevaske\ZatcaApi\ZatcaClient;

$httpClient = new Client();
$factory = new HttpFactory();

// Initialize ZatcaClient with sandbox environment
$client = new ZatcaClient(
    $httpClient,
    $factory, // RequestFactoryInterface
    $factory, // StreamFactoryInterface
    'sandbox' // environment: sandbox | simulation | production
);
```

#### Compliance Certificate Request

[](#compliance-certificate-request)

```
use Sevaske\ZatcaApi\Exceptions\ZatcaRequestException;
use Sevaske\ZatcaApi\Exceptions\ZatcaResponseException;

/**
* @var Sevaske\ZatcaApi\ZatcaClient $client
*/

try {
    $certificateResponse = $client->complianceCertificate('your .csr file content', '112233');
} catch (ZatcaRequestException|ZatcaResponseException $e) {
    // handle
}

$credentials = [
    'requestId' => $certificateResponse->requestId(),
    'certificate' => $certificateResponse->certificate(),
    'secret' => $certificateResponse->secret(),
];

print_r($credentials);
file_put_contents('output/credentials.json', json_encode($credentials, JSON_PRETTY_PRINT));
```

#### Authorized requests

[](#authorized-requests)

Create AuthToken from compliance certificate to make authorized requests.

```
use Sevaske\ZatcaApi\ZatcaAuth;

/**
* @var Sevaske\ZatcaApi\Responses\CertificateResponse $certificateResponse
* @var Sevaske\ZatcaApi\ZatcaClient $client
*/

$authToken = new ZatcaAuth($certificateResponse->certificate(), $certificateResponse->secret());
$client->setAuthToken($authToken);
```

#### Submitting Invoices

[](#submitting-invoices)

Once you have a valid compliance certificate and auth token, you can submit invoices in the simulation environment.

**Submitting 6 documents is required to switch to production mode.**

```
use Sevaske\ZatcaApi\Exceptions\ZatcaRequestException;
use Sevaske\ZatcaApi\Exceptions\ZatcaResponseException;

/**
* @var Sevaske\ZatcaApi\ZatcaClient $client
*/

try {
    // B2P
    $client->reportingInvoice('b2p invoice xml', 'hash', 'uuid');
    $client->reportingInvoice('b2p debit note xml', 'hash', 'uuid');
    $client->reportingInvoice('b2p credit note xml', 'hash', 'uuid');

    // B2B
    $client->clearanceInvoice('b2b invoice xml', 'hash', 'uuid');
    $client->clearanceInvoice('b2b debit note xml', 'hash', 'uuid');
    $client->clearanceInvoice('b2b credit note xml', 'hash', 'uuid');
} catch (ZatcaRequestException|ZatcaResponseException $e) {
    // handle
}
```

#### Production Onboarding

[](#production-onboarding)

After submitting the required simulation invoices, you can request a production certificate.

**This certificate allows you to submit real invoices in the production environment.**

```
use Sevaske\ZatcaApi\Exceptions\ZatcaRequestException;
use Sevaske\ZatcaApi\Exceptions\ZatcaResponseException;

/**
* @var \Sevaske\ZatcaApi\ZatcaClient $client
*/

try {
    $productionCertificateResponse = $client->productionCertificate($certificateResponse->requestId());

    $credentials = [
        'requestId' => $productionCertificateResponse->requestId(),
        'certificate' => $productionCertificateResponse->certificate(),
        'secret' => $productionCertificateResponse->secret(),
    ];

    // display
    print_r($credentials);

    // save
    file_put_contents('output/production-credentials.json', json_encode($credentials, JSON_PRETTY_PRINT));
} catch (ZatcaRequestException|ZatcaResponseException $e) {
    // handle
}
```

#### Submitting Production Invoices

[](#submitting-production-invoices)

Once the client is configured with the production certificate and environment, you can submit real invoices to ZATCA.

```
use Sevaske\ZatcaApi\ZatcaAuth;
use Sevaske\ZatcaApi\Exceptions\ZatcaRequestException;
use Sevaske\ZatcaApi\Exceptions\ZatcaResponseException;

/**
* @var Sevaske\ZatcaApi\ZatcaClient $client
* @var Sevaske\ZatcaApi\Responses\ProductionCertificateResponse $productionCertificateResponse
*/
$productionClient = $client->withEnvironment('production');
$productionAuth = new ZatcaAuth($productionCertificateResponse->certificate(), $productionCertificateResponse->secret());
$productionClient->setAuthToken($productionAuth);

try {
    // submitting production invoices
    $responseReporting = $productionClient->reportingInvoice('my real B2P invoice xml', 'hash', 'uuid');
    $responseClearance = $productionClient->clearanceInvoice('my real B2B invoice xml', 'hash', 'uuid');
} catch (ZatcaRequestException|ZatcaResponseException $e) {
    // handle
}

print_r($responseReporting->toArray());
print_r($responseClearance->toArray());
```

Middleware
----------

[](#middleware)

Middleware in `ZatcaClient` allows you to inspect, modify, or wrap HTTP requests and responses. It works as a pipeline, meaning that multiple middleware can be chained together, each receiving the request and a `$next` callable that continues to the next middleware and ultimately to the HTTP client.

`ZatcaClient` provides four ways to manage middleware:

1. **`withMiddleware($middleware)`** – returns a **new cloned instance** with the provided middleware. Existing middleware in the original client is **replaced** in the clone.
2. **`setMiddleware($middleware)`** – **mutates the current instance**, replacing its middleware with the given ones.
3. **`attachMiddleware($middleware)`** – **mutates the current instance**, adding the given middleware to the end of the existing middleware stack.
4. **`withoutMiddleware()`** - returns a **new cloned instance** with no middleware attached.

All middleware must implement the `MiddlewareInterface`:

```
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

interface MiddlewareInterface
{
    /**
     * @param RequestInterface $request The incoming request
     * @param callable $next Callable to forward the request to the next middleware or the HTTP client
     * @return ResponseInterface
     */
    public function handle(RequestInterface $request, callable $next): ResponseInterface;
}
```

#### Example

[](#example)

For example, implementation of "logging" requests and responses:

```
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Sevaske\ZatcaApi\Interfaces\MiddlewareInterface;

// Attach a custom middleware to inspect requests and responses
$client = $client->withMiddleware(new class implements MiddlewareInterface
{
    public function handle(RequestInterface $request, callable $next): ResponseInterface
    {
        // request
        $this->info('URL: ');
        $this->info((string) $request->getUri());
        $this->info('Body: ');
        $this->info($this->safeStreamContents($request->getBody()));

        /**
         * @var $response \Psr\Http\Message\ResponseInterface
         */
        $response = $next($request);

        // response
        $this->info('Response:');
        $this->info($this->safeStreamContents($response->getBody()));

        return $response;
    }

    private function safeStreamContents(\Psr\Http\Message\StreamInterface $stream): string
    {
        if (! $stream->isSeekable()) {
            return '[unseekable stream]';
        }

        // Save original cursor position
        $pos = $stream->tell();

        // Read from beginning
        $stream->rewind();
        $content = $stream->getContents();

        // Restore original cursor
        $stream->seek($pos);

        return $content;
    }

    private function info(string $text): void
    {
        echo "\n\r".$text;
    }
});
```

Exception handling
------------------

[](#exception-handling)

The library throws the following exceptions which you can catch and handle:

- `ZatcaException` — general exception class
- `ZatcaRequestException` — errors during the HTTP request
- `ZatcaResponseException` — errors processing the API response

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance74

Regular maintenance activity

Popularity32

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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.

###  Release Activity

Cadence

Every ~27 days

Recently: every ~19 days

Total

9

Last Release

141d ago

Major Versions

0.0.1 → v1.02025-07-17

v1.x-dev → 2.0.0-alpha2025-11-26

PHP version history (2 changes)0.0.1PHP ^8.1

2.0.0-alphaPHP ^7.4||^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/94643c38672a39a9b675ab6d43f5c1d3c0789300cc052f742a960e0a7d70847e?d=identicon)[sevaske](/maintainers/sevaske)

---

Top Contributors

[![sevaske](https://avatars.githubusercontent.com/u/42838184?v=4)](https://github.com/sevaske "sevaske (62 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sevaske-zatca-api/health.svg)

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

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35789.4k2](/packages/telnyx-telnyx-php)[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k28.0M318](/packages/openai-php-client)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M736](/packages/sylius-sylius)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60216.0M83](/packages/mollie-mollie-api-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)

PHPackages © 2026

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