رمز الخطأ 1019: توقيع XAdES غير مكتمل

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

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

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

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

المقصود بـ XAdES امتداد لتوقيع XML الرقمي يضيف خصائص قانونية وزمنية فوق التوقيع الأساسي. الفاتورة الإلكترونية في السعودية تُوقَّع بهذا النمط. والتوقيع الصحيح يجب أن يحوي كتلة خصائص موقّعة (SignedProperties) تشهد على وقت التوقيع وعلى الشهادة التي وقّعت بها. الخطأ 1019 يعني أن هذه الكتلة ناقصة أو غير مرتبطة بالتوقيع كما ينبغي.

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

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

كيف تقرأ رسالة الرفض

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

{
  "validationResults": {
    "infoMessages": [
      {
        "type": "INFO",
        "code": "XSD_ZATCA_VALID",
        "category": "XSD validation",
        "message": "Complied with UBL 2.1 standards"
      }
    ],
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1019",
        "category": "Signature validation",
        "message": "XAdES signature is incomplete: required SignedProperties are missing or not referenced."
      }
    ],
    "status": "ERROR"
  },
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null
}

المفاتيح التي تهمّك في القراءة:

• clearanceStatus بقيمة NOT_CLEARED يعني أن المقاصة لم تتم، فالفاتورة لم تُعتمد ولا يجوز تسليمها للمشتري.
• category بقيمة Signature validation يحصر المشكلة في طبقة التوقيع، لا في محتوى الفاتورة ولا في بياناتها الضريبية.
• code بقيمة 1019 هو التعريف الدقيق للسبب، والرسالة تشير إلى أن الخصائص الموقّعة مفقودة أو غير مُشار إليها.
• clearedInvoice بقيمة null يؤكد أنه لا توجد نسخة مختومة عائدة إليك.

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

ما الذي يجعل توقيع XAdES «مكتملًا»

قبل علاج النقص، يجب أن تعرف الشكل الكامل. توقيع XAdES في الفاتورة يتكوّن من كتلة ds:Signature تحوي عدة أجزاء مترابطة. أي جزء غائب أو غير مرتبط ينتج توقيعًا «غير مكتمل». الأجزاء الأساسية:

• ds:SignedInfo: تصف ما الذي وُقّع عليه، وتحوي مراجع (ds:Reference) تشير إلى محتوى الفاتورة وإلى كتلة الخصائص الموقّعة.
• ds:SignatureValue: قيمة التوقيع الفعلية الناتجة عن المفتاح الخاص للشهادة.
• ds:KeyInfo: تحمل الشهادة التي وقّعت بها.
• ds:Object: يحوي xades:QualifyingProperties ومن تحتها xades:SignedProperties وهي بيت القصيد في هذا الخطأ.

داخل xades:SignedProperties يجب أن يوجد عنصران لا غنى عنهما: xades:SigningTime الذي يسجّل وقت التوقيع، و xades:SigningCertificate الذي يثبّت أي شهادة وقّعت عبر بصمة موجزة (CertDigest) ومرجع المُصدِر والرقم التسلسلي (IssuerSerial). الكتلة التالية تبيّن البنية الكاملة المتوقَّعة بشكل مختصر.

  
    ...
    
      
      ...
    
  
  ...
  ...
  
    
      
        
          2026-06-24T10:15:00Z
          
            
              
                
                ...
              
              
                ...
                ...
              
            
          
        
      
    
  

لاحظ المرجع الثاني داخل ds:SignedInfo: هو الذي يربط التوقيع بكتلة SignedProperties عبر سمتي URI و Type. غياب هذا المرجع، أو إشارته إلى معرّف لا وجود له، يجعل الخصائص الموقّعة موجودة شكلًا لكنها غير مرتبطة بالتوقيع. والنتيجة هي نفسها: توقيع غير مكتمل. لهذا لا يكفي أن تتأكد من وجود الكتلة، بل من أنها مرتبطة بالتوقيع ارتباطًا صحيحًا.

الأسباب الأربعة التي تنتج الخطأ 1019

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

1. غياب كتلة الخصائص الموقّعة كليًا

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

2. الخصائص الموقّعة موجودة لكنها ناقصة العناصر

