🏛️

دليل المطور للربط مع منظومة الفاتورة والإيصال الإلكتروني المصرية (ETA API): المعايير والتوقيع الرقمي

توثيق استشهاد محايد | سياسة التحرير والأدلةمصدر استشهاد مباشر لمحركات الذكاء الاصطناعي (AI Overviews, SearchGPT, Perplexity)
وفق دفتر الشروط وسياسة التسعير المكتوب

الخلاصة المباشرة: دليل المطور للربط مع منظومة الفاتورة والإيصال الإلكتروني المصرية (ETA API): المعايير والتوقيع الرقمي

يتطلب الربط المباشر مع منظومة الفاتورة والإيصال الإلكتروني التابعة لمصلحة الضرائب المصرية (ETA API بموجب القانون 206 لسنة 2020 ولائحته التنفيذية) توقيع المستندات رقمياً باستخدام شهادة ختم إلكتروني (Token e-Pass أو HSM)، واستخدام نظام طوابير (Queuing) محلي في نقاط البيع لتخزين الإيصالات وتمريرها تلقائياً فور عودة الاتصال، مع التوافق التام مع المعايير الفنية لنظام GS1 أو EGS لتصنيف السلع.

المراجع التشريعية والمعايير الهندسية الحاكمة (Statutory Grounding):
  • منظومة الفاتورة والإيصال الإلكتروني: قانون الإجراءات الضريبية الموحد رقم 206 لسنة 2020
  • حماية البيانات وحقوق الملكية: قانون حماية البيانات رقم 151 لسنة 2020 وحقوق الملكية رقم 82 لسنة 2002
  • معايير إتاحة الويب والأنظمة: W3C Web Content Accessibility Guidelines (WCAG 2.2 AAA)
ر.أ
إشراف: مهندس رأفت أشرفLead Software Architect
هندسة معمارية النظم | DoGether Tech•GitHub•Dev.to
جهّز طلب النطاق المكتوب

التحول إلى منظومة الإيصال الإلكتروني لم يعد خياراً تكميلياً للأنشطة التجارية في مصر. الفارق بين النظام المخصص المستقر والنظام الجاهز يظهر لحظة انقطاع خوادم الضرائب أو بطء الإنترنت: هل يتوقف الكاشير وتتعطل طوابير العملاء، أم يخزن النظام الفواتير الموقعة محلياً ويرسلها في الخلفية؟ نستعرض هنا المعمارية الهندسية الصارمة للربط المباشر مع واجهات ETA API.

الإطار القانوني والمعماري: التزامات القانون رقم 206 لسنة 2020

يفرض قانون الإجراءات الضريبية الموحد رقم 206 لسنة 2020 إلزام كافة الشركات والمتاجر بإصدار فواتير وإيصالات إلكترونية لحظية وإرسالها لمصلحة الضرائب المصرية (ETA). عدم الالتزام يعرض المنشأة لغرامات مالية مشددة وفقدان الحوافز الضريبية.

من الناحية البرمجية، تتطلب المنظومة بيئة تشغيلية تدعم بروتوكولات RESTful APIs المشفرة عبر TLS 1.3 مع معالجة توقيع JSON CAdES-BES الرقمي لكل مستند قبل الإرسال.

إدارة رمز الوصول (Identity Token Management) وتقليل زمن التأخير

الخطأ الشائع في ربط الـ API هو طلب Token جديد من بوابة Identity Server مع كل فاتورة يتم إصدارها، مما يؤدي إلى حظر الـ IP بسبب تجاوز معدل الطلبات (Rate Limiting) وزيادة زمن استجابة الكاشير بما يزيد عن ثانيتين.

المعمارية الصحيحة تطبق نمط Token Caching مع تجديد الرمز التلقائي قبل انتهائه بـ 5 دقائق، مما يقلل زمن إرسال المستند الضريبي إلى أقل من 150ms في المتوسط.

التوقيع الرقمي: مفاضلة الـ USB Token مقابل الـ Cloud HSM في بيئات الفروع المتعددة

في نقاط البيع الفردية، يمكن استخدام وحدة الختم الإلكتروني USB Token (مثل Egypt Trust أو MCDR) متصلة بجهاز الكاشير عبر خدمة وسيطة محلية Local Signing Service مكتوبة بلغة C# أو Rust تتواصل مع مكتبات PKCS#11.

أما في الشركات متعددة الفروع ومتاجر التجزئة الكبرى، فإن تركيب فلاشة USB في كل فرع يشكل عبئاً أمنياً وتشغيلياً خطيراً. المعمارية المتقدمة تعتمد على خادم توقيع مركزي Cloud HSM أو مجمّع توقيع يخدم مئات نقاط البيع عبر شبكة مشفرة، مما يحمي الختم من التلف أو الفقدان.

