Quick Start Guide

Requirements

Before installation, ensure your system meets the following requirements:

• PHP ^7.4|^8.0

• Laravel ^8.0|^9.0|^10.0

• OpenSSL Extension

• JSON Extension

• DOM Extension

• cURL Extension

Installation & Setup

composer require hazem7575/zatca

php artisan vendor:publish --provider="Hazem\Zatca\ZatcaServiceProvider"


2. Run migrations:


php artisan migrate
`

Add the following to your `.env` file:

ZATCA_LIVE=false

Basic Usage

Device Registration

First, add the HasZatcaDevice trait to your model:

use Hazem\Zatca\Traits\HasZatcaDevice;

class Store extends Model
{
    use HasZatcaDevice;
}

Then register your device:

$business = Store::find(1);
$device = $business->registerZatcaDevice($request->otp, [
    'vat_no' => $request->tax_number,
    'ci_no' => $request->registration_number,
    'company_name' => $request->organization_name,
    'company_address' => $request->registered_address,
    'company_building' => $request->building_number,
    'company_plot_identification' => $request->plot_identification,
    'company_city_subdivision' => $request->city_sub_division,
    'company_city' => $request->city,
    'company_postal' => $request->postal_number,
    'company_country' => 'SA',
    'solution_name' => 'MADA',
    'common_name' => $request->common_name,
])->active();

Invoice Creation

Add the HasZatcaInvoice trait to your model:

use Hazem\Zatca\Traits\HasZatcaInvoice;

class Order extends Model
{
    use HasZatcaInvoice;
    
    protected function prepareZatcaInvoiceData()
    {
        $items = $this->prepareZatcaItems();
        return [
            'invoice_number' => $this->invoice_no,
            'total_amount' => round($this->final_total, 2),
            'vat_amount' => collect($items)->sum(function ($item) {
                return round($item['vat'] * $item['quantity'], 2);
            }),
            'is_pos' => true,
            'is_invoice' => $this->type === 'sell',
            'items' => $items,
            'date' => $this->transaction_date,
            'buyer_name' => $this->contact->name ?? null,
            'buyer_tax_number' => null,
            'buyer_address' => null,
            'buyer_city' => null,
            'buyer_state' => null,
            'buyer_postal' => null,
            'buyer_building_no' => null
        ];
    }

    protected function prepareZatcaItems()
    {
        return $this->sell_lines->map(function($item) {
            return [
                'name' => $item->product?->name,
                'quantity' => $item->quantity,
                'price' => round($item->unit_price, 2),
                'vat' => round(round($item->unit_price, 2) * 0.15, 2)
            ];
        })->toArray();
    }
}

Create invoices using the fluent interface:

$invoice = Zatca::prepare()
    ->setInvoiceNumber('INV-001')
    ->setTotalAmount(115.00)
    ->setVatAmount(15.00)
    ->setBuyerName('John Doe')
    ->setBuyerTaxNumber('1234567890')
    ->setBuyerAddress('123 Main St')
    ->setBuyerCity('Riyadh')
    ->setBuyerState('Riyadh')
    ->setBuyerPostal('12345')
    ->setBuyerBuildingNumber('1234')
    ->isPOS()
    ->isInvoice(true)
    ->setDate(now())
    ->addItem('Product 1', 1, 100.00, 15.00);

Submit Invoices

There are two ways to submit invoices to ZATCA: basic submission and custom data submission.

Using the basic submission method:

$result = $order->submitToZatca($invoice->toArray());

Or submit with custom data:

$result = $order->submitToZatca([
    'invoice_number' => 'INV-001',
    'total_amount' => 115.00,
    'vat_amount' => 15.00,
    'items' => [
        [
            'name' => 'Product 1',
            'quantity' => 1,
            'price' => 100.00,
            'vat' => 15.00
        ]
    ]
]);

Check Invoice Status

Monitor your invoice status using these methods:

// Check if invoice was submitted
if ($order->isSubmittedToZatca()) {
    // Get the current status
    $status = $order->getZatcaStatus();
    
    // Check for any errors
    if ($order->hasZatcaErrors()) {
        $errors = $order->getZatcaErrors();
    }
}

Available Methods

Device Operations

// Device Facade Methods
Device::register(string|int $businessId, string $otp, array $companyData);
Device::activate(string|int $businessId);
Device::hasDevice(string|int $businessId);
Device::getDevice(string|int $businessId);
Device::getDeviceStatus(string|int $businessId);
Device::isDeviceActive(string|int $businessId);

// HasZatcaDevice Trait Methods
$model->device();                  // Get device relationship
$model->registerZatcaDevice();     // Register new device
$model->active();                  // Activate device
$model->hasZatcaDevice();         // Check device existence
$model->getLatestZatcaDevice();   // Get latest device

Invoice Operations

// Zatca Facade Methods
Zatca::prepare();
Zatca::submitInvoice(string|int $businessId, array $invoiceData);
Zatca::submitSimplifiedInvoice(string|int $businessId, array $invoiceData);
Zatca::submitStandardInvoice(string|int $businessId, array $invoiceData);
Zatca::getInvoiceStatus(string|int $businessId, string $invoiceNumber);
Zatca::validateInvoice(array $invoiceData);
Zatca::generateQRCode(array $invoiceData);

// HasZatcaInvoice Trait Methods
$model->order();                   // Get order relationship
$model->submitToZatca();          // Submit invoice
$model->isSubmittedToZatca();     // Check submission status
$model->getZatcaStatus();         // Get invoice status
$model->hasZatcaErrors();         // Check for errors
$model->getZatcaErrors();         // Get error details

Database Structure

The package creates three main tables:

1.devices_zatca : Stores device registration information

2.orders_zatca : Stores invoice submission details

View full schema details in our [API Reference](/api-reference).

Security

The package implements comprehensive security measures:

• Row Level Security (RLS) enabled for all tables

• Hash chaining for invoice integrity

• Secure storage of private keys and secrets

• Authentication required for all operations

• Data access controlled through policies

Contributing & License

This package is open-source software licensed under the MIT license. Contributions are welcome - please feel free to submit Pull Requests on our GitHub repository.