الكتلة موجودة، لكن ينقصها xades:SigningTime أو xades:SigningCertificate. أكثر صورة شائعة: وجود SigningCertificate بلا بصمة موجزة (CertDigest) أو بلا مرجع المُصدِر والرقم التسلسلي (IssuerSerial). أي عنصر ناقص داخل الكتلة يجعلها غير مكتملة في نظر التحقق.

3. الخصائص الموقّعة غير مُشار إليها من SignedInfo

الكتلة كاملة، لكن لا يوجد داخل ds:SignedInfo مرجع (ds:Reference) يشير إليها، أو أن قيمة URI في المرجع لا تطابق Id كتلة SignedProperties. عندها لا يعدّ التحقق هذه الخصائص جزءًا من التوقيع، فكأنها غير موجودة. هذا أدقّ الأسباب وأصعبها اكتشافًا لأن الملف يبدو كاملًا للعين.

4. مراجع SignedInfo مشوّهة

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

مثال عملي: توقيع ناقص مقابل توقيع مكتمل

الكتلة التالية تبيّن السبب الأول والأشيع: توقيع تنقصه كتلة ds:Object كاملةً، فلا توجد فيه خصائص موقّعة أصلًا. هذا بالضبط ما ينتج الخطأ 1019 عند بناء التوقيع بمكتبة لا تدعم XAdES.

  
    
      ...
    
    
  
  ...
  ...
  

المشكلة هنا في موضعين: لا يوجد ds:Object يحمل الخصائص الموقّعة، ولا مرجع داخل ds:SignedInfo يشير إليها. لتصحيحه، نضيف كتلة QualifyingProperties كاملة، ثم نضيف المرجع الذي يربطها بالتوقيع. الكتلة التالية تبيّن الجزء المُصحَّح المضاف.

  
  ...




  
    
      
        2026-06-24T10:15:00Z
        
          
            
              
              ...
            
            
              ...
              ...
            
          
        
      
    
  

بعد إضافة هذين الجزأين يصبح التوقيع مكتملًا: الخصائص الموقّعة موجودة، ومرتبطة بالتوقيع عبر مرجع URI المطابق لـ Id. تنبيه: لا تضف هذه العناصر يدويًا على ملف موقّع جاهز. أضفها في طبقة التوليد قبل التوقيع، لأن أي تعديل بعد التوقيع يبطل قيمة الموجز.

كيف تميّز الخطأ 1019 عن أخطاء التوقيع الأخرى

أخطاء التوقيع تتشابه ظاهريًا فتربك التشخيص. الفروق العملية بينها:

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

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

أين يقع التوقيع في مسار الفاتورة

الفوترة الإلكترونية في السعودية تسير على مسارين بحسب نوع الفاتورة، والتوقيع حاضر في كليهما لكن بدور مختلف. فهم موضع التوقيع في المسار يوضح لماذا يوقف الخطأ 1019 الفاتورة بالكامل.

• المقاصة (Clearance) للفواتير الضريبية القياسية (B2B): تُرسَل الفاتورة الموقّعة إلى المنصة قبل تسليمها للمشتري. إذا كان التوقيع ناقصًا توقف المقاصة، فلا تُعتمد الفاتورة ولا تُسلَّم.
• الإبلاغ (Reporting) للفواتير المبسّطة (B2C): تُصدَر الفاتورة موقّعة وتُسلَّم للعميل، ثم يُبلَّغ عنها المنصة خلال المهلة المقررة. التوقيع الناقص هنا يُفشل الإبلاغ ويبقي الفاتورة غير مكتملة التوثيق.

في الحالتين، التوقيع شرط لاكتمال العملية. لذلك لا يُعامَل الخطأ 1019 كتحذير يمكن تجاهله، بل كمانع يوقف الفاتورة عن دخول المنظومة. ومعالجته أولوية قبل أي خطأ آخر في الاستجابة، لأن الفاتورة بلا توقيع مكتمل لا قيمة لها أمام الهيئة مهما سلِم باقي محتواها.

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

كيف تفحص المنصة التوقيع خطوة بخطوة

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

