رمز الخطأ 1012: المعرّف الفريد UUID مكرّر أو خاطئ

تبني تكاملك مع منصة فاتورة، وتختبر إرسال فاتورة إلكترونية، فيعود إليك رفض برمز محدد: 1012. يخبرك هذا الرمز أن المعرّف الفريد UUID للفاتورة مكرّر أو خاطئ، فترفضه الهيئة قبل أن تنظر في أي حقل آخر. هذه الصفحة دليل متخصص في رمز الخطأ 1012 وحده، ضمن منظومة الفاتورة الإلكترونية من قيود.

الفرق بين هذه الصفحة وصفحة أخطاء المعرّف الفريد UUID العامة فرق في الزاوية. الصفحة العامة تشرح أنماط أخطاء UUID الخمسة كلها (مكرر، صيغة خاطئة، حقل مفقود، إعادة استخدام، خلط مع رقم الفاتورة). أما هنا فنركّز على الرمز 1012 تحديداً: متى يصدره النظام، وما الحالات التي يغطيها، وكيف تقرأ رسالته، وكيف تصلحه نهائياً. إن أردت فهم حقل UUID نفسه (تعريفه وصيغته وموضعه في XML) فمرجعه صفحة المعرّف الفريد UUID في الفاتورة الإلكترونية. ولمحة عن بقية فئات أخطاء المنظومة تجدها في دليل أخطاء هيئة الزكاة والضريبة والجمارك في الفوترة.

الجمهور المستهدف هنا هو المطوّر أو مسؤول التكامل التقني الذي يبني اتصال نظام محاسبي بمنصة فاتورة. لذلك تجد أمثلة JSON فعلية لاستجابات الهيئة، وشرحاً لكل حالة بصيغة عرض المشكلة ثم الحل. الرموز التقنية الإنجليزية مثل cbc:UUID وvalidationResults تبقى كما هي لأنها أسماء حقول فعلية في الـ API.

ما الذي يعنيه رمز الخطأ 1012 بالضبط

الرمز 1012 ليس خطأ صياغة عابراً، بل قرار رفض نهائي. تصدره الهيئة عندما تفشل قيمة المعرّف الفريد UUID في اجتياز التحقق، سواء لأنها مكرّرة أو لأنها لا تطابق الصيغة المطلوبة. حقل UUID إلزامي في كل فاتورة إلكترونية في المرحلة الثانية، وهو بصمة عالمية لا تتكرر تميّز كل مستند فاتورة عن أي فاتورة أخرى في أي نظام في العالم.

تعتمد الهيئة على هذا الحقل لتمييز المستند في المقاصة والإبلاغ، ولمنع ازدواج الفواتير في سجلها. لأن الحقل إلزامي ومُقيَّد الصيغة، فهو لا يقبل أنصاف الحلول. القيمة إما أن تكون موجودة وصحيحة الصيغة وفريدة، أو يصدر الرمز 1012 وتُرفض الفاتورة. لا توجد حالة «تحذير» هنا، بل رفض مباشر يضع status على ERROR.

الخلاصة العملية أن الرمز 1012 يجمع تحت مظلته عائلتين من المشكلات: التكرار وفساد الصيغة. كلتاهما تعودان إلى منطق توليد المعرّف في نظامك، لا إلى الفاتورة نفسها. لذلك إصلاح الرمز 1012 يبدأ دائماً من السؤال: متى وكيف يولّد نظامي قيمة UUID؟

قبل أن ندخل في الحالات الثلاث، تستحق نقطة جوهرية التوضيح. معظم مطوّري التكامل الجدد يتعاملون مع المعرّف الفريد كأنه رقم تسلسلي عادي، فيقعون في الرمز 1012 من حيث لا يدرون. لكن UUID ليس رقماً تختاره أنت أو تزيده بواحد عند كل فاتورة، بل قيمة عشوائية يولّدها معيار محدد لتكون فريدة عالمياً دون أي تنسيق بين الأنظمة. فهم هذا الفرق وحده يمنع أغلب حالات الرمز 1012، لأن جذرها هو معاملة المعرّف العشوائي معاملة الرقم التسلسلي.

