ابدأ من متطلبات مصلحة الضرائب الحالية وSDK الرسمي، ثم افصل بين إعداد بيانات الشركة والأكواد والتوقيع وبين منطق ERP الذي ينشئ المستند ويرسله ويتابع حالته ويعالج الرفض أو الأخطاء.
ربط ERP بالفاتورة الإلكترونية في مصر ليس مجرد استدعاء API بعد حفظ الفاتورة. قبل الإرسال يجب أن تكون بيانات الشركة والعملاء والأصناف والضرائب والأكواد وبنية المستند متوافقة مع المتطلبات الحالية، ثم يحتاج النظام متابعة نتيجة الإرسال وحالة المستند.
مصلحة الضرائب المصرية توفر أدلة للممولين وSDK وواجهات API للتكامل بين أنظمة ERP ومنظومة الفاتورة الإلكترونية. لهذا يجب أن يبدأ أي مشروع تكامل من الوثائق الرسمية الحالية، وليس من كود قديم أو شرح تجاري غير محدث.
كيف تنظر للتكامل كدورة كاملة؟
التكامل يبدأ داخل ERP عندما ينشئ المستخدم مستندًا صحيحًا، ثم تتحول البيانات إلى الصيغة المطلوبة، تمر بالتحقق والتوقيع أو متطلبات الهوية المناسبة، تُرسل عبر الواجهة الرسمية، ثم يحفظ النظام الرد والحالة والمعرفات المرتبطة بالمستند.
إذا تعاملت مع العملية كزر إرسال فقط ستظهر مشاكل في التكرار وإعادة المحاولة وفقدان حالة المستند.
تجهيز بيانات البائع والمشتري والأصناف والأكواد والضرائب والقيم المطلوبة.
فحص الحقول والحسابات والقواعد قبل إرسال الطلب.
تنفيذ متطلبات المصادقة أو التوقيع طبقًا للتوثيق الرسمي والحالة.
إرسال المستند عبر واجهة التكامل المناسبة.
حفظ IDs والحالة والردود والتنبيهات وربطها بالفاتورة داخل ERP.
جودة Master Data أهم من كود الـAPI
نسبة كبيرة من أخطاء التكامل تبدأ قبل API: كود صنف غير صحيح، بيانات عميل ناقصة، وحدة قياس مختلفة أو ضريبة غير مطابقة للسياسة.
لذلك يجب تحديد مصدر الحقيقة لكل بيانات أساسية، ومن يملك صلاحية تعديلها، وما الذي يحدث للفاتورة القديمة إذا تغيرت بيانات الصنف بعد إصدارها.
- بيانات الشركة والفروع المستخدمة في المستندات.
- أكواد الأصناف أو الخدمات ونظام التكويد المعتمد للحالة.
- وحدات القياس والضرائب والقيم المالية.
- بيانات العميل أو الجهة المستلمة المطلوبة لنوع المستند.
- سياسة التقريب والحسابات قبل إنشاء Payload.
- حفظ Snapshot من البيانات المستخدمة في المستند بدل الاعتماد على قيم متغيرة لاحقًا.
ما الذي يجب أن يفعله طبقة التكامل داخل ERP؟
الطبقة الجيدة تعزل منطق الضرائب والاتصال الخارجي عن شاشة الفاتورة نفسها. بذلك يمكن اختبارها ومراقبتها وتحديثها عندما تتغير الواجهة أو القواعد دون إعادة بناء دورة المبيعات بالكامل.
كما يجب أن تكون Idempotent قدر الإمكان: إعادة المحاولة بعد Timeout لا يجب أن تنشئ مستندًا مكررًا دون تحقق.
إدارة بيانات المصادقة والـtokens طبقًا للواجهة الرسمية مع عدم كشف الأسرار للمستخدمين.
تحويل مستند ERP إلى بنية البيانات المطلوبة بصورة قابلة للاختبار.
منع الإرسال عندما توجد حقول أو حسابات غير صحيحة يمكن اكتشافها محليًا.
تحديث حالة المستند داخل ERP وحفظ الردود والأخطاء ومعرفات المنظومة.
معالجة الرفض والأخطاء بدون فوضى
ليس كل فشل يعني أن المستخدم يجب أن يعيد إنشاء الفاتورة. بعض الأخطاء قد تكون Validation واضحة، وبعضها اتصال مؤقت، وبعضها يحتاج تصحيح Master Data أو مستند جديد حسب الحالة.
صمم شاشة تشغيل أو Log توضح آخر محاولة، نوع الخطأ، الرسالة المرجعية، وهل يمكن إعادة المحاولة بأمان.
| نوع المشكلة | التصرف داخل النظام | ما الذي لا يجب فعله |
|---|---|---|
| Validation محلي | إيقاف الإرسال وإظهار الحقل المطلوب تصحيحه | إرسال Payload معروف أنه غير صحيح |
| Timeout / Network | التحقق من النتيجة قبل إعادة المحاولة | إرسال نسخة جديدة فورًا بدون فحص |
| رفض من المنظومة | حفظ الكود والرسالة وتوجيه المستخدم للإجراء المناسب | حذف أثر المحاولة أو تعديل التاريخ بلا سجل |
| تغيير قواعد أو API | اختبار تحديث التكامل على بيئة منفصلة | تعديل Production مباشرة بدون Regression Test |
خطة اختبار قبل تشغيل الفواتير الفعلية
اختبار فاتورة واحدة ناجحة لا يكفي. تحتاج حالات حدودية واستثناءات تمثل التشغيل الحقيقي، مع التحقق من أن ERP نفسه يحتفظ بحالة واضحة لكل مستند.
- مستند بسيط بعميل وأصناف صحيحة.
- أكثر من معدل أو نوع ضريبة إذا كان ذلك جزءًا من التشغيل.
- خصومات أو قيم صفرية أو كسور حسب الحالات المسموح بها.
- خطأ متعمد في كود أو حقل للتأكد أن الرسالة مفهومة.
- انقطاع اتصال أثناء الإرسال وإعادة المحاولة.
- مستخدمان يحاولان إرسال نفس المستند أو تحديثه في وقت متقارب.
- مراجعة سجلات النظام وعدم ظهور أسرار أو بيانات حساسة في Logs غير محمية.
المراجع الرسمية التي يجب أن تبقى جزءًا من المشروع
متطلبات التكامل الضريبي قابلة للتحديث. لذلك يجب أن تكون الوثائق الرسمية مرجعًا مستمرًا أثناء التحليل والتنفيذ والاختبار، وليس رابطًا يُراجع مرة واحدة في بداية المشروع.
احتفظ في وثائق المشروع بإصدار أو تاريخ المرجع الذي بُني عليه التكامل، وراجع Release Notes أو الأدلة الرسمية قبل تغييرات Production المهمة.
مراجع وروابط مرتبطة
أسئلة شائعة
هل الفاتورة الإلكترونية تحتاج ERP معين؟
لا يعتمد المفهوم على اسم منتج واحد؛ المهم أن النظام يستطيع إنشاء البيانات المطلوبة والتكامل وفق الوثائق الرسمية الحالية ومتطلبات الممول.
هل يكفي إرسال الفاتورة عبر API؟
لا. يجب أيضًا إدارة البيانات والأكواد والمصادقة أو التوقيع والحالة والأخطاء وإعادة المحاولة وسجل العملية.
كيف أمنع إرسال نفس الفاتورة مرتين؟
باستخدام معرفات داخلية فريدة وحفظ نتائج المحاولات والتحقق من الحالة قبل إعادة الإرسال وتصميم Idempotency مناسب.
هل يجب اختبار التكامل قبل Production؟
نعم. التكامل المالي يحتاج بيئة واختبارات تمثل الحالات الناجحة والفاشلة والانقطاع والتكرار قبل التشغيل الفعلي.
ما المرجع عند تغير متطلبات المنظومة؟
موقع مصلحة الضرائب المصرية والـSDK والوثائق الرسمية الحالية هي المرجع، ويجب مراجعتها قبل اعتماد تغييرات التكامل.
