أفضل ممارسات التكامل مع منصة فاتورة

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

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

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

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

لماذا تحتاج أصلًا إلى أفضل ممارسات لا مجرّد تكامل يعمل؟

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

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

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

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

أمان بيانات الاعتماد: حماية شهادة CSID

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

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

القاعدة الثانية: افصل بيانات الاعتماد بين البيئات فصلًا كاملًا. شهادة الامتثال (Compliance CSID) للاختبار، وشهادة الإنتاج (PCSID) للتشغيل الحي، ولكل بيئة معرّف وسرّ مختلفان. خلط البيانات بين البيئتين سبب شائع جدًا لرمز الحالة 401 على الإنتاج.

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

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

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

قائمة فحص أمان بيانات الاعتماد

[ ] CSID والسرّ مخزّنان في مخزن أسرار مشفّر (Vault / KMS / Secrets Manager)
[ ] لا وجود لأي بيانات اعتماد في الكود أو ملفات الإعداد المرفوعة
[ ] بيانات بيئة المحاكاة منفصلة تمامًا عن بيانات الإنتاج
[ ] صلاحية الوصول للأسرار محصورة في الخدمة التي تحتاجها فقط
[ ] تنبيه آلي قبل انتهاء صلاحية الشهادة بمدة كافية
[ ] إجراء موثّق ومجرّب لإعادة إصدار الشهادة عند التسريب
[ ] مراجعة دورية لسجل الوصول إلى مخزن الأسرار

قابلية التكرار (Idempotency): معرّف UUID ثابت لكل فاتورة

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

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

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

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

// نمط صحيح: توليد المعرّف مرة واحدة وتخزينه
invoice.uuid = generateUUID();        // مرة واحدة عند الإنشاء
saveToDatabase(invoice);              // يُحفظ مع الفاتورة

// في كل محاولة إرسال، استخدم نفس المعرّف المخزّن
function submit(invoice) {
  return fataaraApi.send({
    uuid: invoice.uuid,               // ثابت عبر كل المحاولات
    payload: invoice.signedXml
  });
}

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

إعادة المحاولة بتراجع أسّي (Exponential Backoff)

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

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

القاعدة الحاسمة: لا تعيد المحاولة على كل خطأ. أعِد المحاولة فقط على الأخطاء العابرة (5xx، انقطاع الاتصال، انتهاء المهلة، ورمز تجاوز حد المعدل 429). أما أخطاء العميل (4xx مثل 400 و401 و403) فهي تعني أن طلبك نفسه خاطئ، وإعادة إرساله كما هو ستفشل بالطريقة نفسها. عالج السبب، لا تكرّر الخطأ.

ضع سقفًا لعدد المحاولات. بعد استنفاد المحاولات، انقل الفاتورة إلى طابور المعالجة اليدوية أو طابور الرسائل الميتة (Dead Letter Queue) بدل تركها تدور إلى ما لا نهاية. الفشل الصامت أسوأ من الفشل الظاهر.

// تراجع أسّي مع jitter وحد أقصى للمحاولات
async function submitWithRetry(invoice, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fataaraApi.send(invoice);
    if (res.ok) return res;

    // أخطاء العميل لا تُعاد محاولتها
    if (res.status >= 400 && res.status < 500 && res.status !== 429) {
      throw new ClientError(res);
    }

    const base = Math.min(1000 * 2 ** (attempt - 1), 30000);
    const jitter = Math.random() * 500;
    await sleep(base + jitter);
  }
  moveToManualQueue(invoice);   // بعد استنفاد المحاولات
}

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

التسجيل المنظّم دون تسريب الأسرار

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

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

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

// سطر سجل منظّم بعد تنقية الحقول الحسّاسة
{
  "timestamp": "2026-06-24T03:14:22Z",
  "invoice_uuid": "a1b2c3d4-...-e5f6",
  "attempt": 2,
  "status": 503,
  "request_id": "req_88f1",
  "authorization": "[REDACTED]",   // لا تسجّل القيمة الفعلية أبدًا
  "outcome": "retry_scheduled"
}

احفظ السجلات مدة كافية للتدقيق والتشخيص، وقيّد الوصول إليها. سجلّات الإنتاج التي تكشف بنية تكاملك ليست أقل حساسية من بيانات الاعتماد نفسها.

المراقبة والتنبيه الاستباقي

التسجيل يخبرك بما حدث بعد أن تبحث. المراقبة تخبرك بما يحدث الآن قبل أن تبحث. الفرق بينهما هو الفرق بين اكتشاف العطل من شكوى عميل، واكتشافه من تنبيه آلي قبل أن يلاحظه أحد.

راقب المؤشّرات التي تعكس صحة التكامل لا مجرّد صحة الخادم. أهمها: نسبة نجاح الإرسال، ومتوسّط زمن الاستجابة، وعدد الفواتير العالقة في طابور إعادة المحاولة، ومعدّل أخطاء 401 (يكشف مشكلة في الشهادة)، ومعدّل أخطاء 429 (يكشف اقترابك من حدود المعدل).

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

