عند بناء تكامل مع منصة فاتورة لإصدار الفواتير الإلكترونية ومقاصتها، لا يكفي أن «تنجح» الطلبات في الأحوال المثالية. النظام الحقيقي يتعامل مع رفض الفواتير، والتحذيرات، وانقطاع الاتصال، والشهادات المنتهية. هذا الدليل يشرح كيف تعالج أخطاء واجهة برمجة التطبيقات (API) القادمة من منصة فاتورة بشكل منهجي: من رموز حالة HTTP، إلى بنية استجابة الأخطاء والتحذيرات، إلى تمييز الفواتير المقبولة مع تحذير عن المرفوضة، وصولاً إلى كيفية تسجيل الخطأ وعرضه على المستخدم وإصلاحه. الهدف أن يخرج المطوّر بنموذج واضح لمعالجة الأخطاء يصمد في بيئة الإنتاج.
هذا المقال جزء من مركز المطوّرين ضمن الفاتورة الإلكترونية من قيود. ويفترض أنك قرأت نقاط نهاية API لمنصة فاتورة وتعرف الفرق بين واجهة المقاصة وواجهة الإبلاغ، إضافة إلى قواعد التحقق من الفاتورة التي تحدد متى تُرفض الفاتورة من الأساس.
لماذا تحتاج إلى استراتيجية معالجة أخطاء مكتملة
في تكامل الفوترة الإلكترونية، الخطأ ليس استثناءً نادراً بل حدث متوقع يجب التخطيط له. الفاتورة قد تُرفض لأن رقم ضريبة القيمة المضافة غير صحيح، أو لأن مجموع البنود لا يساوي الإجمالي، أو لأن ترتيب التجزئة (hash) المتسلسل انكسر. كل حالة من هذه تحتاج رد فعل مختلف.
المطوّر الذي يعالج الاستجابة الناجحة فقط يبني نظاماً هشاً. أول فاتورة تُرفض في الإنتاج توقف خط الإصدار بالكامل، أو الأسوأ: تمر الفاتورة المرفوضة كأنها نجحت، فيكتشف العميل المشكلة بعد أيام عند مراجعة سجلاته لدى هيئة الزكاة والضريبة والجمارك (ZATCA). معالجة الأخطاء الجيدة تمنع هذين السيناريوهين معاً.
تبدأ الاستراتيجية الناضجة بثلاثة أسئلة لكل استجابة تصل من منصة فاتورة. أولاً: ما رمز حالة HTTP؟ هذا يحدد الفئة العامة للنتيجة. ثانياً: ما حالة الفاتورة داخل جسم الاستجابة (الحقل status)؟ هذا يميز القبول من القبول مع تحذير من الرفض. ثالثاً: ما تفاصيل نتائج التحقق (validationResults)؟ هذه تخبرك بالضبط ما الذي يجب إصلاحه.
رموز حالة HTTP من منصة فاتورة
أول طبقة تصنيف هي رمز حالة HTTP. لكل رمز معنى يحدد كيف يتصرف نظامك. لا تعالج كل رمز بالطريقة نفسها، فإعادة المحاولة على خطأ في بيانات الفاتورة مضيعة للموارد، بينما عدم إعادة المحاولة على خطأ خادم مؤقت يخسر فواتير صحيحة.
الجدول التالي يلخص الرموز التي ستراها فعلياً عند التكامل مع واجهة المقاصة (Clearance) وواجهة الإبلاغ (Reporting):
| الرمز | المعنى | التصرف المطلوب |
|---|---|---|
| 200 OK | قُبلت الفاتورة ومُوقّعت من الهيئة. واجهة المقاصة تُرجع الفاتورة المُصدّقة. | خزّن الفاتورة المُصدّقة ورمز الاستجابة السريعة (QR). أكمل العملية. |
| 202 Accepted | قُبلت الفاتورة مع وجود تحذيرات (cleared with warnings). الفاتورة صالحة لكن تحتوي ملاحظات. | خزّن الفاتورة، سجّل التحذيرات، ونبّه الفريق المعني لمراجعتها لاحقاً. |
| 400 Bad Request | الطلب نفسه مشوّه: JSON غير صالح، أو حقل إلزامي مفقود في غلاف الطلب. | لا تُعد المحاولة بالبيانات نفسها. أصلح بنية الطلب ثم أرسل من جديد. |
| 401 Unauthorized | بيانات المصادقة غير صحيحة أو منتهية. شهادة CSID غير صالحة أو الرمز المميز انتهى. | جدّد بيانات الاعتماد. تحقق من صلاحية شهادة CSID قبل إعادة الإرسال. |
| 422 Unprocessable Entity | الطلب صحيح بنيوياً لكن الفاتورة فشلت في قواعد التحقق. هذه أكثر حالة ستراها. | اقرأ validationResults، اعرض الأخطاء، أصلح بيانات الفاتورة. لا تُعد المحاولة قبل الإصلاح. |
| 429 Too Many Requests | تجاوزت حد المعدل المسموح للطلبات خلال نافذة زمنية. | أوقف الإرسال مؤقتاً واحترم ترويسة إعادة المحاولة. راجع قسم حدود المعدل لاحقاً. |
| 500 / 502 / 503 | خطأ في خادم المنصة أو عدم توفره المؤقت. ليست مشكلة في فاتورتك. | أعد المحاولة وفق منطق تراجع أسّي. الفاتورة صحيحة، الخطأ مؤقت. |
القاعدة الجوهرية في التصنيف: أخطاء فئة 4xx مسؤوليتك أنت (بيانات أو مصادقة أو حد معدل)، وأخطاء فئة 5xx مسؤولية المنصة (خادم مؤقت). الفئتان تتطلبان منطقين مختلفين تماماً. أخطاء 4xx (باستثناء 429) لا يُعاد إرسالها بالبيانات نفسها لأنها ستفشل مجدداً، بينما أخطاء 5xx و429 مرشحة لإعادة المحاولة لأن البيانات صحيحة والمشكلة عابرة.
انتبه إلى الفرق العملي بين رمزي 200 و202. كلاهما يعني أن الفاتورة صالحة ومُصدَّقة، لكن 202 يحمل إشارة ضمنية إلى وجود ملاحظة تستحق المراجعة. كثير من المطوّرين يعاملون كل رمز في نطاق 2xx كنجاح تام ويتجاهلون التحذيرات، فتتراكم ملاحظات لا أحد يقرأها. الأفضل أن تميّز الرمزين في منطقك: 200 يمر بصمت، و202 يمر لكن يُسجَّل تحذيره ويُعرض في لوحة مراجعة دورية.
كذلك لا تخلط بين 400 و422 رغم أن كليهما من فئة الأربعمئة. الرمز 400 يعني أن الطلب نفسه مكسور بنيوياً: نص JSON غير صالح، أو ترويسة مفقودة، أو حقل غلاف الطلب غائب، أي أن المنصة لم تستطع حتى قراءة الفاتورة. أما 422 فيعني أن المنصة قرأت الفاتورة وفهمتها لكنها فشلت في قاعدة عمل. التمييز بينهما يوجّه الإصلاح: 400 يُصلَح في طبقة بناء الطلب، و422 يُصلَح في بيانات الفاتورة نفسها.
صورة توضيحية: شجرة قرار رموز حالة HTTP
| الرمز | الإجراء |
|---|---|
| 2xx | نجاح: تابع (قد يوجد تحذير) |
| 4xx | خطأ في الطلب: صحّح أو جدّد المصادقة |
| 5xx | خطأ خادم: أعد المحاولة لاحقاً |
بنية استجابة الأخطاء والتحذيرات
رمز HTTP يخبرك بالفئة العامة، لكن التفاصيل الدقيقة تأتي في جسم الاستجابة. تتبع منصة فاتورة بنية موحّدة لنتائج التحقق، ومعرفة هذه البنية هي مفتاح معالجة الأخطاء بدقة. كل استجابة تحمل حقل status على المستوى الأعلى، وداخل validationResults قائمتان منفصلتان: errorMessages للأخطاء التي تمنع القبول، وwarningMessages للتحذيرات التي لا تمنعه.
إليك مثالاً على استجابة فاتورة مرفوضة بسبب فشل التحقق (رمز HTTP يرافقها 422):
لاحظ العناصر الأساسية. الحقل status على مستوى validationResults يأخذ قيمة ERROR هنا لأن هناك خطأ واحد على الأقل. القائمة errorMessages تحوي كائناً لكل خطأ، وكل كائن يحمل أربعة حقول مهمة: type (نوع الرسالة)، وcode (رمز القاعدة المخالَفة)، وcategory (فئة القاعدة)، وmessage (الوصف القابل للقراءة). الحقل clearanceStatus يؤكد أن الفاتورة لم تُصدَّق.
الحقل code هو الأهم برمجياً. كل قاعدة تحقق لها رمز فريد ثابت لا يتغير، مثل BR-KSA-EN16931-08 أو BR-CO-15. اعتمد على هذا الرمز في منطقك، لا على نص الرسالة، لأن النص قد يتغير صياغةً بين إصدارات المنصة بينما الرمز ثابت. ابنِ خريطة في نظامك تربط كل رمز بإجراء إصلاح محدد ورسالة واضحة للمستخدم.
الحقول الأساسية في كائن الخطأ
لكل كائن في قائمة errorMessages أو warningMessages الحقول التالية:
- type: نوع الرسالة، يأخذ قيمة ERROR أو WARNING. يحدد ما إذا كانت الرسالة مانعة للقبول أم لا.
- code: الرمز الفريد للقاعدة المخالَفة. ثابت بين الإصدارات، وعليه تبني منطقك.
- category: فئة القاعدة، مثل BR-KSA للقواعد الخاصة بالسعودية، أو EN16931 للمعيار الأوروبي الذي تبنّته الهيئة.
- message: وصف نصي قابل للقراءة. مفيد للعرض على المستخدم لكنه ليس مرجعاً برمجياً ثابتاً.
صورة توضيحية: تشريح كائن الخطأ في validationResults
type: نوع الرسالة (خطأ/تحذير)
code: رمز الخطأ (مفتاح المنطق)
category: فئة الخطأ
message: وصف للقراءة البشرية
التمييز بين التحذيرات والرفض
أكثر نقطة يخطئ فيها المطوّرون حديثو العهد بمنصة فاتورة هي الخلط بين «مقبولة مع تحذير» و«مرفوضة». الفرق جوهري وله أثر مباشر على ما يجب فعله بالفاتورة.
الفاتورة المقبولة مع تحذير صالحة قانونياً ومُصدَّقة من الهيئة. تصلك برمز HTTP رقمه 202، وحقل status فيها يكون WARNING وليس ERROR، وقائمة errorMessages فارغة بينما warningMessages تحوي ملاحظة أو أكثر. هذه الفاتورة تُسلَّم للمشتري وتُخزَّن كمصدَّقة. التحذير مجرد تنبيه لمراجعة لاحقة، لا يمنع شيئاً.
أما الفاتورة المرفوضة فتصلك برمز HTTP رقمه 422، وحقل status فيها ERROR، وقائمة errorMessages تحوي خطأً واحداً على الأقل. هذه الفاتورة لم تُصدَّق، ولا يجوز تسليمها للمشتري، ويجب إصلاح بياناتها وإعادة إرسالها.
إليك مثالاً على استجابة مقبولة مع تحذير:
لاحظ الفروق الثلاثة عن المثال السابق: status هنا WARNING لا ERROR، وerrorMessages فارغة، وclearanceStatus يساوي CLEARED. هذه الفاتورة نجحت رغم وجود ملاحظة. القاعدة العملية: اعتمد على حقل status وقائمة errorMessages معاً لاتخاذ القرار. إذا كانت errorMessages غير فارغة، الفاتورة مرفوضة بصرف النظر عن أي شيء آخر. إذا كانت فارغة وكانت warningMessages تحوي عناصر، الفاتورة مقبولة مع تحذير.
| المعيار | مقبولة | مقبولة مع تحذير | مرفوضة |
|---|---|---|---|
| رمز HTTP | 200 | 202 | 422 |
| status | PASS | WARNING | ERROR |
| errorMessages | فارغة | فارغة | تحوي عناصر |
| warningMessages | فارغة | تحوي عناصر | قد تحوي |
| clearanceStatus | CLEARED | CLEARED | NOT_CLEARED |
| تُسلَّم للمشتري؟ | نعم | نعم | لا |
صورة توضيحية: مقارنة بصرية بين القبول والقبول مع تحذير والرفض
| المعيار | مقبولة (2xx) | مرفوضة (422) |
|---|---|---|
| الحالة | معتمَدة/مُبلَّغة | مرفوضة |
| التحذير | قد يوجد للتصحيح لاحقاً | أخطاء توقف القبول |
| التسليم | تُسلَّم/تُبلَّغ | لا تُسلَّم حتى التصحيح |
فئات الأخطاء الشائعة
معظم حالات الرفض تتكرر ضمن عدد محدود من الفئات. معرفتها مسبقاً تختصر وقت التشخيص وتساعدك على بناء رسائل إصلاح جاهزة لكل فئة. فيما يلي أكثر الفئات شيوعاً عند التكامل مع منصة فاتورة.
أخطاء حسابية في المبالغ. هذه أكثر الفئات شيوعاً. تقع عندما لا يتطابق مجموع البنود مع الإجمالي، أو لا يساوي مبلغ الضريبة المعلن مجموع ضرائب البنود الفعلية. السبب غالباً تقريب عشري خاطئ. أصلحها بحساب المجاميع من البنود نفسها بدقة عشرية موحّدة بدلاً من إدخالها يدوياً.
أخطاء أرقام التسجيل الضريبي. تقع عندما يكون رقم ضريبة القيمة المضافة للبائع أو المشتري غير صحيح أو لا يطابق التنسيق المطلوب (خمسة عشر رقماً تبدأ وتنتهي بثلاثة). تحقق من الرقم قبل الإرسال بقاعدة تحقق محلية لتوفير دورة كاملة من الرفض.
أخطاء سلسلة التجزئة (hash chain). منصة فاتورة تربط كل فاتورة بتجزئة الفاتورة السابقة لضمان سلامة التسلسل. إذا أُرسلت الفواتير خارج الترتيب، أو فُقدت تجزئة سابقة، يُرفض التسلسل. أصلحها بضمان الإرسال التسلسلي وعدم تخطّي أي فاتورة في السلسلة.
أخطاء الشهادة والتوقيع. تقع عندما تكون شهادة CSID منتهية أو غير صالحة، أو عندما يفشل التوقيع الرقمي. هذه الفئة ترافقها غالباً رموز HTTP من نوع 401. الحل تجديد شهادة CSID والتأكد من سلامة مفتاح التوقيع.
أخطاء الحقول الإلزامية المفقودة. تقع عند غياب حقل تتطلبه قواعد التحقق، مثل تاريخ الإصدار أو نوع الفاتورة أو معرّف الفاتورة الفريد (UUID). راجع قواعد التحقق من الفاتورة للقائمة الكاملة بالحقول الإلزامية وشروطها.
أخطاء صيغ التاريخ والوقت. تقع عندما لا يتطابق تنسيق طابع الفاتورة الزمني مع الصيغة المطلوبة، أو عندما يكون تاريخ الإصدار في المستقبل، أو عندما يسبق تاريخ التوريد تاريخ الإصدار بشكل غير منطقي. هذه الفئة كثيرة الظهور عند التعامل مع مناطق زمنية مختلفة. وحّد جميع الطوابع الزمنية على توقيت موحّد قبل البناء.
أخطاء تصنيف الإعفاء والنسب الضريبية. تقع عندما يُعلَن بند ما معفى أو خاضع لنسبة صفرية دون ذكر سبب الإعفاء المطلوب، أو عندما تختلف النسبة المطبّقة عن النسبة المعلنة للفئة الضريبية. أصلحها بربط كل بند بفئته الضريبية الصحيحة وسبب الإعفاء حين يلزم.
الفائدة العملية من حفظ هذه الفئات أنها تتيح لك بناء خريطة إصلاح جاهزة. لكل رمز قاعدة تربطه بفئة، ولكل فئة رسالة مستخدم واضحة وخطوة إصلاح محددة. بهذا يتحول التعامل مع الرفض من تشخيص يدوي كل مرة إلى استجابة شبه آلية تعرض للمستخدم بالضبط ما يجب فعله. ومع تراكم سجلاتك تكتشف أي الفئات أكثر تكراراً عندك، فتعالج جذرها في طبقة البناء بدلاً من تكرار الإصلاح اليدوي.
دع قيود يتولّى التوقيع والمقاصة والتعامل مع الأخطاء
يدير قيود شهادة CSID والتوقيع والمقاصة الفورية مع منصة فاتورة تلقائياً، ويعرض أخطاء التحقق بلغة واضحة دون أن تبني طبقة معالجة الأخطاء بنفسك.
كيف تسجّل الخطأ وتعرضه على المستخدم
اكتشاف الخطأ نصف المهمة. النصف الآخر أن تسجّله بشكل يسمح بالتشخيص لاحقاً، وأن تعرضه على المستخدم بلغة يفهمها. التسجيل الجيد يفرّق بين تكامل يمكن صيانته وآخر يتحول إلى صندوق أسود مغلق.
في طبقة السجلات، خزّن لكل فاتورة مرفوضة الحزمة التشخيصية الكاملة: معرّف الفاتورة، ورمز حالة HTTP، وقائمة رموز الأخطاء (code) كاملة، وطابع زمني، ومعرّف الطلب إن وُجد. لا تسجّل نص الرسالة فقط، لأن الرمز هو ما تبحث عنه عند تجميع الأخطاء المتكررة وتحليل أنماطها.
في طبقة العرض للمستخدم، لا تُظهر رمز الخطأ الخام مثل BR-KSA-EN16931-08 للمستخدم النهائي. ترجم كل رمز إلى رسالة عربية واضحة تخبر المستخدم بما حدث وكيف يصلحه. مثلاً، بدلاً من عرض الرمز، اعرض: «إجمالي الضريبة في الفاتورة لا يطابق مجموع ضرائب البنود. راجع مبالغ البنود.» هذه الرسالة قابلة للتنفيذ، والرمز الخام ليس كذلك.
التمييز بين طبقتي التسجيل والعرض مهم. السجل التقني للمطوّر يحتوي الرموز والتفاصيل الكاملة للتشخيص، أما واجهة المستخدم فتعرض رسالة مبسّطة قابلة للتنفيذ. خلط الطبقتين يربك المستخدم بتفاصيل تقنية لا تعنيه، أو يحرم المطوّر من التفاصيل التي يحتاجها.
احرص على ألا تسجّل بيانات حساسة في السجلات. جسم الفاتورة قد يحتوي معلومات تجارية وأرقام تسجيل ضريبي، فلا تطبع الحمولة الكاملة في سجلات مشتركة أو خدمات مراقبة خارجية. اكتفِ بالحزمة التشخيصية: المعرّفات والرموز والطوابع الزمنية. هذا يوازن بين قابلية التشخيص وحماية بيانات العميل.
أضف إلى ذلك مستوى خطورة لكل سجل. الرفض بسبب بيانات خطأ مستوى تحذير يحتاج تدخلاً، أما تكرار أخطاء الخادم من فئة الخمسمئة عبر فواتير كثيرة فمستوى تنبيه عاجل يستدعي مراجعة حالة المنصة. تصنيف السجلات حسب الخطورة يجعل لوحة المراقبة قابلة للقراءة بدل أن تغرق في رسائل متساوية الوزن.
مثال على بنية سجل تشخيصي مفيد:
هذه البنية تجيب على كل سؤال تشخيصي: أي فاتورة، أي رمز HTTP، أي قواعد فشلت، متى، وما الإجراء الذي اتُّخذ. عند تجميع آلاف السجلات يصبح بإمكانك حساب أكثر رموز الأخطاء تكراراً ومعالجة سببها الجذري بدلاً من علاج الأعراض فاتورةً فاتورةً.
كيف تصلح الخطأ ثم تعيد الإرسال
بعد التسجيل والعرض تأتي خطوة الإصلاح. هنا يظهر الفرق بين فئات HTTP بوضوح، لأن كل فئة لها مسار إصلاح مختلف.
أخطاء بيانات الفاتورة (422) تتطلب تصحيح البيانات قبل أي إعادة إرسال. لا فائدة من إعادة المحاولة بالفاتورة نفسها لأنها ستُرفض بالطريقة نفسها. صحّح المبالغ أو رقم التسجيل الضريبي أو الحقل المفقود، ثم أرسل الفاتورة كطلب جديد. تذكّر أن تجزئة الفاتورة ستتغير بعد التصحيح، فتعامل معها كفاتورة جديدة في السلسلة.
أخطاء المصادقة (401) تتطلب تجديد بيانات الاعتماد. تحقق من صلاحية شهادة CSID، وجدّدها إن انتهت، ثم أعد الإرسال. هذه الأخطاء لا علاقة لها ببيانات الفاتورة، فالفاتورة نفسها صحيحة.
أخطاء الخادم المؤقتة (5xx) وأخطاء تجاوز حد المعدل (429) تتطلب إعادة محاولة منظَّمة بفواصل زمنية متزايدة، لأن الفاتورة صحيحة والمشكلة عابرة. لكن إعادة المحاولة لها قواعد دقيقة تخص الفواصل الزمنية وعدد المحاولات وتفادي الإرسال المكرر، وهذا موضوع مستقل بذاته.
لتفادي الرفض من الأساس، طبّق طبقة تحقق محلية قبل الإرسال تفحص المجاميع وأرقام التسجيل والحقول الإلزامية. هذه الطبقة تلتقط الجزء الأكبر من أخطاء 422 قبل أن تكلّفك دورة شبكية كاملة. اعتبرها خط الدفاع الأول، ومعالجة استجابة المنصة خط الدفاع الثاني.
أخيراً، اجعل مسار الإصلاح قابلاً للتتبّع للمستخدم نفسه. عندما تُرفض فاتورة، لا تتركها في حالة غامضة، بل اعرض حالتها بوضوح: مرفوضة بانتظار الإصلاح، أو قيد إعادة الإرسال، أو مُصدَّقة بعد التصحيح. المستخدم الذي يرى رحلة فاتورته كاملة يثق بالنظام ويتصرف بسرعة. أما الفاتورة التي تختفي بصمت بعد الرفض فتتحول إلى مشكلة تظهر متأخرة عند المطابقة الضريبية، وهي أصعب وقت لاكتشاف خطأ.
تنبّه إلى نقطة دقيقة عند إعادة الإرسال: لا ترسل الفاتورة المرفوضة مرتين دون تغيير. كل إرسال يستهلك من حد المعدل، وقد يربك سجلاتك إن لم تربط المحاولة الجديدة بالأصلية. اجعل لكل فاتورة معرّفاً داخلياً ثابتاً تتتبّع به محاولاتها كلها، بحيث يبقى لديك خيط واضح يربط الفاتورة الأصلية بمحاولة الإصلاح الناجحة.
كذلك راقب الحالة الوسيطة التي تنتظر فيها استجابة لم تصل. إذا انقطع الاتصال بعد إرسال الفاتورة وقبل وصول الرد، قد تكون الفاتورة قد عولجت فعلاً لدى المنصة دون أن تعرف نتيجتها. في هذه الحالة لا تُعد الإرسال الأعمى، بل استعلم عن حالة الفاتورة أولاً بمعرّفها الفريد إن أتاحت المنصة ذلك، لتتفادى ازدواج الإصدار. هذه الحالات الحدّية هي ما يفصل التكامل الناضج عن التكامل الذي يعمل في المختبر فقط.
ما يتولّاه قيود نيابة عنك
بناء طبقة معالجة أخطاء كاملة من الصفر عمل كبير: تصنيف رموز HTTP، وتفسير validationResults، وإدارة شهادة CSID، وترجمة الرموز إلى رسائل عربية واضحة، وبناء طبقة تحقق محلية. قيود يتولّى هذه الطبقة كاملة نيابة عن المستخدم.
يدير قيود شهادة CSID والتوقيع الرقمي تلقائياً، ويرسل كل فاتورة B2B للمقاصة الفورية مع منصة فاتورة، ويُبلغ عن فواتير B2C المبسّطة خلال أربع وعشرين ساعة. عند فشل التحقق، يعرض قيود الخطأ بلغة عربية واضحة تخبر المستخدم بما يجب إصلاحه دون أن يضطر لفهم رموز القواعد الخام.
هذا لا يعني أن المطوّر لا يحتاج لفهم معالجة الأخطاء. من يبني تكاملاً مباشراً مع المنصة، أو يربط نظاماً خارجياً عبر واجهة قيود، يستفيد من فهم هذه البنية ليفسّر ما يصله من استجابات. لكن المستخدم النهائي الذي يصدر فواتيره عبر قيود يحصل على هذه الطبقة جاهزة دون أن يكتب سطر كود واحد.
يستحق التذكير أن قيود لا يسجّل العميل لدى الهيئة نيابة عنه. تسجيل شهادة CSID لدى الهيئة خطوة يقوم بها العميل بنفسه، ويرشده قيود خلالها. كذلك لا يقدّم قيود إقرار ضريبة القيمة المضافة نيابة عن العميل، بل يولّد بيانات الإقرار ليقدّمها العميل عبر بوابة الهيئة.
الخطوات التالية في مركز المطوّرين
بعد إتقان معالجة الأخطاء، الموضوعان المكمّلان مباشرة هما منطق إعادة المحاولة وحدود المعدل. منطق إعادة المحاولة (Retry Logic) يشرح كيف تعيد إرسال الفواتير الصحيحة عند أخطاء الخادم المؤقتة بفواصل زمنية متزايدة دون إغراق المنصة أو تكرار الإرسال. وحدود المعدل (Rate Limits) تشرح عدد الطلبات المسموح بها في النافذة الزمنية وكيف تحترم ترويسات إعادة المحاولة عند الوصول إلى رمز 429. سنربط هذين الدليلين هنا فور نشرهما.
للمراجعة، تأكد أنك ملمّ بأساس التكامل عبر نقاط نهاية API لمنصة فاتورة، وبشروط قبول الفاتورة عبر قواعد التحقق من الفاتورة. هذان الدليلان مع هذا المقال يكوّنان الأساس المتين لأي تكامل ناضج مع منصة فاتورة.
خلاصة عملية
معالجة الأخطاء في تكامل منصة فاتورة تقوم على ثلاث طبقات قرار. الطبقة الأولى رمز حالة HTTP الذي يحدد الفئة العامة ومسؤوليتها: 4xx مسؤوليتك، و5xx مسؤولية المنصة. الطبقة الثانية حقل status وقائمتا errorMessages وwarningMessages اللتان تميّزان القبول من القبول مع تحذير من الرفض. الطبقة الثالثة رمز القاعدة (code) الثابت الذي تبني عليه منطق الإصلاح ورسائل المستخدم.
التكامل الناضج يسجّل الرموز لا النصوص، ويترجمها إلى رسائل عربية قابلة للتنفيذ، ويميّز إعادة المحاولة المشروعة (5xx و429) عن الإصلاح الإلزامي (422 و401)، ويبني طبقة تحقق محلية تلتقط الأخطاء قبل الإرسال. من يفضّل عدم بناء هذه الطبقة بنفسه يحصل عليها جاهزة عبر قيود.