sevaske / zatca-api
PHP client for the ZATCA (Fatoora) e-invoicing API: reporting, clearance, compliance and certificates.
Requires
- php: ^7.4 || ^8.0
- ext-dom: *
- ext-json: *
- php-http/discovery: ^1.15
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0 || ^2.0
Requires (Dev)
- nyholm/psr7: ^1.8
- php-http/mock-client: ^1.6
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^9.6
Suggests
- guzzlehttp/guzzle: A popular PSR-18 HTTP client implementation
- sevaske/php-zatca-xml: Generates and signs ZATCA XML invoices to submit with this client
- symfony/http-client: A PSR-18 HTTP client implementation (requires nyholm/psr7)
Provides
None
Conflicts
None
Replaces
None
README
ZATCA API PHP Client
This is a simple PHP library to work with the ZATCA API. You can send invoice data, check invoice status, verify compliance, and manage certificates easily.
If you’re looking for a library to generate XML invoices, you can use this one: https://github.com/sevaske/php-zatca-xml
Features
- Supports all major ZATCA API endpoints
- Simple authentication with certificate and secret
- Response handling via typed response objects
- Environment support: sandbox, simulation, production
- Uses any PSR-18 compatible HTTP client (e.g., Guzzle). Clients other than Guzzle need
guzzlehttp/psr7ornyholm/psr7installed to build requests
Installation
composer require sevaske/zatca-api
Quick Start
use GuzzleHttp\Client; use Sevaske\ZatcaApi\Api; use Sevaske\ZatcaApi\Responses\ClearanceResponse; use Sevaske\ZatcaApi\Responses\ComplianceCertificateResponse; use Sevaske\ZatcaApi\Responses\ProductionCertificateResponse; use Sevaske\ZatcaApi\Responses\ReportingResponse; use Sevaske\ZatcaApi\Exceptions\ZatcaRequestException; $httpClient = new Client(); $api = new Api('simulation', $httpClient); try { $response = $api->complianceCertificate('my csr', 'otp code'); // ComplianceCertificateResponse if (! $response->success()) { // handle } $credentials = [ 'requestId' => $response->requestId(), 'secret' => $response->secret(), 'certificate' => $response->certificate(), ]; // saving the certificate file_put_contents('credentials.json', json_encode($credentials)); // set the credentials to auth $api->setCredentials($credentials['certificate'], $credentials['secret']); $productionCertificate = $api->productionCertificate($credentials['requestId']); // ProductionCertificateResponse if (! $productionCertificate->success()) { // handle } $productionCredentials = [ 'requestId' => $productionCertificate->requestId(), 'secret' => $productionCertificate->secret(), 'certificate' => $productionCertificate->certificate(), ]; // saving the certificate file_put_contents('production-credentials.json', json_encode($productionCredentials)); // set the credentials to auth $api->setCredentials($productionCredentials['certificate'], $productionCredentials['secret']); $reportingResponse = $api->reporting('signed-xml-invoice', 'invoice-hash', 'uuid', true); // ReportingResponse $reportingResponse->success(); $reportingResponse->warnings(); $clearanceResponse = $api->clearance('signed-xml-invoice', 'invoice-hash', 'uuid', true); // ClearanceResponse $reportingResponse->success(); $reportingResponse->warnings(); } catch (ZatcaRequestException $e) { echo "Request error: " . $e->getMessage(); print_r($e->context()); }
Available Methods
| Method | Description |
|---|---|
reporting() |
Submit invoice data to ZATCA |
clearance() |
Request invoice clearance status |
compliance() |
Verify invoice compliance |
complianceCertificate() |
Request compliance certificate |
productionCertificate() |
Obtain production certificate |
renewProductionCertificate() |
Renew production certificate |
Notes
$invoiceHashmay benullforreporting(),clearance()andcompliance(): the hash is then taken from the signature of the signed invoice (the digest of theinvoiceSignedDatareference).- Every response has
statusCode()(the HTTP status) andsuccess(). - If your HTTP client does not throw on HTTP errors (e.g. Guzzle with
http_errors => falseor a pure PSR-18 client), responses like 401 or 500 are returned as response objects: always checksuccess().
Exception handling
The library throws the following exceptions which you can catch and handle:
ZatcaException— general exception classZatcaRequestException— errors during the HTTP requestZatcaResponseException— errors processing the API response
When ZATCA answers with an HTTP error (e.g. a rejected invoice), the exception context contains the answer:
try { $api->reporting($xml, $hash, $uuid); } catch (ZatcaRequestException $e) { $context = $e->context(); $context['status']; // HTTP status, e.g. 400 $context['errors']; // ZATCA errors: validationResults.errorMessages for invoices, errors for certificates $context['response']; // decoded JSON body $context['content']; // raw body }
status, content, response and errors are present only when the HTTP client provides the error response
(Guzzle does); response and errors only when the body is JSON.
Renewing the production certificate
Renewal is authorized by the current production certificate and requires an OTP from the Fatoora portal and a new CSR.
$api->setCredentials($currentProductionCertificate, $currentSecret); $renewal = $api->renewProductionCertificate($newCsr, $otp); if ($renewal->success()) { // store $renewal->certificate() and $renewal->secret() } elseif ($renewal->isNotCompliant()) { // HTTP 428: ZATCA issued a compliance certificate. Pass the compliance checks with it, // then call productionCertificate($renewal->requestId()) }
Security
- The certificate secret is a credential: store it encrypted or in a secret manager, never in a public directory or in git.
The
file_put_contents()calls in the example above only illustrate the flow. - Do not disable TLS verification in the HTTP client.
- Exceptions keep the original HTTP client exception as
getPrevious(); it may reference the request including theAuthorizationheader, so do not dump it to logs.