ربط أودو بمنظومة الفاتورة الإلكترونية: قائمة مراجعة قبل أول إرسال

Read this article in English

معظم حالات فشل تشغيل ربط أودو بمنظومة الفاتورة الإلكترونية لا يسببها الكود. يسببها كود EGS ناقص، أو توكن توقيع موصول بالجهاز الخطأ، أو Client Secret مُولَّد لبيئة الاختبار ومنسوخ في الإنتاج. هذه القائمة تجمع كل ما يجب أن يكون صحيحاً قبل خروج أول فاتورة حقيقية من أودو، بالترتيب الذي يجب أن تنفذه به.

تنطبق على أودو 17 و18 و19، النسخة المجتمعية (Community) أو Enterprise، وعلى أي موديول تكامل بما فيه ما تبنيه بنفسك. وحيثما يمكن أن تتغير قواعد المصلحة نقول «راجع إرشادات المصلحة الحالية» بدلاً من التخمين.

نظرة عامة: ستة أشياء يجب أن توجد

إذا كان أي صف فارغاً توقف واملأه. لن يعمل أي شيء آخر.

الخطوة 1: اضبط ملف الممول أولاً

قبل لمس أودو، افتح ملف شركتك على بوابة الفاتورة الإلكترونية وتأكد من:

• رقم التسجيل الضريبي يطابق تماماً ما ستضعه على شركة أودو.
• الفروع. كل شركة أو مخزن في أودو يُصدر فواتير يجب أن يقابله فرع مسجل في الملف برقم فرع. حقل branchID وعنوان المُصدر يُتحقق منهما مقابل هذا.
• أكواد النشاط. حقل activityCode في كل مستند يجب أن يكون أحد أكواد النشاط الضريبي المسجلة لك. اختر الكود الرئيسي للفواتير ودوّنه.
• حقول العنوان. الدولة يجب أن تكون EG، ويجب ملء المحافظة والمدينة والشارع ورقم المبنى. حقل «الشارع» الوحيد في أودو لا يكفي غالباً؛ قد تحتاج حقلاً مخصصاً لرقم المبنى.

الخطوة 2: سجّل الـ ERP واحصل على Client ID وClient Secret

تتعرف المصلحة على تكاملك عبر Client ID وClient Secret يُنشآن تحت قسم ERP في ملف الممول. ملاحظات توفر ساعات:

1. 1توجد بيئتان منفصلتان. بيئة الاختبار preprod تستخدم https://id.preprod.eta.gov.eg للهوية وhttps://api.preprod.invoicing.eta.gov.eg للـ API؛ والإنتاج يستخدم عناوين الإنتاج. بيانات اعتماد بيئة لا تعمل في الأخرى.
2. 2السر يظهر مرة واحدة فقط. خزّنه في معاملات النظام في أودو أو في مدير أسرار، لا في رسالة واتساب.
3. 3نقطة التوكن هي /connect/token على خدمة الهوية بنوع منح client credentials. التوكن ينتهي؛ يجب أن يجدده التكامل لا أن يخزن واحداً للأبد.
4. 4كل تسجيل ERP يمكن حصره في فروع معينة. إذا ظهر 403 IncorrectSubmitter فهذا أول مكان تراجعه.

أنشئ تسجيل ERP واحداً لكل قاعدة بيانات أودو، لا لكل مستخدم.

الخطوة 3: رتّب التوقيع (الختم الإلكتروني)

كل مستند يجب أن يحمل توقيع CAdES-BES بشهادة صادرة من مقدم خدمة مصري مرخّص. المفتاح الخاص موجود على توكن USB أو HSM، وهذا يعني:

• أودو لا يستطيع التوقيع ببايثون فقط على خادم سحابي. تحتاج خدمة توقيع صغيرة تعمل على جهاز موصول به التوكن فعلياً (جهاز ويندوز في المكتب، أو HSM يتيحه لك مقدم الخدمة).
• خدمة التوقيع يجب أن توقّع محتوى المستند المعياري بالضبط مع استبعاد قسم signatures. إذا أعاد التكامل تسلسل الـ JSON بعد التوقيع ينكسر التوقيع.
• راجع تاريخ انتهاء الشهادة وسجّله في تقويمك. الشهادة المنتهية تنتج مستندات Invalid دون تحذير واضح.

إذا قال الموديول إنه «يوقّع الفواتير» فاسأل أين التوكن وأي خدمة تخاطبه.

الخطوة 4: أكواد الأصناف — GS1 أو EGS لكل منتج

هذه الخطوة هي الأكثر تسبباً في تأخير التشغيل. كل سطر فاتورة يحتاج codeType وitemCode.

نصائح عملية:

1. 1صدّر منتجاتك النشطة من أودو وقرر لكل منتج: GS1 أم EGS.
2. 2لأكواد EGS، اربط كل كود بتصنيف GPC، وسجّله على البوابة، وانتظر الاعتماد. افعل هذا قبل التشغيل بأسابيع.
3. 3خزّن نوع الكود والكود على نموذج المنتج في أودو واجعلهما إلزاميين للمنتجات القابلة للبيع.
4. 4شغّل تقريراً بالمنتجات بلا أكواد قبل كل دفعة إرسال.

لا ترسل فاتورة حقيقية بكود ما زال Pending. ستعود Invalid.

الخطوة 5: أكواد وحدات القياس