كما أن توقيت توليد القيمة لا يقل أهمية عن طريقة توليدها. القيمة يجب أن تولَّد لحظة إنشاء كل مستند فاتورة، لا قبلها ولا بعدها. توليدها مبكراً (عند تجهيز قالب مثلاً) يفتح باب التكرار، وتأجيلها قد ينتج حقلاً فارغاً يكسر الصيغة. الزمن الصحيح للتوليد هو نقطة إنشاء المستند نفسه، مرة واحدة لكل مستند. احتفظ بهذه القاعدة في ذهنك وأنت تقرأ الحالات الثلاث، فهي الخيط الذي يربطها جميعاً.

الحالة الأولى: UUID مكرّر بين فاتورتين

هذه أشهر حالات الرمز 1012. تحدث عندما يرسل نظامك القيمة نفسها لمستندين مختلفين، فترفض الهيئة الثاني لأنها سبق أن سجّلت القيمة للأول. تأتي رسالة الاستجابة على هذا النحو:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1012",
        "category": "DUPLICATE_DOCUMENT",
        "message": "Invoice UUID already exists for this taxpayer"
      }
    ],
    "warningMessages": []
  }
}

السبب الجذري. نظامك يولّد القيمة نفسها لمستندين. أشهر سبب هو توليد UUID مرة واحدة وتخزينه ثابتاً في قالب، أو نسخ فاتورة قديمة مع معرّفها بدل توليد معرّف جديد، أو خلل في مولّد الأرقام العشوائية يجعله يكرر القيم.

الحل. ولّد قيمة UUID جديدة لحظة إنشاء كل فاتورة. لا تشتق القيمة من رقم الفاتورة ولا من التاريخ ولا من أي بيانات قابلة للتكرار. خزّن كل معرّف مولَّد في جدول، وتحقق قبل الإرسال أنه لم يُستخدم من قبل في نظامك.

للتحقق من جذر المشكلة عملياً، افحص متى يستدعي كودك دالة التوليد. إن وجدتها تُستدعى عند تحميل القالب أو عند بدء جلسة المستخدم، فهذا هو الخلل، لأن القيمة تولَّد مرة وتُعاد على كل فاتورة. انقل الاستدعاء إلى داخل دالة إنشاء الفاتورة نفسها، بحيث يقابل كل مستند استدعاء توليد مستقلاً. أضف كذلك قيد تفرّد (unique constraint) على عمود المعرّف في قاعدة بياناتك، فيمنعك هذا القيد من حفظ معرّف مكرّر قبل أن يصل أصلاً إلى الهيئة.

الحالة الثانية: صيغة UUID غير صالحة

الوجه الثاني للرمز 1012 هو فساد الصيغة. حتى لو كانت القيمة فريدة تماماً، فإنها تُرفض إذا لم تطابق الصيغة المعيارية للمعرّف الفريد. الصيغة المطلوبة هي معرّف من الإصدار الرابع (UUID v4) مكوّن من 36 حرفاً: 32 رقماً ست عشرياً موزّعة على خمس مجموعات تفصلها أربع شرطات، بالشكل 8-4-4-4-12.

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1012",
        "category": "INVALID_FORMAT",
        "message": "UUID value is not a valid v4 identifier"
      }
    ],
    "warningMessages": []
  }
}

السبب الجذري. الصيغة تفسد لأسباب متعددة. قد يكون الطول خاطئاً (عدد الأحرف ليس 36، أو الشرطات في غير مواضعها)، أو تحوي القيمة أحرفاً خارج النظام الست عشري، أو يولّد نظامك معرّفاً من إصدار آخر غير الرابع، أو يُدرج فراغات أو أحرفاً مخفية حول القيمة عند بنائها في XML.