• التحقق من البنية (XSD): تتأكد المنصة أن ملف الفاتورة يطابق مخطط UBL 2.1. إذا نجح هذا تظهر XSD_ZATCA_VALID كرسالة معلومات، كما في مثال الاستجابة أعلاه.
• التحقق من وجود كتلة التوقيع: تبحث المنصة عن ds:Signature وعن ds:Object الذي يحمل الخصائص الموقّعة. غيابهما هو السبب الأول للخطأ 1019.
• التحقق من اكتمال الخصائص الموقّعة: تتأكد من وجود SigningTime و SigningCertificate بعنصريه. نقص أي عنصر يوقف التحقق هنا.
• التحقق من الربط: تتأكد أن ds:SignedInfo يحوي مرجعًا صحيحًا إلى SignedProperties. هذا أدقّ ما يفحصه التحقق وأكثره خفاءً عند التشخيص.

الخطأ 1019 يُطلَق في المرحلتين الثالثة والرابعة: حين تنقص الخصائص الموقّعة عناصرها، أو حين لا تكون مرتبطة بالتوقيع. أما المرحلة الأولى فلها أخطاؤها الخاصة بفئة التحقق من البنية، والمرحلة الثانية قد تنتج خطأ غياب التوقيع كليًا. لذلك لا تعالج الخطأ في طبقة المحتوى ما دامت فئة الرفض هي التحقق من التوقيع.

نقطة دقيقة تستحق الانتباه: ربط الخصائص الموقّعة بالتوقيع يعتمد على تجزئة (Digest) محسوبة على كتلة SignedProperties بعد توحيد صياغتها (Canonicalization). إذا اختلفت الصياغة بين لحظة الحساب ولحظة التحقق، أو حُسبت التجزئة على كتلة قبل اكتمالها، فلن تتطابق القيم وقد يظهر الخطأ نفسه. لذلك يجب أن تُحسب التجزئة على الكتلة النهائية بعد توحيد صياغتها، لا قبل ذلك.

متى يظهر الخطأ حسب طريقة بناء التكامل

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

تكامل مبني يدويًا بمكتبة توقيع عامة

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

قالب توقيع منسوخ بمعرّفات غير متطابقة

كثيرون ينسخون قالب توقيع جاهزًا ثم يعدّلون عليه. الخطأ الشائع هنا أن يبقى معرّف Id في كتلة SignedProperties مختلفًا عن قيمة URI في المرجع، فينكسر الربط. الملف يبدو كاملًا، لكنه يُرفض. تحقق دائمًا أن المعرّف والمرجع يحملان القيمة نفسها بعد أي تعديل على القالب.

تعديل المحتوى بعد التوقيع

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

كيف تصحّح التوقيع وتعيد الإرسال

اتبع الخطوات بالترتيب. كل خطوة تعالج طبقة فوق سابقتها، فلا تقفز.

• أكّد أن مولّد التوقيع يدعم XAdES. تحقق أن الأداة تُنتج كتلة xades:QualifyingProperties، لا توقيع XML أساسيًا فحسب.
• افحص اكتمال الخصائص الموقّعة. تأكد من وجود SigningTime و SigningCertificate بعنصريه: CertDigest و IssuerSerial.
• تحقق من المرجع. يجب أن يحوي ds:SignedInfo مرجعًا إلى SignedProperties بقيمة URI مطابقة لـ Id وبسمة Type الصحيحة.
• أعد توليد المستند بعد أي تعديل. أي تغيير في المحتوى أو في بنية التوقيع يبطل التجزئة، فلا تعدّل ملفًا موقّعًا يدويًا.
• وقّع من جديد بشهادة CSID. أعد التوقيع بشهادة منشأتك ثم أرسل المستند إلى المقاصة.

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

تفصيل كتلة هوية الشهادة: CertDigest و IssuerSerial

أكثر صور النقص خفاءً تقع داخل xades:SigningCertificate. هذه الكتلة لا تكتفي بذكر الشهادة، بل تثبّتها بطريقتين متكاملتين، ونقص أيٍّ منهما ينتج توقيعًا غير مكتمل:

• CertDigest: بصمة موجزة للشهادة، تتكوّن من خوارزمية الموجز (DigestMethod) وقيمته (DigestValue). تثبت أن الشهادة المرجعية هي نفسها التي وقّعت فعلًا، فلا يمكن استبدالها.
• IssuerSerial: يحدد الشهادة عبر اسم الجهة المُصدِرة (X509IssuerName) والرقم التسلسلي (X509SerialNumber). يربط الشهادة بسلسلة الثقة التي أصدرتها.

