Qoyod
الأسعار

 دليل المعرفة

أخطاء التوقيع في الفاتورة الإلكترونية

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

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

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

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

كيف يعمل الختم التشفيري قبل أن نتحدث عن أخطائه

قبل تشخيص أي خطأ، لا بد من صورة واضحة عن آلية التوقيع. الفاتورة الإلكترونية في المرحلة الثانية ليست ملف PDF موقَّعًا. هي ملف XML بصيغة UBL 2.1 يُوقَّع رقميًا بمعيار XAdES، ويُدرَج التوقيع داخل امتداد قياسي اسمه UBLExtensions.

التوقيع يُحسب على شكل مختصَر تشفيري (hash) لمحتوى الفاتورة، ثم يُشفَّر هذا المختصَر بالمفتاح الخاص للمُصدِّر. المفتاح الخاص مرتبط بشهادة رقمية تصدرها الهيئة اسمها معرّف الختم التشفيري (CSID). تتحقق منصة فاتورة من التوقيع باستخدام المفتاح العام المرافق للشهادة. إذا اختلَّ أي عنصر في هذه السلسلة، يُرفض الختم.

الخوارزمية المعتمدة للتوقيع هي ECDSA على المنحنى الإهليلجي secp256k1، مع دالة المختصَر SHA-256. هذه ليست تفاصيل اختيارية. الهيئة تفرض هذه المعطيات بدقة، وأي انحراف عنها يُنتج توقيعًا ترفضه المنصة حتى لو كان صحيحًا حسابيًا. لشرح أعمق لهذه الآلية راجع المواصفة التقنية للتوقيع الرقمي.

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

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

القراءة الصحيحة لرسالة خطأ التوقيع

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

ZATCA clearance response

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "invalid-signature",
        "category": "CRYPTOGRAPHIC_STAMP",
        "message": "The signature value does not match the invoice hash."
      }
    ]
  },
  "clearanceStatus": "NOT_CLEARED"
}

انتبه إلى ثلاثة عناصر في كل رسالة. الحقل code يحدد نوع الخطأ بدقة. الحقل category يخبرك أن الخطأ في طبقة الختم لا في بيانات الفاتورة. والحقل clearanceStatus يؤكد أن الفاتورة لم تُعتمد. كل خطأ نناقشه أدناه يظهر بهذا الشكل، ويتغيّر فيه رمز code فقط.

خريطة أخطاء التوقيع الثمانية

أخطاء التوقيع في ثلاث مجموعات
تصنيف أخطاء التوقيع لتسريع التشخيص.
مجموعات الخطأ

الشهادة: CSID منتهية أو خلط امتثال/إنتاج

الخوارزمية: ECDSA/secp256k1/SHA-256 خاطئة

البنية: XAdES ناقص أو ترتيب عناصر خاطئ

المصدر: توقيع على شكل غير قانوني (Canonical)

حدّد المجموعة أولاً ثم انزل للخطأ المحدّد.

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

الخطأ الأول: التوقيع غير صالح (invalid-signature)

العَرَض: يردّ نظام الهيئة برمز invalid-signature ورسالة تفيد أن قيمة التوقيع لا تطابق مختصَر الفاتورة. الفاتورة تُرفض ولا تُعتمد.

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

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

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

الخطأ الثاني: التوقيع على شكل قانوني خاطئ (signed over wrong canonical form)

العَرَض: رمز invalid-signature نفسه، لكن الفاتورة لم تُمسّ بعد التوقيع، والتوقيع ما زال يُرفض. هذا هو الخطأ الأخبث لأنه يبدو وكأن كل شيء سليم.

السبب الجذري: المختصَر التشفيري لا يُحسب على نص XML كما تراه، بل على شكله القانوني (canonical form) بعد تطبيق خوارزمية التقنين التي تفرضها الهيئة. لو حسبت التوقيع على النص الخام بدل الشكل القانوني، أو استخدمت خوارزمية تقنين مختلفة، سينتج مختصَر صحيح حسابيًا لكنه لا يطابق ما تحسبه المنصة. النتيجة رفض رغم أن التوقيع «صحيح» من منظورك.

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

لماذا يفشل التوقيع رغم صحته الحسابية

التوقيع على النص الخام مقابل الشكل القانوني
لماذا يجب التوقيع على الشكل القانوني (C14N).
المعيار خطأ: النص الخام صحيح: الشكل القانوني
المُدخل XML كما هو بعد التوحيد C14N
النتيجة توقيع غير صالح توقيع صالح
السبب فروق مسافات/ترتيب تمثيل موحّد ثابت
وقّع دائماً على الشكل القانوني الموحّد للفاتورة.

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

الخطأ الثالث: شهادة CSID منتهية أو غير معروفة

العَرَض: رمز يشير إلى أن الشهادة غير صالحة أو منتهية، مثل رسالة عن شهادة غير معروفة لدى المنصة أو خارج فترة صلاحيتها. الفاتورة تُرفض على مستوى الهوية لا التوقيع.

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

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

الخطأ الرابع: الخلط بين شهادة الامتثال وشهادة الإنتاج

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

السبب الجذري: توجد شهادتان متمايزتان في رحلة التكامل. شهادة الامتثال (Compliance CSID) تُستخدم في بيئة المحاكاة لاجتياز اختبارات التوافق. وشهادة الإنتاج (Production CSID) تُستخدم في البيئة الفعلية بعد اجتياز الامتثال. التوقيع في بيئة الإنتاج بشهادة الامتثال، أو إرسال فواتير اختبار بشهادة الإنتاج، يُنتج رفضًا مباشرًا لأن البيئة لا تقبل إلا شهادتها.

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