الحل. استخدم دالة توليد قياسية للإصدار الرابع من المعرّف الفريد متوفرة في لغة برمجتك، ولا تبنِ القيمة يدوياً بدمج نصوص. تجنّب أي تحويل لاحق يغيّر حالة الأحرف أو يضيف بادئة أو لاحقة. قبل إدراج القيمة في cbc:UUID، تحقق منها بتعبير نمطي يتأكد من مطابقة الصيغة 8-4-4-4-12. وانتبه إلى أن الرمز 1012 لا يفرّق في رسالته أحياناً بين سبب وآخر، لذلك افحص الطول والأحرف والإصدار معاً قبل أن تعيد الإرسال.

الحالة الثالثة: إعادة استخدام UUID عند إعادة الإرسال

هذه الحالة أكثر خفاءً، وتربك المطوّرين الجدد كثيراً. عندما تُرفض فاتورة لسبب آخر (خطأ في حقل ضريبي مثلاً)، يصححها المستخدم ويعيد إرسالها. إن أعدت الإرسال بالمعرّف الفريد نفسه، فقد سجّلت الهيئة محاولتك الأولى بهذه القيمة، فيعود إليك الرمز 1012 على أنها قيمة مكرّرة.

السبب الجذري. النظام يربط المعرّف الفريد بالفاتورة كبيان ثابت، فيظن أن «الفاتورة نفسها» يجب أن تحمل المعرّف نفسه عند كل محاولة. هذا فهم خاطئ. المعرّف الفريد يخص مستند الإرسال، لا الفاتورة كفكرة تجارية. كل محاولة إرسال هي مستند جديد من منظور الهيئة، ويجب أن تحمل معرّفاً جديداً.

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

القاعدة الذهبية هنا بسيطة: لا تعامل الرمز 1012 على أنه «خطأ في الفاتورة القديمة»، بل على أنه إشارة إلى أن قيمة المعرّف استُهلكت ولا تصلح مرة أخرى. أي معرّف وصل إلى سجل الهيئة، نجح أم فشل، يُعتبر مستهلَكاً.

تتعقّد هذه الحالة أكثر في الأنظمة التي تخزّن المعرّف الفريد مبكراً ضمن سجل الفاتورة، ثم تستدعيه عند كل عملية إرسال. لو فشلت المحاولة الأولى وأبقى النظام القيمة المخزّنة كما هي، فإن المحاولة الثانية ترسل القيمة ذاتها فيصدر الرمز 1012. الحل التصميمي هو ألّا تُخزَّن قيمة المعرّف الفريد كبيان دائم في سجل الفاتورة، بل تولَّد ضمن خطوة بناء حمولة الإرسال نفسها. بهذا يصبح كل إرسال مستقلاً بطبيعته، ولا يحتاج فريقك إلى تذكّر تحديث القيمة يدوياً.

انتبه كذلك إلى عمليات إعادة المحاولة التلقائية. بعض الأنظمة تعيد إرسال الطلب آلياً عند انقطاع الشبكة أو انتهاء المهلة، فترسل القيمة نفسها مرتين. إن وصلت المحاولة الأولى إلى الهيئة فعلاً ثم انقطع الرد عنك، فإن إعادة المحاولة بالقيمة ذاتها تنتج الرمز 1012 رغم أن الفاتورة الأولى نجحت. صمّم منطق إعادة المحاولة بحيث يستعلم أولاً عن حالة المستند قبل أن يعيد إرساله، أو يولّد معرّفاً جديداً لكل محاولة شبكية.

كيف تقرأ رسالة الرمز 1012 وتشخّصها خطوة بخطوة

عندما يصلك الرمز 1012، اتبع تسلسلاً ثابتاً للتشخيص بدل التخمين. الهدف أن تحدد أي حالة من الثلاث أنت فيها قبل أن تكتب أي إصلاح.

