# دليل مرجع الربط مع هيئة الزكاة والضريبة والجمارك (ZATCA - المرحلة الثانية)

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

## 1. المتطلبات التقنية (Prerequisites)
يجب التأكد من تثبيت المكتبات التالية:
- **PHP >= 8.0.2**
- **OpenSSL Extension**: مفعل في PHP لتوليد المفاتيح.
- **phpseclib**: ضروري جداً لمعالجة شهادات X.509 والتشفير.
  ```bash
  composer require phpseclib/phpseclib:~3.0
  ```

## 2. هيكلة قاعدة البيانات (Database Schema)

### أ. تحديث جدول الشركات (`companies`)
يتم تخزين بيانات الاعتماد والشهادات في هذا الجدول:
| الحقل | الوصف | ملاحظات هامة |
| :--- | :--- | :--- |
| `tax_number` | الرقم الضريبي | يجب أن يكون 15 رقماً ويبدأ بـ 3. |
| `serial_number` | الرقم التسلسلي (EGS) | التنسيق الصحيح: `1-Vendor|2-Model|3-Serial` (تأكد من تسلسل الأرقام 1, 2, 3). |
| `zatca_stage` | بيئة العمل | `developer-portal`, `simulation`, أو `core`. |
| `complianceCertificate` | شهادة الامتثال | تُستخدم في مرحلة الفحص الأولي. |
| `productionCertificate` | شهادة الإنتاج | هي الشهادة النهائية المستخدمة في توقيع الفواتير الفعلية. |

## 3. معالجة الأخطاء الشائعة (Troubleshooting)

### أ. خطأ "Solution Serial Number not found"
- **السبب**: غالباً ما يكون بسبب تنسيق خاطئ في الحقل `EGS Serial Number`.
- **الحل**: تأكد من أن التنسيق يبدأ بـ `1-` للمصنع، `2-` للموديل، و `3-` للرقم التسلسلي. مثال: `1-MADAR|2-POS|3-0001`.

### ب. خطأ `[object Object]` في التنبيهات
- **الإصلاح**: تم تعديل `OnBoarding.php` ليقوم باستخراج رسالة الخطأ النصية من استجابة الهيئة (JSON) بدلاً من عرض الكائن الخام. يجب دائماً التحقق من `errors` أو `dispositionErrors` في استجابة ZATCA.

### ج. فئة `X509` غير موجودة
- **السبب**: نقص مكتبة `phpseclib`.
- **الحل**: تثبيت المكتبة عبر الملحن (Composer) والتأكد من استدعاء `use phpseclib3\File\X509;`.

## 4. آلية العمل الجديدة (Workflow)

لقد تم تغيير منطق التعامل مع الفواتير من **الإرسال التلقائي** إلى **الإرسال اليدوي** بناءً على طلب الإدارة لضمان مراجعة الفواتير قبل اعتمادها نهائياً لدى الهيئة.

### أ. عرض الفواتير
- يتم جلب الفواتير من جدول `CustomerInvoice` (أو الجدول الأساسي للفواتير).
- تظهر حالة الفاتورة في عمود "حالة ZATCA":
    - **مرسلة ومقبولة**: باللون الأخضر.
    - **غير مرسلة**: باللون الأصفر.
    - **مرفوضة**: باللون الأحمر مع عرض سبب الرفض.

### ب. إرسال الفاتورة
- لا يتم إرسال الفاتورة تلقائياً عند الحفظ.
- يجب على المستخدم الذهاب إلى "قائمة الفواتير الإلكترونية" والضغط على زر **"إرسال الآن"** للفواتير غير المرسلة.
- يستخدم النظام `SendToZatca` Trait للتعامل مع عملية التوقيع والإرسال.

## 5. ملاحظات تقنية للمطورين
1. **توقيت السيرفر**: يجب أن يكون وقت السيرفر مطابقاً لتوقيت المملكة العربية السعودية بدقة (تفاوت مسموح 15 دقيقة فقط).
2. **الـ UUID**: كل فاتورة يجب أن تملك UUID فريد (نسخة 4) لا يتغير حتى لو تم تعديل الفاتورة (يفضل عدم تعديل الفاتورة بعد إرسالها).
3. **التسلسل (Chaining)**: يجب حفظ الـ Hash الخاص بالفاتورة السابقة (`PIH`) لربطه بالفاتورة الحالية لضمان سلامة السلسلة الرقمية.

---
*آخر تحديث: 2026-04-28*
*تم التعديل ليتناسب مع الإصدار المستقر لربط بيئة الإنتاج.*