ابدأ اليوم

دع قيود يتولى الختم التشفيري نيابةً عنك

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

ابدأ تجربتك المجانية وأصدر فواتير مختومة بلا أخطاء

الخطأ الخامس: معطيات المنحنى الإهليلجي غير صحيحة (wrong ECDSA / secp256k1 params)

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

السبب الجذري: الهيئة تفرض خوارزمية ECDSA على المنحنى secp256k1 تحديدًا. بعض المكتبات البرمجية تستخدم منحنى افتراضيًا مختلفًا مثل secp256r1 أو prime256v1، فيُولَّد مفتاح صحيح تقنيًا لكنه على منحنى غير معتمد. كذلك قد تُحسب دالة المختصَر بخوارزمية غير SHA-256، فيُرفض التوقيع. النتيجة مفتاح لا تقبله المنصة رغم أنه سليم في حد ذاته.

الإصلاح: اضبط مكتبة التشفير على المنحنى secp256k1 صراحةً عند توليد المفتاح، ولا تعتمد على الافتراضي. تأكد أن دالة المختصَر هي SHA-256. عند توليد طلب الشهادة (CSR)، حدّد هذه المعطيات بدقة كي تصدر الشهادة على المنحنى الصحيح من البداية. هذا الإعداد يُضبط مرة واحدة عند التكامل، ويتولاه النظام المعتمد آليًا.

الخطأ السادس: الخصائص الموقَّعة (XAdES) ناقصة

العَرَض: رمز خطأ يشير إلى أن خصائص التوقيع الموقَّعة ناقصة أو غير مكتملة، مثل غياب مختصَر الشهادة أو ختم الوقت داخل بنية XAdES.

السبب الجذري: معيار XAdES يفرض إدراج مجموعة من الخصائص الموقَّعة (Signed Properties) داخل التوقيع، أبرزها مختصَر الشهادة المُصدِّرة ووقت التوقيع. هذه الخصائص جزء من المحتوى الموقَّع، أي أنها تدخل في حساب المختصَر. إذا أُهملت إحداها أو وُضعت خارج نطاق التوقيع، يعتبر النظام البنية ناقصة ويرفضها.

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

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

الخطأ السابع: ترتيب عناصر التوقيع داخل UBLExtensions خاطئ

العَرَض: رمز خطأ يشير إلى بنية امتداد غير صالحة أو عنصر توقيع في موضع غير متوقع. الفاتورة تُرفض قبل التحقق من التوقيع الحسابي.

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

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

قائمة تحقق سريعة قبل إرسال الفاتورة الموقَّعة

تحقّق قبل الإرسال من التوقيع
ست نقاط تمنع أخطاء التوقيع قبل الإرسال.
فحص ما قبل الإرسال

شهادة CSID سارية وللبيئة الصحيحة

معاملات ECDSA/secp256k1/SHA-256 صحيحة

التوحيد القياسي C14N مطبّق

XAdES (وقت التوقيع وبصمة الشهادة) مكتمل

ترتيب عناصر UBLExtensions صحيح

هوية الموقّع تطابق الشهادة

اجتياز النقاط الست يمنع معظم أخطاء التوقيع.

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

الخطأ الثامن: عدم تطابق هوية المُصدِّر في الشهادة

العَرَض: رسالة تشير إلى أن بيانات المُصدِّر في الفاتورة لا تطابق بيانات الشهادة، مثل اختلاف رقم التسجيل الضريبي بين الفاتورة والشهادة.

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

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

كيف يساعدك قيود في تفادي أخطاء التوقيع من الأساس

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

يدير قيود معرّف الختم التشفيري (CSID) وتجديده تلقائيًا، فلا تتعامل مع شهادة منتهية أو غير مسجَّلة. ويولّد ملف XML بصيغة UBL 2.1 ويوقّعه بالخوارزمية والمعطيات الصحيحة (ECDSA على secp256k1 مع SHA-256) دون أي ضبط يدوي. كما يبني بنية XAdES كاملة بخصائصها الموقَّعة، ويضع التوقيع في موضعه الصحيح داخل الامتداد القياسي.

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

جدول مرجعي: الأخطاء الثمانية في لمحة

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

الخطأ العائلة الإصلاح المختصر
التوقيع غير صالح حسابي لا تعدّل الملف بعد التوقيع
شكل قانوني خاطئ حسابي طبّق التقنين القياسي قبل المختصَر
شهادة منتهية أو غير معروفة شهادة جدّد الشهادة وتأكد من تسجيلها
خلط الامتثال بالإنتاج شهادة شهادة لكل بيئة على حدة
معطيات المنحنى خاطئة حسابي secp256k1 مع SHA-256 صراحةً
خصائص XAdES ناقصة بنية أكمل الخصائص الموقَّعة الإلزامية
ترتيب العناصر خاطئ بنية اتبع ترتيب المواصفة حرفيًا
هوية مُصدِّر غير متطابقة شهادة طابق رقم التسجيل مع الشهادة

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

لماذا يتكرر هذا في التكامل اليدوي تحديدًا

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

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

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

منهجية تشخيص أي خطأ توقيع في ثلاث خطوات

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

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

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

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

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

مركز المساعدة

لم تجد ما تبحث عنه؟

لا تقلق، لدينا المزيد من أدوات المساعدة.

ندوات مباشرة يقدمها فريق قيود لمساعدتك في استخدام البرنامج بسهولة والرد على أسئلتك.

تعرّف على أحدث تحديثات فيود والتحسينات المستمرة والخصائص الجديدة في مكان واحد.

فريقنا جاهز لمساعدتك وتقديم الدعم الفوري لأي مشكلة تواجهها على مدار الساعة