PHPackages                             corecave/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. corecave/laravel-zatca

ActiveLibrary[API Development](/categories/api)

corecave/laravel-zatca
======================

Laravel package for ZATCA e-invoicing integration (Saudi Arabia Phase 2)

v1.2.0(5mo ago)61.8k↓46.1%2MITPHPPHP ^8.1

Since Dec 5Pushed 5mo agoCompare

[ Source](https://github.com/nadyshalaby/laravel-zatca)[ Packagist](https://packagist.org/packages/corecave/laravel-zatca)[ RSS](/packages/corecave-laravel-zatca/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (9)Versions (5)Used By (0)

Laravel ZATCA
=============

[](#laravel-zatca)

A comprehensive Laravel package for integrating with Saudi Arabia's ZATCA (Zakat, Tax and Customs Authority) e-invoicing system (FATOORA platform).

Features
--------

[](#features)

- CSR generation and certificate management
- Invoice XML generation (UBL 2.1 compliant)
- Digital signing with ECDSA (secp256k1)
- QR code generation (TLV format with 9 tags)
- QR code image generation (PNG/SVG) for invoices
- Invoice reporting (B2C simplified invoices)
- Invoice clearance (B2B standard invoices)
- Credit and debit note handling
- Hash chain management (ICV & PIH)
- Sandbox, simulation, and production environments

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10.x, 11.x, or 12.x
- OpenSSL extension
- GMP extension (recommended for better performance)
- `simplesoftwareio/simple-qrcode` (optional, for QR code image generation)

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

[](#installation)

```
composer require corecave/laravel-zatca
```

Publish the configuration file:

```
php artisan vendor:publish --tag=zatca-config
```

Run the migrations:

```
php artisan migrate
```

### Optional: QR Code Image Generation

[](#optional-qr-code-image-generation)

To generate QR code images (PNG/SVG) for embedding in emails or PDFs:

```
composer require simplesoftwareio/simple-qrcode
```

Configuration
-------------

[](#configuration)

Add these environment variables to your `.env` file:

```
# Environment: sandbox, simulation, or production
ZATCA_ENVIRONMENT=simulation

# ===========================================
# Seller Information
# ===========================================
ZATCA_SELLER_NAME="Your Company Name"
ZATCA_SELLER_NAME_AR="اسم شركتك بالعربي"

# VAT Number: 15 digits, format: 3XXXXXXXXXX0003
# - Must start with 3
# - Followed by 10-digit registration number
# - Followed by 0003
ZATCA_VAT_NUMBER=310000000000003

# Commercial Registration Number (CRN): 10 digits
ZATCA_REGISTRATION_NUMBER=1000000000

# ===========================================
# Seller Address (Required for SA)
# ===========================================
ZATCA_SELLER_STREET="Main Street"
ZATCA_SELLER_BUILDING="1234"           # 4 digits
ZATCA_SELLER_CITY="Riyadh"
ZATCA_SELLER_DISTRICT="Al Olaya"
ZATCA_SELLER_POSTAL_CODE="12345"       # 5 digits
ZATCA_SELLER_ADDITIONAL_NUMBER="1234"  # 4 digits (optional)

# ===========================================
# CSR Configuration
# ===========================================
ZATCA_CSR_ORGANIZATION="Your Company Name"
ZATCA_CSR_ORGANIZATION_UNIT="Main Branch"
# Common name format depends on environment:
# - Simulation: TST-886431145-{VAT_NUMBER}
# - Production: {VAT_NUMBER}
ZATCA_CSR_COMMON_NAME="TST-886431145-310000000000003"

# Invoice types: 1100 = B2B + B2C, 1000 = B2C only, 0100 = B2B only
ZATCA_INVOICE_TYPES=1100

# Business category
ZATCA_BUSINESS_CATEGORY="Retail"
ZATCA_CITY="Riyadh"

# ===========================================
# Debug (optional, for development)
# ===========================================
ZATCA_DEBUG_ENABLED=true
ZATCA_DEBUG_PATH=zatca/debug
```

Understanding ZATCA Environments
--------------------------------

[](#understanding-zatca-environments)

EnvironmentPortalAPI EndpointPurpose`sandbox`Developer Portal`/developer-portal`Basic development testing with mock certificates`simulation`Simulation Portal`/simulation`Real testing with ZATCA - invoices are validated but not recorded`production`FATOORA Portal`/core`Live production - invoices are legally binding**Important Notes:**

- **Sandbox** uses mock certificates that won't pass ZATCA validators - only for initial development
- **Simulation** uses real ZATCA certificates but invoices aren't recorded - use for integration testing
- **Production** is live - every invoice submitted is legally binding

Complete Onboarding Process
---------------------------

[](#complete-onboarding-process)

### Overview

[](#overview)

The onboarding process involves 4 steps:

1. **Generate CSR** - Create a Certificate Signing Request
2. **Get Compliance CSID** - Submit CSR with OTP to get a compliance certificate
3. **Pass Compliance Checks** - Submit sample invoices for validation
4. **Get Production CSID** - Exchange compliance certificate for production certificate

### Step 1: Generate CSR

[](#step-1-generate-csr)

```
php artisan zatca:generate-csr --save
```

This generates:

- A private key (stored securely)
- A CSR file for submission to ZATCA

### Step 2: Get Compliance CSID & Run Compliance Checks

[](#step-2-get-compliance-csid--run-compliance-checks)

1. Log in to the appropriate ZATCA portal:

    - **Simulation**:  (simulation section)
    - **Production**:  (production section)
2. Navigate to your EGS (e-Invoice Generation Solution) unit
3. Generate a new OTP (One-Time Password)
4. Run the compliance command within 1 hour (OTP expires):

```
# For simulation environment
php artisan zatca:compliance --otp=123456

# The command will:
# 1. Submit your CSR to ZATCA
# 2. Receive a compliance certificate (CSID)
# 3. Run compliance checks with sample invoices
# 4. Display pass/fail status for each check
```

### Step 3: Get Production CSID

[](#step-3-get-production-csid)

After **ALL** compliance checks pass, request your production certificate:

```
php artisan zatca:production-csid
```

**Important:**

- This command does NOT require a new OTP
- It uses your compliance certificate to authenticate
- The compliance request ID is used to verify you passed compliance
- Only works if you completed Step 2 successfully

### Step 4: Start Issuing Invoices

[](#step-4-start-issuing-invoices)

Once you have a production certificate, you can start issuing legally-binding invoices:

```
use Corecave\Zatca\Facades\Zatca;

// The package automatically uses your production certificate
$result = Zatca::process($invoice);
```

Full Usage Example
------------------

[](#full-usage-example)

Here's a complete example from building an invoice to submitting it:

```