أولاً، اقرأ حقل category في الاستجابة. قيمة DUPLICATE_DOCUMENT تعني أن القيمة مكرّرة أو مُعاد استخدامها، وقيمة INVALID_FORMAT تعني أن الصيغة فاسدة. هذا الحقل وحده يقسم المشكلة إلى نصفين ويوفّر عليك نصف وقت التشخيص.

ثانياً، استخرج قيمة UUID التي أرسلتها فعلاً من حمولة XML. لا تعتمد على ما تظنه القيمة، بل على ما خرج من نظامك حرفياً. انسخها وافحص طولها وصيغتها بأداة تحقق من المعرّف الفريد. إن لم تطابق الصيغة المعيارية، فأنت في الحالة الثانية.

ثالثاً، إن كانت الصيغة سليمة والفئة DUPLICATE_DOCUMENT، فابحث عن القيمة نفسها في سجل المعرّفات الذي يحفظه نظامك. إن وجدتها مرتبطة بفاتورة سابقة ناجحة، فأنت في الحالة الأولى (تكرار حقيقي). وإن وجدتها مرتبطة بمحاولة إرسال سابقة فاشلة لنفس الفاتورة، فأنت في الحالة الثالثة (إعادة استخدام عند إعادة الإرسال).

رابعاً، أصلح المنطق لا المستند الواحد. الرمز 1012 يتكرر دفعةً واحدة على كل الفواتير المتأثرة بالخلل نفسه. تصحيح فاتورة واحدة لا يحلّ الجذر. عدّل دالة التوليد، أعد اختبارها في البيئة التجريبية، ثم أعد إرسال الدفعة كلها بمعرّفات سليمة.

يفيدك أن تسجّل لكل محاولة إرسال قيمة المعرّف الفريد التي خرجت فعلاً، مع الطابع الزمني وحالة الاستجابة. هذا السجل يحوّل تشخيص الرمز 1012 من تخمين إلى مراجعة مباشرة: تفتح السجل، تبحث عن القيمة المرفوضة، فترى متى أُرسلت أول مرة وبأي حالة. السجل نفسه يكشف أنماط الخلل المتكررة، مثل قالب يعيد القيمة ذاتها أو مسار إعادة محاولة يولّد تكراراً صامتاً.

وأخيراً، احذر من «الحل» الذي يبدو سريعاً ويزيد المشكلة: توليد قيمة عشوائية يدوية لتجاوز الرفض لحظياً. هذا يخفي الجذر ويترك دالة التوليد المعطوبة تنتج الرمز 1012 في الدفعة التالية. عالج السبب مرة واحدة بدل أن تطفئ الحريق فاتورةً فاتورة.

كيف يساعدك قيود في تفادي الرمز 1012

الفكرة الجوهرية أن معظم حالات الرمز 1012 تنشأ من منطق توليد يكتبه فريق التكامل بنفسه. عندما يتولى نظام محاسبي متكامل توليد المعرّف الفريد نيابةً عنك، تختفي هذه الفئة من الأخطاء لأنها لا تترك للمستخدم فرصة الخطأ في التوليد أصلاً.

يولّد قيود قيمة UUID فريدة لكل مستند فاتورة لحظة إنشائه، بالصيغة المعيارية للإصدار الرابع. ولأن المنصة مرتبطة مباشرة بمنصة فاتورة، فهي تبني حمولة XML المتوافقة مع المرحلة الثانية وتضع المعرّف في موضعه الصحيح داخل cbc:UUID دون تدخل يدوي. كما يدير قيود معرّف الختم المشفر (CSID) لكل منشأة تلقائياً ضمن منظومة الفوترة الإلكترونية، فيتولّى الجانب التقني بدل أن يكون عبئاً على فريقك.

عند إعادة إرسال فاتورة صُححت، يولّد قيود معرّفاً جديداً تلقائياً بدل إعادة استخدام القديم، فتنتفي الحالة الثالثة من جذرها. النتيجة أن المحاسب يركّز على صحة البيانات الضريبية، بينما تتكفّل المنصة بالتفاصيل التقنية التي تنتج الرمز 1012.

