PHPackages yr-group/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. yr-group/laravel-zatca ActiveLibrary[API Development](/categories/api) yr-group/laravel-zatca ====================== Easy-to-use Laravel package for ZATCA (Saudi Arabian E-Invoicing) Phase 1 and Phase 2 integration 1.0.1(7mo ago)0131MITPHPPHP ^8.1 Since Oct 5Pushed 7mo agoCompare [ Source](https://github.com/DevYSM/laravel-zatca)[ Packagist](https://packagist.org/packages/yr-group/laravel-zatca)[ RSS](/packages/yr-group-laravel-zatca/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (1)Dependencies (3)Versions (2)Used By (0) Laravel ZATCA Package ===================== [](#laravel-zatca-package) Easy-to-use Laravel package for ZATCA (Saudi Arabian E-Invoicing) Phase 1 and Phase 2 integration. Features -------- [](#features) - ✅ **Phase 1**: Simple QR Code generation for invoices - ✅ **Phase 2**: Full E-Invoicing integration with ZATCA - CSR (Certificate Signing Request) generation - Compliance CSID acquisition - Production CSID acquisition - Invoice signing and submission - Support for both B2B (reporting) and B2C (clearance) invoices Installation ------------ [](#installation) 1. Require the package ``` composer require yr-group/laravel-zatca ``` 2. Publish the configuration file: ``` php artisan vendor:publish --tag=zatca-config ``` 3. Configure your `.env` file: ``` ZATCA_ENVIRONMENT=simulation # or 'production' ZATCA_SOLUTION_NAME=MyERP ZATCA_VERSION=1.0.0 ``` Usage ----- [](#usage) ### Phase 1: QR Code Generation [](#phase-1-qr-code-generation) Generate simple QR codes for invoices (for Phase 1 compliance): ``` use YrGroup\LaravelZatca\Facades\Zatca; // Generate QR code $qrCode = Zatca::phaseOne() ->sellerName('My Company') ->vatNumber('123456789123456') ->timestamp(now()) ->totalWithVat('115.00') ->vatTotal('15.00') ->generate(); // Generate as base64 PNG $qrCodeBase64 = Zatca::phaseOne() ->sellerName('My Company') ->vatNumber('123456789123456') ->timestamp(now()) ->totalWithVat('115.00') ->vatTotal('15.00') ->generateBase64(); ``` ### Phase 2: Full E-Invoicing Integration [](#phase-2-full-e-invoicing-integration) #### Step 1: Generate CSR (Certificate Signing Request) [](#step-1-generate-csr-certificate-signing-request) ``` use YrGroup\LaravelZatca\Facades\Zatca; $merchantData = [ 'vat_number' => '310461435700003', 'solution_name' => config('zatca.solution_name'), 'version' => config('zatca.version'), 'serial_number' => '1-TST|2-TST|3-' . uniqid(), 'common_name' => 'TST-886431145-399999999900003', 'organization_name' => 'My Test Company', 'organizational_unit' => 'Riyad Branch', 'registered_address' => 'Riyadh', 'business_category' => 'Retail', ]; $result = Zatca::csr()->generateCSR($merchantData); // Returns: // [ // 'csr_content' => '...', // 'private_key_path' => '/path/to/private_key.pem', // 'csr_path' => '/path/to/csr.pem' // ] ``` #### Step 2: Get Compliance Certificate [](#step-2-get-compliance-certificate) Get an OTP from the ZATCA portal: - Simulation: - Production: ``` $csrContent = file_get_contents(storage_path('app/zatca/csr.pem')); $otp = '123456'; // From ZATCA portal $result = Zatca::api()->getComplianceCSID($csrContent, $otp); // Save the certificate and secret file_put_contents(storage_path('app/zatca/certificate.txt'), $result['binary_security_token']); file_put_contents(storage_path('app/zatca/secret.txt'), $result['secret']); ``` #### Step 3: Sign and Submit Invoice [](#step-3-sign-and-submit-invoice) ``` // Load your XML invoice (must conform to ZATCA UBL 2.1 format) $xmlInvoice = file_get_contents(storage_path('app/zatca/invoices/invoice.xml')); // Load certificate and secret $certificate = file_get_contents(storage_path('app/zatca/certificate.txt')); $secret = file_get_contents(storage_path('app/zatca/secret.txt')); $privateKeyPath = storage_path('app/zatca/private_key.pem'); // Sign the invoice $signedData = Zatca::invoice()->signInvoice( $xmlInvoice, $certificate, $privateKeyPath, $secret ); // Extract UUID from XML $doc = new \DOMDocument(); $doc->loadXML($xmlInvoice); $xpath = new \DOMXPath($doc); $uuid = $xpath->query('//cbc:UUID')->item(0)->nodeValue; // Report invoice (B2B - Standard invoices) $result = Zatca::api()->reportInvoice( $signedData['signed_invoice'], $signedData['hash'], $uuid, $certificate, $secret ); // Or clear invoice (B2C - Simplified invoices) $result = Zatca::api()->clearInvoice( $signedData['signed_invoice'], $signedData['hash'], $uuid, $certificate, $secret ); ``` #### Step 4: Get Production CSID (After Compliance Testing) [](#step-4-get-production-csid-after-compliance-testing) ``` $complianceRequestId = 'request-id-from-compliance'; $certificate = file_get_contents(storage_path('app/zatca/certificate.txt')); $secret = file_get_contents(storage_path('app/zatca/secret.txt')); $result = Zatca::api()->getProductionCSID( $complianceRequestId, $certificate, $secret ); // Save production certificate and secret file_put_contents(storage_path('app/zatca/prod_certificate.txt'), $result['binary_security_token']); file_put_contents(storage_path('app/zatca/prod_secret.txt'), $result['secret']); ``` Test Mode Username & Password --------------------------------- [](#test-mode-username--password) ``` ZATCA_TEST_MODE_REPORTING_USERNAME ZATCA_TEST_MODE_REPORTING_PASSWORD ``` You can get the username and password from the ZATCA portal. API Reference ------------- [](#api-reference) ### ZatcaPhaseOneService [](#zatcaphaseoneservice) ``` Zatca::phaseOne() ->sellerName(string $name) ->vatNumber(string $vatNumber) ->timestamp($timestamp) ->totalWithVat(string $total) ->vatTotal(string $vat) ->generate(?QrCodeOptions $options = null): string ->generateBase64(): string ``` ### ZatcaService (CSR Generation) [](#zatcaservice-csr-generation) ``` Zatca::csr()->generateCSR(array $merchantData): array ``` ### ZatcaAPIService [](#zatcaapiservice) ``` Zatca::api()->getComplianceCSID(string $csrContent, string $otp): array Zatca::api()->checkInvoiceCompliance(string $signedInvoice, string $invoiceHash, string $uuid, string $certificate, string $secret): array Zatca::api()->getProductionCSID(string $complianceRequestId, string $certificate, string $secret): array Zatca::api()->reportInvoice(string $signedInvoice, string $invoiceHash, string $uuid, string $certificate, string $secret): array Zatca::api()->clearInvoice(string $signedInvoice, string $invoiceHash, string $uuid, string $certificate, string $secret): array ``` ### ZatcaInvoiceService [](#zatcainvoiceservice) ``` Zatca::invoice()->signInvoice(string $xmlInvoice, string $certificateContent, string $privateKeyPath, string $secret): array ``` Configuration ------------- [](#configuration) The package uses the following configuration options (in `config/zatca.php`): - `environment`: ZATCA environment (`simulation` or `production`) - `otp`: One-Time Password from ZATCA portal - `solution_name`: Your ERP/POS solution name - `version`: Your solution version - `certificate_path`: Path to store certificates - `private_key_path`: Path to store private keys - `secret_path`: Path to store secrets Requirements ------------ [](#requirements) - PHP 8.1 or higher - Laravel 11.0 or higher - salla/zatca package - prgayman/laravel-zatca package License ------- [](#license) MIT License Credits ------- [](#credits) Built with ❤️ by YR-Group [Yassen Sayed](https://yassensayed.com/) & [Ramadan Ewis](https://ramadanewais.com). ### Health Score 33 — LowBetter than 75% of packages Maintenance64 Regular maintenance activity Popularity8 Limited adoption so far Community7 Small or concentrated contributor base Maturity44 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 Unknown Total 1 Last Release 220d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/94ad099ac29460710c50f3c27489ebd2e8ee24d3cd5bfbaf040cd5d4a3a2dd1a?d=identicon)[Yassen Sayed](/maintainers/Yassen%20Sayed) --- Top Contributors [![DevYSM](https://avatars.githubusercontent.com/u/59166666?v=4)](https://github.com/DevYSM "DevYSM (8 commits)") --- Tags qr codelaravelZATCAfatoorae-invoicingsaudi ### Embed Badge ![Health badge](/badges/yr-group-laravel-zatca/health.svg) ``` [![Health](https://phpackages.com/badges/yr-group-laravel-zatca/health.svg)](https://phpackages.com/packages/yr-group-laravel-zatca) ``` ### Alternatives [andreaselia/laravel-api-to-postman Generate a Postman collection automatically from your Laravel API 1.0k586.2k3](/packages/andreaselia-laravel-api-to-postman)[mollie/laravel-mollie Mollie API client wrapper for Laravel & Mollie Connect provider for Laravel Socialite 3624.1M28](/packages/mollie-laravel-mollie)[api-ecosystem-for-laravel/dingo-api A RESTful API package for the Laravel and Lumen frameworks. 3121.5M10](/packages/api-ecosystem-for-laravel-dingo-api)[essa/api-tool-kit set of tools to build an api with laravel 52680.5k](/packages/essa-api-tool-kit)[mll-lab/laravel-graphiql Easily integrate GraphiQL into your Laravel project 683.2M9](/packages/mll-lab-laravel-graphiql)[kirschbaum-development/laravel-openapi-validator Automatic OpenAPI validation for Laravel HTTP tests 581.1M5](/packages/kirschbaum-development-laravel-openapi-validator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)