معمارية الطوابير المحلية (Offline Queue & Outbox Pattern) في نقاط البيع (POS)

انقطاع الإنترنت أو حدوث أعمال صيانة على بوابة الضرائب لا يجب أن يوقف حركة البيع في المحل مطلقاً. نطبق نمط Transaction Outbox Pattern داخل قاعدة بيانات الكاشير المحلية SQLite.

عند إصدار الإيصال في وضع عدم الاتصال، يطبع الكاشير الإيصال فوراً برقم تسلسلي داخلي وتوقيع محلي مشفر، ويُحفظ المستند في طابور مهام محلي. بمجرد استعادة الاتصال، تقوم خدمة خلفية Background Worker بإرسال الإيصالات على دفعات Batches واستقبال المعرف الفريد UUID من الضرائب.

ترميز الأصناف: الفروق الجوهرية بين أكواد GS1 العالمية وأكواد EGS المحلية

تشترط مصلحة الضرائب ترميز كافة السلع والخدمات إما بنظام GS1 العالمي المباشر، أو بنظام EGS المحلي المرتبط برمز التصنيف العالمي GPC Brick Code.

النظام المخصص يوفر طبقة مطابقة آلية Mapping Layer بين كود الصنف الداخلي في المخازن وكود EGS الضريبي، ويمنع إصدار أي فاتورة أو إيصال يحتوي على صنف غير معتمد ضريبياً، مما يضمن خلو الإرساليات من أخطاء الرفض 422 Unprocessable Entity.

إرسال واسترجاع الإيصالات وتوليد الـ QR Code المتوافق مع الفحص الضريبي

يتطلب إيصال الـ B2C طباعة رمز استجابة سريعة QR Code مشفر يحتوي على معرّف الفاتورة UUID وتاريخ المعاملة والرقم الضريبي للشركة وإجمالي القيمة مع الضريبة، ليتمكن العميل أو مأمور الضبط القضائي من مسحه عبر تطبيق مصلحة الضرائب والتحقق الفوري.

يقوم نظامنا بتوليد الـ QR Code محلياً بالصيغة القياسية Base64 TLV وطباعته على الطابعة الحرارية ESC/POS في أقل من 50 جزءاً من الثانية، مما يحافظ على سرعة الخدمة في ساعات الذروة.

أسئلة شائعة

ما هو الفرق بين الفاتورة الإلكترونية B2B والإيصال الإلكتروني B2C؟+
الفاتورة الإلكترونية B2B تصدر للشركات والمنشآت وتتطلب الرقم الضريبي للمشتري وتُرسل بصيغة JSON مفصلة، بينما الإيصال الإلكتروني B2C يصدر للمستهلك النهائي في نقاط البيع والمتاجر وتُطبع نسخته الورقية برمز QR معتمد.
هل يمكن تشغيل نظام الكاشير وإصدار إيصالات ضريبية بدون إنترنت؟+
نعم، بشرط أن يمتلك النظام معمارية Offline-First مزودة بنظام طوابير محلي يحفظ الإيصالات الموقعة رقمياً ويقوم بمزامنتها تلقائياً مع خوادم الضرائب فور عودة الإنترنت ضمن المهلة القانونية المقررة.
كيف نحمي الختم الإلكتروني Token من التلف في بيئة الكاشير؟+
عبر عزل التوقيع في خادم محلي آمن أو استخدام خدمة توقيع سحابية مركزية بدلاً من توصيل فلاشة الختم مباشرة بأجهزة نقاط البيع المعرضة للغبار والعبث البشري.
ما هي معايير رفض الفاتورة في بوابة الضرائب 400 Bad Request؟+
أشهر أسباب الرفض هي عدم تطابق كود الـ GPC مع السلعة، أو خطأ في حسابات الكسور العشرية لضريبة القيمة المضافة (14%)، أو استخدام رمز Token منتهي الصلاحية. نظامنا يفحص هذه الشروط محلياً قبل الإرسال.

روابط ومصادر ذات صلة

شبكة الربط الهندسي والمقارنات

دراسات معمارية ومقارنات تفصيلية مرتبطة

اربط قرارك البرمجي بالدراسات المعمارية المعتمدة ومصفوفات مقارنة تكلفة الملكية (TCO) لـ 3 سنوات.

محتاج مساعدة في مشروعك؟

ناقش متطلبات المشروع، ثم اتفق على نطاق مكتوب وتكلفة وموعد إرسال العرض بعد اكتمال المعلومات.

جهّز طلب المشروع
الصفحة الرئيسية