هذا الفرق يظهر بوضوح في المنشآت التي تصدر فواتير كثيرة يومياً. كلما زاد حجم الفواتير، ارتفع احتمال أن يُنتج منطق توليد مكتوب يدوياً قيمة مكرّرة أو فاسدة الصيغة تحت الضغط. عندما يتولّى نظام مُختبَر على ملايين الفواتير هذه المهمة، يصبح الرمز 1012 حدثاً نادراً بدل أن يكون عقبة يومية يطاردها فريق التكامل. كما يوفّر النظام المتكامل سجلاً موحّداً لكل إرسال، فتراجع أي رفض سابق دون أن تبني أدوات تشخيص خاصة بك.

تعرّف على منظومة الفاتورة الإلكترونية من قيود ومتطلباتها للمرحلة الثانية، لتفهم أين يقع توليد المعرّف ضمن دورة إصدار الفاتورة المتوافقة.

متى يظهر الرمز 1012 في الاختبار ومتى في الإنتاج

تختلف خطورة الرمز 1012 باختلاف البيئة التي يظهر فيها. في البيئة التجريبية (sandbox)، ظهوره مفيد لأنه يكشف خلل التوليد مبكراً قبل أن يمسّ فواتير حقيقية. عامل أي رمز 1012 في الاختبار على أنه جرس إنذار يستحق إصلاح الجذر فوراً، لا تجاوزه بتوليد قيمة يدوية مؤقتة.

أما في الإنتاج، فظهور الرمز 1012 أخطر لأنه يعني فواتير مرفوضة فعلية تؤخّر الإبلاغ. هنا تظهر قيمة قيد التفرّد في قاعدة البيانات: إن كان موجوداً، يُحبَط التكرار في نظامك قبل أن يصل إلى الهيئة، فلا يتحول إلى رفض إنتاجي. اجعل اختبار منطق التوليد جزءاً ثابتاً من خط النشر، بحيث لا يصل أي تغيير في كود الفوترة إلى الإنتاج دون اجتياز اختبار يولّد آلاف المعرّفات ويتحقق من تفرّدها وصيغتها.

القاعدة العملية: عالج الرمز 1012 في الاختبار بإصلاح الكود، وفي الإنتاج بإيقاف الدفعة المتأثرة فوراً، إصلاح الجذر، ثم إعادة الإرسال بمعرّفات جديدة. لا تخلط بين الحلين.

قائمة وقاية عملية من الرمز 1012

الوقاية أرخص من العلاج. راجع النقاط التالية في كودك قبل أن تطلق تكاملك في الإنتاج، فهي تغطّي الأسباب الجذرية الثلاثة للرمز 1012.

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

مولّد قياسي للإصدار الرابع. اعتمد على دالة جاهزة في مكتبة لغتك تولّد UUID v4، ولا تبنِ القيمة بدمج نصوص أو بأرقام عشوائية يدوية. المولّدات القياسية تضمن الصيغة والعشوائية معاً.

تحقق من الصيغة قبل الإرسال. أضف خطوة تحقق بتعبير نمطي تتأكد أن القيمة 36 حرفاً بالشكل 8-4-4-4-12، دون فراغات أو أحرف خفية حولها. أوقف الإرسال محلياً إن فشل التحقق، فهذا أرخص من رفض الهيئة.

قيد تفرّد في قاعدة البيانات. ضع unique constraint على عمود المعرّف الفريد. هذا القيد هو خط دفاعك الأخير ضد التكرار قبل أن يغادر المعرّف نظامك.

معرّف جديد لكل محاولة إرسال. اجعل مسار إعادة الإرسال وإعادة المحاولة التلقائية يولّد قيمة جديدة، أو يستعلم عن حالة المستند قبل إعادة استخدام قيمة سابقة.