حقل unitType في كل سطر يجب أن يأتي من جدول أكواد الوحدات لدى المصلحة (مثل EA للقطعة وKGM للكيلوجرام؛ راجع قائمة أكواد المصلحة الحالية للقيم الدقيقة). أسماء وحدات القياس في أودو نص حر، لذلك تحتاج ربطاً:

• أضف حقل «كود وحدة المصلحة» على uom.uom.
• اربط كل وحدة مستخدمة على المنتجات القابلة للبيع.
• تعامل مع الوحدة غير المربوطة كخطأ يمنع الإرسال لا كتحذير.

الخطوة 6: بيانات العملاء

قسم المستلم يعتمد على نوع العميل:

• B (شركة): يحتاج رقم التسجيل الضريبي للعميل واسمه.
• P (شخص طبيعي): الرقم القومي والاسم والعنوان اختيارية تحت الحد القانوني وإلزامية فوقه. الحد يتغير؛ راجع إرشادات المصلحة الحالية.
• F (أجنبي): يحتاج معرّفاً ودولة.

في أودو أضف «نوع المستلم» على جهة الاتصال، واجعل رقم التسجيل إلزامياً للشركات، وتحقق من صيغة الرقم القومي (14 رقماً) للأشخاص. طبّق ذلك عند ترحيل الفاتورة حتى يكتشف المحاسبون المشكلة قبل الإرسال لا بعده.

الخطوة 7: اختبر في preprod أولاً

لا تختبر على الإنتاج أبداً. بيئة preprod لدى المصلحة تحاكي الإنتاج:

1. 1ثبّت شهادة الجذر (Root CA) لبيئة preprod على الجهاز الذي يستدعي الـ API (الأسئلة الشائعة في SDK تشرح ذلك وتحذر من تثبيتها على أجهزة الإنتاج).
2. 2سجّل ERP منفصلاً في ملف preprod للحصول على بيانات اعتماد الاختبار.
3. 3في أودو وجّه التكامل إلى عناوين preprod واستخدم نسخة من قاعدة البيانات.
4. 4أرسل مجموعة صغيرة من الفواتير تغطي: عميل شركة برقم تسجيل؛ عميل شخص طبيعي تحت الحد؛ سطر بخصم نسبة مئوية وسعر وحدة غير مقرّب؛ سطر بوحدة قياس غير افتراضية؛ إشعار خصم يشير إلى الفاتورة.
5. 5تابع الحالة حتى تصبح كلها Valid. الرد 202 ليس نجاحاً؛ راجع مقالنا عن المعنى الحقيقي للحالة 202.
6. 6اكسر فاتورة واحدة عمداً (كود صنف خاطئ) وتأكد أن الخطأ يظهر في أودو بكلمات يفهمها الإنسان.

فقط عندما تعود السيناريوهات الستة Valid انتقل إلى بيانات اعتماد الإنتاج.

الخطوة 8: قرر من يضغط الزر

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

• رحّل في أودو كالمعتاد.
• أرسل إلى المصلحة عن قصد، بواسطة شخص محدد، على دفعات، بعد المراجعة.
• احصر صلاحية الإرسال في مجموعة أودو مخصصة حتى يمتلكها المحاسبون فقط. (مقالنا عن صلاحيات أودو يشرح الطريقة.)

قائمة الفحص قبل الإقلاع (انسخها)

• رقم التسجيل ورقم الفرع وكود النشاط والعنوان الكامل مدخلة في أودو ومطابقة لملف المصلحة.
• بيانات اعتماد preprod مختبَرة؛ بيانات الإنتاج مخزنة بأمان ولم تُستخدم بعد.
• خدمة التوقيع متاحة من أودو؛ التوكن موصول؛ تاريخ انتهاء الشهادة مسجل.
• 100% من المنتجات القابلة للبيع لها كود GS1 أو EGS معتمد.
• 100% من وحدات القياس على تلك المنتجات مربوطة بأكواد المصلحة.
• نماذج العملاء تطلب رقم التسجيل للشركات والرقم القومي فوق الحد.
• السيناريوهات الستة في preprod عادت Valid.
• نص الخطأ من validationSteps يظهر على الفاتورة.
• صلاحية الإرسال محصورة في مجموعة مستخدمين محددة.
• شخص مسؤول عن الفحص اليومي: «هل يوجد ما زال Submitted أو Invalid؟».

أسئلة شائعة

هل أحتاج أودو Enterprise للربط بمصلحة الضرائب؟

لا. واجهة المصلحة هي HTTPS/JSON عادية. النسختان Community وEnterprise يمكنهما التكامل بشرط أن يدعم الموديول نسختك وأن تتوفر لديك خدمة توقيع للتوكن أو الـ HSM.

هل يستطيع أودو توقيع الفاتورة بنفسه؟

ليس وحده. المفتاح الخاص على توكن عتادي أو HSM. تحتاج مكوّن توقيع يصل إلى هذا العتاد؛ يرسل أودو المستند إليه ويستلم التوقيع.

ما الفرق بين أكواد GS1 وEGS؟

أكواد GS1 باركودات عالمية تشتريها من GS1 وتقبلها المصلحة دون اعتماد. أكواد EGS مجانية تسجلها على بوابة المصلحة تحت رقمك الضريبي ويجب أن تعتمدها المصلحة قبل الاستخدام.

كم يستغرق اعتماد كود EGS؟

إرشادات GS1 مصر تذكر حتى 15 يوماً. التوقيت قد يتغير؛ راجع إرشادات المصلحة الحالية وسجّل الأكواد قبل التشغيل بوقت كافٍ.