Download the PHP package meita/zatca without Composer
On this page you can find all versions of the php package meita/zatca. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package zatca
Short Description 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.
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package zatca
ZATCA e‑Invoice 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. إذا كنت تستخدم هذه الحزمة داخل مشروعك مباشرة، يمكنك إضافتها كاعتماد محلي باستخدام المسار:
ثم تشغيل:
الحزمة تمت تهيئتها بحيث يتم تحميل الأصناف ضمن مساحة الاسم Zatca\\.
الاستخدام السريع
1. التجهيز
قبل أن تتمكن من إرسال الفواتير، يجب الحصول على معرف ختم التشفير (CSID) والسر (secret) من بوابة المطورين التابعة لـ ZATCA. هذه العملية تشمل:
- إنشاء طلب توقيع شهادة (CSR) وتقديمه للحصول على CSID.
- إتمام الاختبارات عبر بيئة Integration Sandbox باستخدام Compliance CSID API.
- عند اجتياز الاختبارات، ستتلقى binarySecurityToken و secret تستخدمهما كبيانات مصادقة.
ضع ملف المفتاح الخاص (private_key.pem) والملف العام (certificate.crt) في مكان آمن بداخل مشروعك؛ حيث تستخدمهما الحزمة لتوقيع الفواتير.
2. تكوين العميل
3. إنشاء الفاتورة
4. إرسال الفاتورة القياسية
5. إرسال الفاتورة المبسطة
هيكل الأصناف الأساسية
1. Zatca\Invoice
يمثل الفاتورة ويوفر طرقًا لتوليد UUID وتكوين بيانات الفاتورة وتحويلها إلى XML. يعتمد على DOMDocument لتوليد ملف UBL بسيط. يمكنك تعديل طريقة toXml() لتضمين حقول إضافية حسب القاموس الرسمي.
2. Zatca\Utilities\Signer
يحتوي على وظائف لحساب hash للفاتورة باستخدام خوارزمية SHA‑256 وفقًا لمعيار C14N11، وتوقيع الـ hash باستخدام المفتاح الخاص عبر openssl_sign. يستخدم خوارزمية ECDSA (اختيارية: يمكن استخدام RSA إذا كانت متطلباتك مختلفة).
3. Zatca\Utilities\QrCodeGenerator
يبني تمثيلًا نصيًا (Base64) لرمز الإستجابة السريعة وفقًا لمواصفات TLV. يتضمن حقول: اسم البائع، الرقم الضريبي، الطابع الزمني، إجمالى الفاتورة، إجمالى الضريبة، Hash الفاتورة، التوقيع الرقمي، والمفتاح العام. لا يتضمن إنشاء صورة QR؛ بل يُرجع سلسلة Base64 يمكن تحويلها لصورة عبر مكتبات خارجية (مثل endroid/qr-code).
4. Zatca\ZatcaClient
يُعد الواجهة الرئيسية للتعامل مع 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، والدمج فى العميل). لتشغيل الاختبارات:
-
تأكد من تثبيت اعتماديات التطوير (تشمل PHPUnit) باستخدام Composer:
- ثم قم بتشغيل الأمر التالي من جذر المشروع:
سترى ملخصًا بالاختبارات التى تم تنفيذها ونتائجها. يمكنك استخدام هذه الاختبارات كنقطة انطلاق لإضافة اختبارات أخرى حسب احتياجات مشروعك.
ملاحظات أمنية
- يجب تخزين المفتاح الخاص والـ secret فى أماكن آمنة وبصورة مشفرة وعدم مشاركتهما.
- لا تحتفظ بالسر فى مستودع الكود؛ استخدم متغيرات بيئة أو خدمات إدارة الأسرار.
- تأكد من استخدام اتصال
HTTPSعند إرسال الفواتير لحماية البيانات.
ترخيص
تم نشر هذه الحزمة تحت رخصة MIT. يمكنك استخدامها وتعديلها بحرية وفق شروط الرخصة.
المساهمة
مرحبًا بجميع المساهمات! إذا وجدت مشكلة أو ترغب فى إضافة ميزة جديدة، الرجاء فتح تذكرة أو إرسال طلب دمج (Pull Request).