اختبار دفعي قبل النشر. اكتب اختباراً يولّد آلاف المعرّفات دفعةً واحدة ويتحقق من تفرّدها وصيغتها. أدرجه في خط النشر بحيث لا يصل تغيير في كود الفوترة إلى الإنتاج دون اجتيازه.

من إصلاح الفاتورة إلى إصلاح منطق التوليد

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

الإصلاح الجذري ثلاثي: ولّد المعرّف داخل دالة إنشاء المستند مرة واحدة لكل مستند، استخدم مولّداً قياسياً للإصدار الرابع لا بناءً يدوياً، وأضف قيد تفرّد على مستوى قاعدة البيانات. هذه الطبقات الثلاث مجتمعة تغلق الأبواب الثلاثة التي يدخل منها الرمز 1012: التكرار، فساد الصيغة، وإعادة الاستخدام.

متى ثبّتّ هذه الطبقات واختبرتها، يتحول الرمز 1012 من خطأ متكرر يطاردك إلى حالة نادرة تكشفها قبل وصولها إلى الهيئة. والأهم أن إصلاحك يصمد مع نمو حجم الفواتير، لأنه يعالج منطق التوليد لا الأعراض. إن أردت تجنّب كتابة هذا المنطق من الصفر، فاعتماد نظام محاسبي يتولّى توليد المعرّف وصيغته وتفرّده يضع هذه الطبقات الثلاث في مكانها افتراضياً، فتبدأ من نقطة خالية من الرمز 1012.

الأسئلة الشائعة

ما الفرق بين الرمز 1012 وأخطاء UUID الأخرى؟

الرمز 1012 يخص تحديداً المعرّف الفريد المكرّر أو الخاطئ الصيغة. أخطاء UUID الأخرى مثل الحقل المفقود كلياً أو الخلط بينه وبين رقم الفاتورة قد تصدر برموز أو فئات مختلفة. للوحة كاملة بكل أنماط UUID راجع صفحة أخطاء المعرّف الفريد UUID.

هل يكفي توليد UUID جديد لإصلاح الرمز 1012؟

توليد قيمة جديدة سليمة يحل الفاتورة الحالية، لكنه لا يصلح الجذر إن كان نظامك يكرر القيم أو يولّدها بصيغة خاطئة. أصلح دالة التوليد وتوقيت استدعائها، ثم أضف قيد تفرّد في قاعدة البيانات حتى لا يتكرر الخطأ.

هل يجب أن أغيّر رقم الفاتورة عند تغيير المعرّف الفريد؟

لا. رقم الفاتورة التجاري والمعرّف الفريد للمستند حقلان منفصلان. قد يبقى رقم الفاتورة ثابتاً عند إعادة الإرسال، بينما يجب أن يتغيّر المعرّف الفريد مع كل محاولة إرسال.

لماذا يعود الرمز 1012 عند إعادة إرسال فاتورة سبق أن رُفضت؟

لأن الهيئة سجّلت قيمة المعرّف من محاولتك الأولى، فأصبحت مستهلَكة. أي معرّف وصل إلى سجل الهيئة لا يصلح مرة أخرى. ولّد معرّفاً جديداً لكل محاولة إرسال.

ما الصيغة الصحيحة للمعرّف الفريد التي يقبلها النظام؟

معرّف من الإصدار الرابع (UUID v4) مكوّن من 36 حرفاً: 32 رقماً ست عشرياً على خمس مجموعات بالشكل 8-4-4-4-12 تفصلها أربع شرطات، دون فراغات أو أحرف إضافية حوله.

كيف أتفادى الرمز 1012 دون كتابة منطق توليد بنفسي؟

استخدم نظاماً محاسبياً متكاملاً يولّد المعرّف الفريد ويبني XML المتوافق نيابةً عنك. يدير قيود توليد المعرّف وصيغته وتفرّده تلقائياً، فلا يصلك الرمز 1012 من الأساس.