PHPackages saudizatca/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. saudizatca/laravel-zatca ActiveLibrary[API Development](/categories/api) saudizatca/laravel-zatca ======================== Complete Laravel package for ZATCA (Saudi Arabia) E-Invoicing Phase 2 integration - Supports Sandbox, Simulation, and Production environments v1.1.3(1mo ago)05MITPHPPHP ^8.1 Since May 3Pushed 1mo agoCompare [ Source](https://github.com/z3i0/zatca-invoicing)[ Packagist](https://packagist.org/packages/saudizatca/laravel-zatca)[ RSS](/packages/saudizatca-laravel-zatca/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (9)Versions (6)Used By (0) ZATCA E-Invoicing Laravel Package ================================= [](#zatca-e-invoicing-laravel-package) [![ZATCA Phase 2](https://camo.githubusercontent.com/0dc295ecef933ad61a1aba57aa02afffa60f05a7d6ed9a02f5470b0fab0b4974/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5a415443412d5068617365253230322d626c7565)](https://camo.githubusercontent.com/0dc295ecef933ad61a1aba57aa02afffa60f05a7d6ed9a02f5470b0fab0b4974/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5a415443412d5068617365253230322d626c7565) [![Laravel](https://camo.githubusercontent.com/8f36112d9b8ae5926c7d2d27744660ab14cd431c94cf6f489f07a29dd9625865/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825324631312e7825324631322e7825324631332e782d726564)](https://camo.githubusercontent.com/8f36112d9b8ae5926c7d2d27744660ab14cd431c94cf6f489f07a29dd9625865/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825324631312e7825324631322e7825324631332e782d726564) [![PHP 8.1+](https://camo.githubusercontent.com/396e308627273611a751aa614834c4a6cd0b268c51ab52ab5330f94b99771fbc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d707572706c65)](https://camo.githubusercontent.com/396e308627273611a751aa614834c4a6cd0b268c51ab52ab5330f94b99771fbc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d707572706c65) [![MIT License](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e) Complete Laravel package for **ZATCA (Saudi Arabia) E-Invoicing Phase 2** integration. Supports all three environments: **Sandbox**, **Simulation**, and **Production**. Features -------- [](#features) - **Certificate Management**: CSR generation with secp256k1 ECC keys - **Compliance CSID**: Request compliance certificates from ZATCA - **Production CSID**: Request production certificates after passing compliance - **Invoice Generation**: UBL 2.1 compliant XML for all invoice types - **Digital Signing**: ECDSA SHA-256 signatures (XAdES-BES) - **QR Code Generation**: ZATCA TLV format (Phase 1 & Phase 2) - **Invoice Submission**: Reporting (B2C) and Clearance (B2B) - **Credit/Debit Notes**: Full support for invoice adjustments - **Arabic Support**: Bilingual invoice support - **Multi-Environment**: Sandbox, Simulation, and Production - **Comprehensive Logging**: Detailed logging of all operations - **Database Storage**: Track all invoices and certificates - **Full Test Coverage**: Unit and Feature tests included Requirements ------------ [](#requirements) - PHP 8.1+ - Laravel 10.x / 11.x / 12.x / 13.x - OpenSSL extension with EC support - GMP extension (recommended) - ext-dom, ext-mbstring, ext-json, ext-xmlwriter, ext-curl Installation ------------ [](#installation) ``` composer require saudizatca/laravel-zatca ``` Publish configuration: ``` php artisan vendor:publish --tag=zatca-config ``` Run migrations: ``` php artisan migrate ``` Configuration ------------- [](#configuration) Add to your `.env` file: ``` # Environment: sandbox | simulation | production ZATCA_ENVIRONMENT=sandbox # Seller Information ZATCA_SELLER_NAME_EN="Your Company Name" ZATCA_SELLER_NAME_AR="اسم شركتك بالعربي" ZATCA_VAT_NUMBER=300000000000003 # Address ZATCA_SELLER_STREET="King Fahd Road" ZATCA_SELLER_BUILDING="1234" ZATCA_SELLER_CITY="Riyadh" ZATCA_SELLER_DISTRICT="Al Olaya" ZATCA_SELLER_POSTAL_CODE="12345" # CSR Configuration ZATCA_CSR_ORGANIZATION="Your Company Name" ZATCA_CSR_ORGANIZATION_UNIT="IT Department" ZATCA_CSR_COMMON_NAME="Your Company Name" # Sandbox Credentials (from ZATCA Developer Portal) ZATCA_SANDBOX_USERNAME=your_sandbox_username ZATCA_SANDBOX_PASSWORD=your_sandbox_password # Debug (optional) ZATCA_DEBUG_ENABLED=true ``` Quick Start ----------- [](#quick-start) ### 1. Check Status [](#1-check-status) ``` php artisan zatca:status ``` ### 2. Generate CSR [](#2-generate-csr) ``` php artisan zatca:csr --vat=300000000000003 --org="Your Company" ``` ### 3. Request Compliance CSID [](#3-request-compliance-csid) Get OTP from ZATCA portal, then: ``` php artisan zatca:compliance-csid --otp=123456 ``` ### 4. Request Production CSID (after compliance tests pass) [](#4-request-production-csid-after-compliance-tests-pass) ``` php artisan zatca:production-csid ``` ### 5. Submit Invoices [](#5-submit-invoices) ``` # Simplified invoice (B2C) php artisan zatca:report --number=INV-001 --total=115 --vat=15 # Standard invoice (B2B) - requires XML file php artisan zatca:clear --xml=/path/to/signed_invoice.xml ``` Programmatic Usage ------------------ [](#programmatic-usage) ### Generate CSR [](#generate-csr) ``` use SaudiZATCA\Facades\Zatca; $result = Zatca::certificate()->generateCSR([ 'organization_identifier' => '300000000000003', 'organization' => 'Your Company', 'common_name' => 'Your Company', 'street' => 'King Fahd Road', 'city' => 'Riyadh', ]); // $result['csr'] - CSR content // $result['private_key'] - Private key content ``` ### Create and Submit Invoice [](#create-and-submit-invoice) ``` use SaudiZATCA\Facades\Zatca; use SaudiZATCA\Data\InvoiceData; use SaudiZATCA\Data\InvoiceLineData; use SaudiZATCA\Data\SellerData; use SaudiZATCA\Data\BuyerData; // Create seller $seller = SellerData::fromConfig(config('zatca.seller')); // Create buyer (for B2B/standard invoices) $buyer = new BuyerData( name: 'Buyer Company', vatNumber: '300000000000004', city: 'Jeddah' ); // Create invoice $invoice = new InvoiceData( invoiceNumber: 'INV-001', issueDate: new DateTime(), lines: [ new InvoiceLineData('Product A', 2, 50.0, 15.0), new InvoiceLineData('Product B', 1, 100.0, 15.0), ], type: InvoiceData::TYPE_STANDARD // or TYPE_SIMPLIFIED ); // Process (generate XML, sign, QR, submit) $result = Zatca::processInvoice($invoice, $seller, $buyer); // $result['uuid'] // $result['invoice_hash'] // $result['signed_xml'] // $result['qr_code'] // $result['submission'] ``` ### Generate QR Code (Phase 1 - Basic) [](#generate-qr-code-phase-1---basic) ``` use SaudiZATCA\Facades\Zatca; use SaudiZATCA\Data\SellerData; $seller = new SellerData('Your Company', '300000000000003'); $qrCode = Zatca::generatePhase1QR($seller, 115.0, 15.0); // Returns Base64-encoded TLV QR data ``` ### Working with Existing XML [](#working-with-existing-xml) ``` use SaudiZATCA\Facades\Zatca; // Generate XML only $xml = Zatca::xml()->generate($invoice, $seller, $buyer); // Sign existing XML $signedResult = Zatca::invoice()->signInvoice($xml, $invoice); // Generate QR for signed invoice $qrCode = Zatca::invoice()->generateQRCode($seller, $invoice, $signedResult['invoice_hash'], $signedResult); // Submit to ZATCA $submission = Zatca::invoice()->submitToZatca($signedResult['signed_xml'], $signedResult['invoice_hash'], $invoice); ``` Invoice Types ------------- [](#invoice-types) TypeDescriptionSubmission Method`standard`B2B Tax InvoiceClearance (real-time)`simplified`B2C Simplified InvoiceReporting (within 24h)`credit_note`Credit NoteClearance`debit_note`Debit NoteClearanceArtisan Commands ---------------- [](#artisan-commands) CommandDescription`zatca:status`Check integration status`zatca:csr`Generate CSR`zatca:compliance-csid`Request compliance CSID`zatca:production-csid`Request production CSID`zatca:report`Submit simplified invoice`zatca:clear`Submit standard invoice`zatca:validate`Validate XML or QR codeDatabase Models --------------- [](#database-models) ### ZatcaCertificate [](#zatcacertificate) Stores certificate information: ``` use SaudiZATCA\Models\ZatcaCertificate; // Get active production certificate $cert = ZatcaCertificate::active() ->environment('production') ->first(); // Check validity if ($cert && $cert->isValid()) { // Use certificate } ``` ### ZatcaInvoice [](#zatcainvoice) Tracks all invoices: ``` use SaudiZATCA\Models\ZatcaInvoice; // Get pending invoices $pending = ZatcaInvoice::pending()->get(); // Get today's invoices $today = ZatcaInvoice::today()->get(); // Get by status $submitted = ZatcaInvoice::status('submitted')->get(); ``` ### ZatcaLog [](#zatcalog) Detailed operation logs: ``` use SaudiZATCA\Models\ZatcaLog; // Get recent errors $errors = ZatcaLog::errors()->recent(24)->get(); // Get API logs $apiLogs = ZatcaLog::category('api')->recent()->get(); ``` Environments ------------ [](#environments) ### Sandbox [](#sandbox) - For initial development and testing - Uses ZATCA Developer Portal - Pre-configured test credentials ### Simulation [](#simulation) - Pre-production testing - Requires real CSID from compliance - Tests with real API structure ### Production [](#production) - Live environment - Requires production CSID - Real invoice submission Testing ------- [](#testing) Run the test suite: ``` # Run all tests vendor/bin/phpunit # With coverage vendor/bin/phpunit --coverage-html coverage # Run specific test vendor/bin/phpunit --filter=CertificateServiceTest ``` ### Test Structure [](#test-structure) ``` tests/ ├── Unit/ │ ├── CertificateServiceTest.php │ ├── InvoiceServiceTest.php │ └── QRCodeServiceTest.php └── Feature/ ├── APIIntegrationTest.php └── InvoiceSubmissionTest.php ``` Error Handling -------------- [](#error-handling) All exceptions extend `ZatcaException`: ``` use SaudiZATCA\Exceptions\ZatcaException; use SaudiZATCA\Exceptions\CertificateException; use SaudiZATCA\Exceptions\APIException; use SaudiZATCA\Exceptions\InvoiceException; try { $result = Zatca::processInvoice($invoice, $seller); } catch (CertificateException $e) { // Handle certificate errors Log::error('Certificate: ' . $e->getMessage()); } catch (APIException $e) { // Handle API errors Log::error('API Error (' . $e->getStatusCode() . '): ' . $e->getMessage()); if ($e->getDetails()) { Log::error('Details: ' . json_encode($e->getDetails())); } } catch (InvoiceException $e) { // Handle invoice errors Log::error('Invoice: ' . $e->getMessage()); } catch (ZatcaException $e) { // Handle general ZATCA errors Log::error('ZATCA: ' . $e->getMessage()); } ``` Logging ------- [](#logging) Configure logging in `config/zatca.php`: ``` 'logging' => [ 'enabled' => true, 'channel' => 'zatca', // Create this channel in logging.php 'level' => 'debug', 'log_api_requests' => true, 'log_api_responses' => true, 'log_sensitive_data' => false, // Set false in production ], ``` Add to `config/logging.php`: ``` 'channels' => [ 'zatca' => [ 'driver' => 'single', 'path' => storage_path('logs/zatca.log'), 'level' => 'debug', ], ], ``` Security -------- [](#security) - Never commit `.env` files with real credentials - Use `log_sensitive_data: false` in production - Store certificates securely (storage path should be outside web root) - Rotate certificates before expiry - Use HTTPS for all API communications in production Troubleshooting --------------- [](#troubleshooting) ### Certificate Issues [](#certificate-issues) ``` # Check OpenSSL EC support php -r "var_dump(openssl_get_curve_names());" # Verify CSR content openssl req -in storage/zatca/certificates/csr.pem -text -noout ``` ### API Connection Issues [](#api-connection-issues) ``` # Check ZATCA status php artisan zatca:status # Test with debug enabled ZATCA_DEBUG_ENABLED=true php artisan zatca:report --number=TEST ``` Contributing ------------ [](#contributing) 1. Fork the repository 2. Create a feature branch 3. Write tests for new functionality 4. Ensure all tests pass 5. Submit a pull request License ------- [](#license) This package is open-sourced software licensed under the [MIT license](LICENSE). Support ------- [](#support) For issues and feature requests, please use the [GitHub issue tracker](https://github.com/saudizatca/laravel-zatca/issues). References ---------- [](#references) - [ZATCA E-Invoicing Portal](https://zatca.gov.sa/en/E-Invoicing/Pages/default.aspx) - [ZATCA Developer Portal](https://developer.zatca.gov.sa/) - [ZATCA Technical Guidelines](https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing-Detailed-Technical-Guideline.pdf) ### Health Score 39 — LowBetter than 84% of packages Maintenance93 Actively maintained with recent releases Popularity5 Limited adoption so far Community6 Small or concentrated contributor base Maturity46 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 ~0 days Total 5 Last Release 36d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/49f1cd648d707c50e6fbc80f7ca992fb7406e256ef8ae82d6176c2591eeed232?d=identicon)[z3i0](/maintainers/z3i0) --- Top Contributors [![z3i0](https://avatars.githubusercontent.com/u/96726335?v=4)](https://github.com/z3i0 "z3i0 (9 commits)") --- Tags laravelvattaxZATCAfatoorae-invoicingsaudi-arabiaphase 2 ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/saudizatca-laravel-zatca/health.svg) ``` [![Health](https://phpackages.com/badges/saudizatca-laravel-zatca/health.svg)](https://phpackages.com/packages/saudizatca-laravel-zatca) ``` ### Alternatives [larastan/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 6.4k51.0M7.4k](/packages/larastan-larastan)[psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[laravel/ai The official AI SDK for Laravel. 9782.1M153](/packages/laravel-ai)[calebdw/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 15104.9k4](/packages/calebdw-larastan)[simplestats-io/laravel-client Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof. 5019.3k](/packages/simplestats-io-laravel-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)