PHPackages                             meita/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. [Payment Processing](/categories/payments)
4. /
5. meita/zatca

ActiveLibrary[Payment Processing](/categories/payments)

meita/zatca
===========

PHP package to prepare, sign and send electronic invoices compliant with the ZATCA e‑invoicing regulations. It can be integrated into any PHP or Laravel project.

v1.0.0(5mo ago)09MITPHPPHP >=7.4

Since Dec 11Pushed 5mo agoCompare

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

READMEChangelogDependencies (1)Versions (7)Used By (0)

ZATCA e‑Invoice PHP Package
===========================

[](#zatca-einvoice-php-package)

هذا الحزمة مكتوبة بلغة PHP وتهدف إلى تسهيل عملية **إعداد، توقيع وإرسال الفواتير الإلكترونية** وفقًا لمواصفات هيئة الزكاة والضريبة والجمارك (ZATCA) في المملكة العربية السعودية. يمكن استخدامها مع أي مشروع PHP، بما فى ذلك إطار عمل Laravel، وتوفر الأدوات اللازمة لتوليد الفاتورة بصيغة XML، حساب البصمة الرقمية (hash)، توقيعها باستخدام مفاتيح ECDSA، توليد رمز الإستجابة السريعة (QR) وترميزها، وأخيرًا إرسالها إلى بوابة **فاتورة** من خلال واجهات البرمجة الخاصة بمرحلة التصفية (Clearance) أو التبليغ (Reporting).

المزايا الرئيسية
----------------

[](#المزايا-الرئيسية)

- إنشاء نموذج فاتورة إلكترونية (بصيغة XML) يتوافق مع قاموس البيانات ومعايير ZATCA.
- توليد **UUID**، وربط الفواتير المتتالية عبر حقل `previousInvoiceHash`.
- حساب تجزئة الفاتورة باستخدام خوارزمية SHA‑256 وتوقيعها باستخدام مفتاح خاص من نوع ECDSA.
- توليد **رمز الإستجابة السريعة (QR)** وفق تنسيق TLV وترميزه Base64.
- إرسال الفواتير إلى واجهات البرمجة الخاصة ببوابة ZATCA (التصفية أو التبليغ) عبر بروتوكول HTTP Basic Auth.
- إمكانية ضبط عنوان الخادم (بيئة الإنتاج أو sandbox) وبيانات الاعتماد (CSID و secret).
- مهيأة للعمل ضمن أي تطبيق Laravel بفضل autoload بـ PSR‑4.

> **تنويه**: هذه الحزمة للأغراض التعليمية وتعرض الخطوات الأساسية المطلوبة للتكامل مع ZATCA. يجب مراجعة المواصفات الرسمية ودمجها فى المشروع الفعلي، مع التأكد من توفير الأمن المناسب وإدارة المفاتيح السرية.

التركيب
-------

[](#التركيب)

يفضل تثبيت الحزمة عبر Composer. إذا كنت تستخدم هذه الحزمة داخل مشروعك مباشرة، يمكنك إضافتها كاعتماد محلي باستخدام المسار:

```
{
    "repositories": [
        {
            "type": "path",
            "url": "path/to/zatca-einvoice"
        }
    ],
    "require": {
        "meita/zatca": "*"
    }
}
```

ثم تشغيل:

```
composer require meita/zatca
```

الحزمة تمت تهيئتها بحيث يتم تحميل الأصناف ضمن مساحة الاسم `Zatca\\`.

الاستخدام السريع
----------------

[](#الاستخدام-السريع)

### 1. التجهيز

[](#1-التجهيز)

قبل أن تتمكن من إرسال الفواتير، يجب الحصول على **معرف ختم التشفير (CSID)** والسر (**secret**) من بوابة المطورين التابعة لـ ZATCA. هذه العملية تشمل:

1. إنشاء طلب توقيع شهادة (CSR) وتقديمه للحصول على **CSID**.
2. إتمام الاختبارات عبر بيئة **Integration Sandbox** باستخدام **Compliance CSID API**.
3. عند اجتياز الاختبارات، ستتلقى **binarySecurityToken** و **secret** تستخدمهما كبيانات مصادقة.

ضع ملف المفتاح الخاص (`private_key.pem`) والملف العام (`certificate.crt`) في مكان آمن بداخل مشروعك؛ حيث تستخدمهما الحزمة لتوقيع الفواتير.

### 2. تكوين العميل

[](#2-تكوين-العميل)

```
use Zatca\ZatcaClient;
use Zatca\Invoice;

$client = new ZatcaClient([
    // عنوان واجهة البرمجة؛ استخدم sandbox للتجارب أو production للإرسال الفعلي
    'base_url' => 'https://sandbox.zatca.gov.sa/e-invoicing/core/v2',
    // معرف الختم الصادر (CSID)
    'client_id' => 'YOUR_CSID_HERE',
    // السر المرتبط بالـ CSID
    'secret'    => 'YOUR_SECRET_HERE',
    // المسار إلى المفتاح الخاص لتوقيع الفاتورة
    'private_key_path' => __DIR__ . '/keys/private_key.pem',
    // المسار إلى الشهادة العامة (اختياري في هذه النسخة)
    'certificate_path' => __DIR__ . '/keys/certificate.crt',
]);
```

### 3. إنشاء الفاتورة

[](#3-إنشاء-الفاتورة)

```
// البيانات المطلوبة للفاتورة، ويمكنك تخصيصها حسب احتياجاتك
$data = [
    'uuid'          => Invoice::generateUuid(),
    'issue_date'    => date('c'), // ISO 8601 timestamp
    'seller_name'   => 'شركة المثال للتجارة',
    'seller_vat'    => '123456789012345',
    'invoice_total' => 115.00,
    'vat_total'     => 15.00,
    // في حال كانت هذه ليست أول فاتورة، أدخل Hash الفاتورة السابقة
    'previous_hash' => null,
    // عناصر أخرى يمكن إضافتها فى ملف XML
    'items' => [
        [
            'name' => 'منتج 1',
            'quantity' => 1,
            'price' => 100.00,
        ],
    ],
];

$invoice = new Invoice($data);

// يمكن تعديل العناصر بعد الإنشاء
$invoice->setPreviousInvoiceHash('previousHashValue');
```

### 4. إرسال الفاتورة القياسية

[](#4-إرسال-الفاتورة-القياسية)

```
// هذه الطريقة تقوم تلقائياً بإنشاء XML، احتساب hash وتوقيعه، بناء رمز QR، ثم إرسالها عبر واجهة التصفية
$response = $client->sendStandardInvoice($invoice);

if ($response['status'] === 'success') {
    // احفظ الفاتورة المختومة (response['invoice']) كما هو موضح فى مواصفات ZATCA
    file_put_contents('cleared_invoice.xml', base64_decode($response['invoice']));
} else {
    // عالج الأخطاء بناءً على رسالة الرفض أو التحذيرات
    var_dump($response['errors']);
}
```

### 5. إرسال الفاتورة المبسطة

[](#5-إرسال-الفاتورة-المبسطة)

```
$response = $client->sendSimplifiedInvoice($invoice);
// فى هذا النموذج، يجب أن تحتوى الفاتورة على الختم والرمز قبل الإرسال
```

هيكل الأصناف الأساسية
---------------------

[](#هيكل-الأصناف-الأساسية)

### 1. `Zatca\Invoice`

[](#1-zatcainvoice)

يمثل الفاتورة ويوفر طرقًا لتوليد **UUID** وتكوين بيانات الفاتورة وتحويلها إلى XML. يعتمد على `DOMDocument` لتوليد ملف UBL بسيط. يمكنك تعديل طريقة `toXml()` لتضمين حقول إضافية حسب القاموس الرسمي.

### 2. `Zatca\Utilities\Signer`

[](#2-zatcautilitiessigner)

يحتوي على وظائف لحساب **hash** للفاتورة باستخدام خوارزمية SHA‑256 وفقًا لمعيار C14N11، وتوقيع الـ hash باستخدام المفتاح الخاص عبر `openssl_sign`. يستخدم خوارزمية ECDSA (اختيارية: يمكن استخدام RSA إذا كانت متطلباتك مختلفة).

### 3. `Zatca\Utilities\QrCodeGenerator`

[](#3-zatcautilitiesqrcodegenerator)

يبني تمثيلًا نصيًا (Base64) لرمز الإستجابة السريعة وفقًا لمواصفات TLV. يتضمن حقول: اسم البائع، الرقم الضريبي، الطابع الزمني، إجمالى الفاتورة، إجمالى الضريبة، Hash الفاتورة، التوقيع الرقمي، والمفتاح العام. لا يتضمن إنشاء صورة QR؛ بل يُرجع سلسلة Base64 يمكن تحويلها لصورة عبر مكتبات خارجية (مثل `endroid/qr-code`).

### 4. `Zatca\ZatcaClient`

[](#4-zatcazatcaclient)

يُعد الواجهة الرئيسية للتعامل مع ZATCA. يوفر الطرق:

- **`sendStandardInvoice(Invoice $invoice): array`** – يرسل الفاتورة القياسية للتصفية ويُرجع مصفوفة تحوى الحالة (`success` أو `error`) والفاتورة المختمة أو الأخطاء.
- **`sendSimplifiedInvoice(Invoice $invoice): array`** – يرسل الفاتورة المبسطة للتبليغ. يجب أن يكون الـ invoice قد تم ختمه وتضمين QR.
- **`prepareSignedInvoice(Invoice $invoice): array`** – لإنشاء ملف XML، حساب الـhash، التوقيع، توليد QR وإرجاع جميع القيم الضرورية دون إرسالها؛ يمكن استخدامه فى سيناريوهات التبليغ.

تشغيل الاختبارات
----------------

[](#تشغيل-الاختبارات)

يحتوي هذا المشروع على مجموعة من اختبارات **PHPUnit** للتأكد من صحة وحدات الكود الخاصة بالحزمة (توليد الـ UUID، بناء ملف XML، حساب الـ hash، التوقيع، إنشاء QR، والدمج فى العميل). لتشغيل الاختبارات:

1. تأكد من تثبيت اعتماديات التطوير (تشمل PHPUnit) باستخدام Composer:

    ```
    composer install --dev
    ```
2. ثم قم بتشغيل الأمر التالي من جذر المشروع:

    ```
    vendor/bin/phpunit
    ```

سترى ملخصًا بالاختبارات التى تم تنفيذها ونتائجها. يمكنك استخدام هذه الاختبارات كنقطة انطلاق لإضافة اختبارات أخرى حسب احتياجات مشروعك.

ملاحظات أمنية
-------------

[](#ملاحظات-أمنية)

- يجب تخزين **المفتاح الخاص** والـ **secret** فى أماكن آمنة وبصورة مشفرة وعدم مشاركتهما.
- لا تحتفظ بالسر فى مستودع الكود؛ استخدم متغيرات بيئة أو خدمات إدارة الأسرار.
- تأكد من استخدام اتصال `HTTPS` عند إرسال الفواتير لحماية البيانات.

ترخيص
-----

[](#ترخيص)

تم نشر هذه الحزمة تحت رخصة **MIT**. يمكنك استخدامها وتعديلها بحرية وفق شروط الرخصة.

المساهمة
--------

[](#المساهمة)

مرحبًا بجميع المساهمات! إذا وجدت مشكلة أو ترغب فى إضافة ميزة جديدة، الرجاء فتح تذكرة أو إرسال طلب دمج (Pull Request).

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance72

Regular maintenance activity

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 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

6

Last Release

157d ago

Major Versions

v0.2.2 → v1.0.02025-12-13

### Community

Maintainers

![](https://www.gravatar.com/avatar/5915383ac10e7c148c23e142195199c8e7909acc2cda2003c26e688090956014?d=identicon)[EngMEita](/maintainers/EngMEita)

---

Top Contributors

[![EngMEita](https://avatars.githubusercontent.com/u/11925529?v=4)](https://github.com/EngMEita "EngMEita (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/meita-zatca/health.svg)

```
[![Health](https://phpackages.com/badges/meita-zatca/health.svg)](https://phpackages.com/packages/meita-zatca)
```

###  Alternatives

[omnipay/paypal

PayPal gateway for Omnipay payment processing library

3156.8M53](/packages/omnipay-paypal)[eduardokum/laravel-boleto

Biblioteca com boletos para o laravel

626351.9k2](/packages/eduardokum-laravel-boleto)[tbbc/money-bundle

This is a Symfony bundle that integrates moneyphp/money library (Fowler pattern): https://github.com/moneyphp/money.

1961.9M](/packages/tbbc-money-bundle)[2checkout/2checkout-php

2Checkout PHP Library

83740.3k2](/packages/2checkout-2checkout-php)[smhg/sepa-qr-data

Generate QR code data for SEPA payments

61717.2k5](/packages/smhg-sepa-qr-data)[omnipay/dummy

Dummy driver for the Omnipay payment processing library

271.2M33](/packages/omnipay-dummy)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)