اختبار فعلي · 21 نوفمبر 2026
أرسلنا عشر فواتير مبسطة للمرحلة الثانية إلى البيئة التجريبية لمنصة فاتورة. عادت الثلاث الأولى بحالة WARNING بسبب تفصيلة واحدة في وقت رمز QR، وبعد إصلاح سطر واحد عادت الفواتير السبع التالية كلها PASS.
إليك معنى PASS وWARNING وERROR عملياً، ونص التحذير الذي أعادته الهيئة، وسببه، وقائمة تحقق ليجتاز نظام الكاشير أو ERP من المرة الأولى. على المنشآت السعودية في الموجة 25 الربط مع فاتورة بحلول 1 فبراير 2027 (إعلان الهيئة).

في آيفينيكس نبني البرمجيات للمنشآت السعودية والخليجية، وقد بنينا للتو تجربة حية لفاتورة المرحلة الثانية. وقبل نشرها اختبرنا محركها على واجهة الامتثال الخاصة بهيئة الزكاة والضريبة والجمارك نفسها. هذا سجل مباشر لذلك الاختبار، مكتوب للمطورين وأصحاب المنتجات وفرق المالية الذين يستعدون للربط.
ماذا اختبرنا بالضبط؟
استخدمنا البيئة التجريبية في بوابة المطورين لدى الهيئة، وهي البيئة التي توفرها الهيئة ليجرب المطورون الربط قبل التعامل مع بيانات حقيقية. وكانت الخطوات ثلاثاً:
- التسجيل: أنشأنا مفتاح secp256k1 وطلب توقيع شهادة (CSR) لمتجر تجريبي وهمي، ثم طلبنا شهادة من نقطة الامتثال باستخدام رمز OTP التجريبي المنشور. ردّت البيئة بحالة
ISSUEDوأعادت شهادة وكلمة سر للواجهة. - الفواتير: بنى محركنا فواتير ضريبية مبسطة بصيغة UBL 2.1 بأسماء أصناف عربية وإنجليزية، وحسب بصمة كل فاتورة ووقّعها، وأنشأ رمز QR بحقوله التسعة، وربط كل فاتورة بالتي قبلها عبر عداد الفواتير وبصمة الفاتورة السابقة.
- التحقق: أرسلنا كل فاتورة إلى نقطة
/compliance/invoicesوسجلنا رمز HTTP وحالة التحقق وكل رسالة.
ماذا عاد: سجل الردود
| التشغيل | HTTP | الحالة | ما حدث |
|---|---|---|---|
| التشغيل 1 (3 فواتير) | HTTP 202 | WARNING | الثلاث بحالة REPORTED، مع تحذير واحد لكل فاتورة: invoiceTimeStamp_QRCODE_INVALID. |
| التشغيل 2 (3 فواتير) | HTTP 200 | PASS | بعد إصلاح وقت رمز QR. كلها REPORTED بلا تحذيرات. |
| التشغيل 3 (4 فواتير) | HTTP 200 | PASS | ثلاث فواتير متسلسلة وواحدة موقعة بالشهادة التي تستخدمها تجربتنا العامة. كلها REPORTED. |
المشكلة الوحيدة في عشر فواتير كانت تحذيراً واحداً تكرر في كل فاتورة من التشغيل الأول. أما التوقيع والبصمة وتسلسل الفواتير ومجاميع الضريبة وهيكل XML فلم تُظهر شيئاً.
ما معنى PASS وWARNING وERROR؟
PASS
مقبولة ولا شيء لإصلاحه
الفاتورة استوفت كل قواعد التحقق. الفاتورة المبسطة تعود بحالة «تم الإبلاغ»، فيحفظ نظامك الرد ويكمل.
WARNING
مقبولة لكن أصلحها
الفاتورة مقبولة، لكن فيها ما يخالف القواعد. من السهل تجاهل التحذيرات ولا ينبغي ذلك: أصلح السبب قبل التشغيل الفعلي، فقد يكون الحقل نفسه قاعدة إلزامية في موضع آخر.
ERROR
غير مقبولة
فشلت قاعدة واحدة على الأقل. لا يتم الإبلاغ عن الفاتورة ولا اعتمادها، فيجب تصحيحها وإرسالها من جديد. ولا تسلّم فاتورة ضريبية مرفوضة لمشترٍ أبداً.
تفصيلة فاجأتنا: ردود التحذير وصلت برمز HTTP 202، بينما وصلت الردود السليمة برمز 200. إن كان كودك يتحقق من 200 فقط فقد يعامل التحذير كفشل، وإن كان يكتفي بأي رمز 2xx فقد يتجاهل التحذيرات بصمت. اقرأ الحقل validationResults.status وقوائم الرسائل في كل مرة.
لماذا ظهر التحذير invoiceTimeStamp_QRCODE_INVALID؟
أعادت الهيئة هذه الرسالة لكل فاتورة في التشغيل الأول:
invoiceTimeStamp_QRCODE_INVALID: Time on QR Code does not match with Invoice Issue Time (KSA-25). If ZATCA's SDK was used to generate QR Code, kindly use the latest version of SDK
يحمل الحقل 3 في رمز QR للمرحلة الثانية تاريخ الفاتورة ووقتها. كان ملف XML يقول IssueDate 2026-11-21 وIssueTime 20:21:42، لكن قيمة QR كانت 2026-11-21T20:21:42Z مع حرف Z في النهاية (علامة توقيت UTC) غير موجود في XML. القيمتان تعنيان اللحظة نفسها، لكن الهيئة تقارنهما كما كُتبتا. حذفنا الحرف لتطابق قيمة QR ملف XML تماماً، فجاء التشغيل التالي نظيفاً.
والدرس أوسع من حرف واحد: استخرج كل حقول QR من ملف XML النهائي لا من متغيرات منفصلة، حتى لا يختلفا أبداً.
قائمة تحقق ليجتاز نظامك من المرة الأولى
قبل ربط أجهزة الإنتاج
cbc:IssueDate وcbc:IssueTime. لا تأخذه من استدعاء ثانٍ للساعة، ولا تغيّر الصيغة بينهما.ext:UBLExtensions وcac:Signature ومرجع QR، وبعد التوحيد القياسي (C14N 1.1). إعادة تنسيق الملف أو تغيير المسافات بعد حساب البصمة يفسدها.validationResults كاملة لكل رد، ونبّه عند أي تحذير، وأصلحه في الكود قبل ربط أجهزة الإنتاج.جرّب المحرك نفسه بنفسك
المحرك الذي اختبرناه يعمل الآن في تجربة آيفينيكس الحية للمرحلة الثانية. أدخل بيانات متجر وأصنافاً، وأصدر فاتورة، وشاهد ملف XML والبصمة والتوقيع وحقول QR، ثم أصدر الفاتورة التالية وشاهد السلسلة. كل ذلك في متصفحك ولا يُرسل شيء. لست متأكداً إن كانت الموجة 25 تشملك؟ في قائمة الموجة 25 فاحص سريع للموجات.
كيف تساعد آيفينيكس
تربط آيفينيكس الأنظمة الموجودة بمنصة فاتورة: أنظمة الكاشير وERP ومتاجر سلة وزد والتطبيقات الخاصة على الويب والجوال.
- التسجيل: المفاتيح وطلبات الشهادات وشهادات الامتثال والإنتاج لكل جهاز أو خادم.
- خدمة الربط: ملف XML الموقّع ورمز QR وتسلسل الفواتير والإبلاغ والاعتماد وإعادة المحاولة والمراقبة.
- اختبار على البيئة التجريبية بأشكال فواتيرك الحقيقية قبل التشغيل، مع تسليم الكود المصدري والتوثيق.
أسئلة شائعة
ماذا يعني WARNING في رد الامتثال من هيئة الزكاة والضريبة والجمارك؟
الفاتورة مقبولة (في اختبارنا عادت بحالة REPORTED ورمز HTTP 202)، لكن قاعدة واحدة على الأقل أعطت تحذيراً. أصلح السبب قبل التشغيل الفعلي، فالتحذير يعني أن نظامك ينتج بيانات لا تطابق القواعد تماماً.
ماذا يعني الخطأ invoiceTimeStamp_QRCODE_INVALID؟
رسالة الهيئة هي: "Time on QR Code does not match with Invoice Issue Time (KSA-25). If ZATCA's SDK was used to generate QR Code, kindly use the latest version of SDK". أي أن تاريخ ووقت الحقل 3 في رمز QR يجب أن يطابقا IssueDate وIssueTime في الفاتورة. في حالتنا أضفنا حرف المنطقة الزمنية إلى قيمة QR وحدها، وبحذفه اختفى التحذير.
هل الفاتورة التي عليها تحذير صالحة؟
في اختبارنا على البيئة التجريبية تم الإبلاغ عن الفواتير التي عليها تحذير. لكن هذا لا يجعل التحذير بلا ضرر: عامله كخلل وأصلحه قبل ربط أجهزة الإنتاج.
ماذا يحدث عندما تكون النتيجة ERROR؟
تفشل الفاتورة في التحقق فلا يتم الإبلاغ عنها ولا اعتمادها. صحّح البيانات وأرسلها من جديد. وفي الفواتير الضريبية (B2B) لا ترسل الفاتورة للمشتري قبل اعتمادها.
هل أستطيع تجربة الفوترة الإلكترونية دون شركة حقيقية؟
نعم. البيئة التجريبية في بوابة المطورين لدى الهيئة تصدر شهادات اختبار برمز OTP تجريبي منشور، فيستطيع المطورون تجربة التسجيل وفحص الفواتير. والشهادات الصادرة منها غير صالحة للفواتير الحقيقية.
أين أرى فاتورة المرحلة الثانية وهي تُبنى خطوة بخطوة؟
جرّب التجربة الحية للمرحلة الثانية على موقع آيفينيكس: تبني ملف XML والبصمة والتوقيع ورمز QR في متصفحك بنفس المحرك الذي اختبرناه هنا.
اقرأ أيضاً
- الموجة 25 من فاتورة: ما يجب أن تسلّمه فرق المنتج والبرمجة قبل 1 فبراير 2027
- الفوترة الإلكترونية في الإمارات: موعد مزود الخدمة المعتمد وقائمة للمنتج
تم التحقق في 21 نوفمبر 2026 الساعة 20:23 بتوقيت UTC (22:23 بتوقيت غزة). بيئة الاختبار: البيئة التجريبية في بوابة المطورين لدى الهيئة (ليست بيئة الإنتاج). المصادر: سجلات اختبارنا، وإعلان الموجة 25.
كل يوم أحد: أخطر الثغرات والاختراقات المؤكدة، ومن المتأثر في السعودية والإمارات ومصر، وما الذي يجب تحديثه أولاً. مجانية، بالعربية والإنجليزية، ويمكنك إلغاء الاشتراك بنقرة.
✓ تم الاشتراك. ستصلك رسالة ترحيب الآن، وأول عدد يوم الأحد.