الخطأ الشائع أن يُولّد التكامل CertDigest ويهمل IssuerSerial، أو العكس، ظنًّا أن أحدهما يكفي. كلاهما إلزامي. ومن الأخطاء أيضًا أن تُحسب البصمة على شهادة مختلفة عن التي وقّعت الفاتورة، فيظهر التوقيع كاملًا شكلًا لكن بصمته لا تطابق الشهادة المرفقة في ds:KeyInfo. تأكد دائمًا أن البصمة والرقم التسلسلي يخصّان شهادة CSID نفسها التي وقّعت المستند.

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

قائمة فحص قبل الإرسال

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

• هل يحوي الملف كتلة ds:Object مع xades:QualifyingProperties و xades:SignedProperties؟
• هل داخل الخصائص الموقّعة عنصر SigningTime بصيغة زمنية صحيحة؟
• هل SigningCertificate يحوي CertDigest (خوارزمية وقيمة) و IssuerSerial (اسم المُصدِر والرقم التسلسلي)؟
• هل يوجد داخل ds:SignedInfo مرجع إلى الخصائص الموقّعة بقيمة URI مطابقة لـ Id وبسمة Type الصحيحة؟
• هل بصمة الشهادة في CertDigest تخصّ الشهادة نفسها المرفقة في ds:KeyInfo؟
• هل التوقيع هو آخر خطوة، ولم يُعدَّل المحتوى بعده بأي حال؟

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

كيف تمنع تكرار الخطأ 1019 مستقبلًا

هذا الخطأ بنيوي في طبقة التوقيع، فالوقاية منه تكون في طريقة بنائه لا في معالجته بعد الرفض. خذ بهذه الإجراءات:

• اعتمد مكتبة توقيع تدعم XAdES صراحةً، وثبّت إصدارها حتى لا يتغيّر سلوكها فجأة.
• أضف تحققًا محليًا قبل الإرسال يرفض أي مستند تنقصه SignedProperties أو مرجعها داخل ds:SignedInfo.
• وقّع آخر خطوة في المسار، بعد اكتمال محتوى الفاتورة، حتى لا يتغيّر المحتوى بعد التوقيع فتبطل التجزئة.
• راقب رمز الاستجابة عند كل إرسال، وسجّل category و code في سجلّاتك لتكتشف أي انحراف مبكرًا.

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

كيف يساعدك قيود في تفادي هذا الخطأ

يدير قيود طبقة التوقيع كاملةً نيابةً عنك. يولّد كتلة xades:SignedProperties بكل عناصرها الإلزامية: وقت التوقيع، وبصمة الشهادة الموجزة، ومرجع المُصدِر والرقم التسلسلي. ثم يضيف المرجع داخل ds:SignedInfo الذي يربط هذه الكتلة بالتوقيع بالشكل الذي يفرضه المعيار. فلا تبني التوقيع يدويًا ولا تقلق من نقص عنصر فيه.

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

لفهم البنية التقنية كاملة راجع المواصفة التقنية للتوقيع الرقمي، ولاستعراض بقية رموز الأخطاء راجع مرجع أخطاء هيئة الزكاة والضريبة والجمارك في الفوترة.

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

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

ما العناصر التي يجب أن تحويها كتلة SignedProperties؟
يجب أن تحوي xades:SigningTime الذي يسجّل وقت التوقيع، و xades:SigningCertificate الذي يثبّت الشهادة عبر بصمة موجزة (CertDigest) ومرجع المُصدِر والرقم التسلسلي (IssuerSerial). نقص أي عنصر منها ينتج الخطأ نفسه.

لماذا يظهر الخطأ رغم وجود كتلة SignedProperties في الملف؟
لأن وجود الكتلة لا يكفي. يجب أن يشير إليها مرجع (ds:Reference) داخل ds:SignedInfo بقيمة URI مطابقة لـ Id الكتلة وبسمة Type الصحيحة. بدون هذا المرجع لا يعدّها التحقق جزءًا من التوقيع.

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

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

كيف يساعد قيود في تفادي هذا الخطأ؟
يبني قيود توقيع XAdES كاملًا تلقائيًا: يولّد كتلة الخصائص الموقّعة بعناصرها، ويربطها بالتوقيع عبر المرجع الصحيح، ويوقّع بشهادة CSID المُدارة داخل النظام. فلا تحتاج إلى بناء التوقيع يدويًا، ولا يصلك الخطأ 1019.