Download the PHP package sevaske/zatca-api without Composer

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: https://github.com/sevaske/php-zatca-xml

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

Invoice types

• Reporting (B2P)
  Used for invoices issued to consumers.

• Clearance (B2B)
  Used for invoices issued to VAT-registered businesses.

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

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

Installation

Usage

Client Initialization

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

Compliance Certificate Request

Authorized requests

Create AuthToken from compliance certificate to make authorized requests.

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.

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.

Submitting Production Invoices

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

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:

Example

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

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