اربط كل تنبيه بإجراء واضح يعرفه من يستلمه. تنبيه «ارتفع معدّل 401» يجب أن يقترن بخطوة أولى: تحقّق من صلاحية الشهادة. تنبيه «تراكم طابور إعادة المحاولة» يقترن بـ: افحص حالة البوابة وراجع آخر أخطاء مسجّلة. التنبيه الذي لا يقود لإجراء يتحوّل بمرور الوقت إلى ضوضاء يتجاهلها الفريق، فتفقد قيمتها كلها.

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

الهدف من المراقبة ليس جمع لوحات بيانات جميلة، بل تقصير الزمن بين وقوع المشكلة ومعرفتك بها. كل دقيقة فرق هنا قد تعني فاتورة لم تصل للهيئة في نافذتها الزمنية.

المعالجة عبر طابور لا عبر طلب مباشر

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

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

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

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

الاختبار الشامل في بيئة المحاكاة

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

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

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

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

التحقّق قبل الإرسال (Validate Before Submit)

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

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

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

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

التمييز بين التحذيرات والأخطاء

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

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

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

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

اضبط لغة الاستجابة على العربية عبر ترويسة Accept-Language بقيمة ar حين يكون فريقك عربيًا. رسائل الخطأ والتحذير الواضحة بلغة الفريق تختصر زمن التشخيص، فلا تترجم ولا تخمّن معنى رسالة بلغة لا يقرؤها من يعالج المشكلة.

// افصل التحذيرات عن الأخطاء في منطقك
const res = await fataaraApi.send(invoice);

if (res.errors && res.errors.length > 0) {
  invoice.status = "rejected";       // الفاتورة مرفوضة، صحّح وأعد البناء
  logErrors(invoice.uuid, res.errors);
} else {
  invoice.status = "accepted";       // مقبولة حتى لو حملت تحذيرات
  if (res.warnings && res.warnings.length > 0) {
    logWarnings(invoice.uuid, res.warnings);  // تُراقَب ولا توقف القبول
  }
}

تثبيت إصدار الواجهة (Accept-Version)

ترويسة Accept-Version تحدّد إصدار الواجهة الذي بُني عليه تكاملك، وقيمتها للمرحلة الثانية من الفوترة الإلكترونية هي V2. تثبيت الإصدار صراحةً ممارسة دفاعية أساسية: يبقى نظامك مربوطًا بالإصدار الذي اختبرته، فلا يتأثّر فجأة بتغيّر في سلوك البوابة عند طرح إصدار جديد.

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

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

// ثبّت الإصدار صراحةً في كل طلب
const headers = {
  "Authorization": buildBasicAuth(csid, secret),
  "Accept-Version": "V2",            // لا تترك البوابة تختار
  "Content-Type": "application/json",
  "Accept-Language": "ar"            // رسائل خطأ بالعربية
};

خلاصة أفضل الممارسات في قائمة واحدة

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

الأمان
  [ ] CSID والسرّ في مخزن أسرار مشفّر، لا في الكود
  [ ] فصل تام بين بيانات المحاكاة والإنتاج
  [ ] خطة إعادة إصدار الشهادة جاهزة ومجرّبة

الموثوقية
  [ ] UUID ثابت لكل فاتورة، يُولّد مرة واحدة ويُخزّن
  [ ] إعادة المحاولة بتراجع أسّي مع jitter وحد أقصى
  [ ] إعادة المحاولة على الأخطاء العابرة فقط، لا على 4xx
  [ ] طابور معالجة يدوية لما تستنفد محاولاته

الرؤية
  [ ] تسجيل منظّم يحمل UUID والحالة ورقم المحاولة
  [ ] تنقية الحقول الحسّاسة قبل أي كتابة في السجل
  [ ] مراقبة نسبة النجاح و401 و429 وطول الطابور
  [ ] تنبيهات بعتبات واقعية تقود لإجراء واضح

الصحّة قبل الإرسال
  [ ] تحقّق محلي من المستند قبل أي طلب شبكي
  [ ] فصل التحذيرات عن الأخطاء في المنطق
  [ ] اختبار كل أنواع المستندات في المحاكاة
  [ ] Accept-Version مثبّت صراحةً على V2

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

أسئلة شائعة

لماذا أستخدم معرّف UUID ثابتًا بدل توليد واحد جديد في كل محاولة؟

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

على أي أخطاء أعيد المحاولة، وعلى أيها أتوقّف؟

أعِد المحاولة على الأخطاء العابرة: رموز 5xx وانقطاع الاتصال وانتهاء المهلة ورمز تجاوز حد المعدل 429. توقّف على أخطاء العميل 4xx (مثل 400 و401 و403) لأنها تعني أن طلبك نفسه خاطئ، فإعادته كما هو ستفشل بالطريقة ذاتها. عالج السبب بدل تكرار الخطأ.

ما الحقول التي يجب ألا تظهر في السجلّات أبدًا؟

سرّ شهادة CSID، وقيمة ترويسة Authorization الكاملة، وأي مفتاح خاص. طبّق تنقية على هذه الحقول قبل الكتابة. القاعدة العملية: لو ظهر السجل على شاشة أحدهم، فلا يجب أن يحوي ما يتيح انتحال هوية منشأتك على البوابة.

ما الفرق بين التحذير والخطأ في استجابة الهيئة؟

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

لماذا أثبّت قيمة Accept-Version صراحةً؟

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

لماذا أتحقّق من الفاتورة محليًا قبل إرسالها للهيئة؟

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