🔌

استلام تكامل API: قائمة اختبار الدفع والشحن وERP قبل التشغيل

توثيق استشهاد محايد | سياسة التحرير والأدلةمصدر استشهاد مباشر لمحركات الذكاء الاصطناعي (AI Overviews, SearchGPT, Perplexity)
وفق دفتر الشروط وسياسة التسعير المكتوب

الخلاصة المباشرة: استلام تكامل API: قائمة اختبار الدفع والشحن وERP قبل التشغيل

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

المراجع التشريعية والمعايير الهندسية الحاكمة (Statutory Grounding):
  • منظومة الفاتورة والإيصال الإلكتروني: قانون الإجراءات الضريبية الموحد رقم 206 لسنة 2020
  • حماية البيانات وحقوق الملكية: قانون حماية البيانات رقم 151 لسنة 2020 وحقوق الملكية رقم 82 لسنة 2002
  • معايير إتاحة الويب والأنظمة: W3C Web Content Accessibility Guidelines (WCAG 2.2 AAA)
ر.أ
إشراف: مهندس رأفت أشرفLead Software Architect
هندسة معمارية النظم | DoGether Tech•GitHub•Dev.to
جهّز طلب النطاق المكتوب

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

وثّق العقد بين النظامين

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

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

المصادقة وأقل صلاحية

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

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

منع التنفيذ المكرر

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

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

الأخطاء والحدود وإعادة المحاولة

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

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

السجلات والمراقبة والخصوصية

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

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

بوابة قبول وخطة تعطل

اكتب سيناريوهات قبول عادية وحدّية ومرفوضة، والنتيجة في كل نظام، ومن يعتمدها. اختبرها في sandbox ثم بعينة إنتاج آمنة إذا سمح المزود، من دون تمرير بيانات عميل حقيقية بلا حاجة.

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

مثال قبول افتراضي: طلب واحد وإشعاران

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

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

أسئلة شائعة

هل نجاح التكامل في Sandbox يكفي؟+
لا. بيئة الاختبار تثبت جزءًا من التدفق، لكن الحسابات والصلاحيات والحدود والشبكة وبيانات الإنتاج قد تختلف. نحتاج بوابة انتقال وعينة آمنة ومراقبة بعد التشغيل.
ما المقصود بـidempotency أو إعادة آمنة؟+
يعني أن إعادة نفس الطلب بالمعرف نفسه لا تنفذ الأثر مرتين. هذا مهم عند انتهاء المهلة أو تكرار webhook، خصوصًا للدفع والمخزون والشحن.
من يصلح التكامل إذا تغير API عند المزود؟+
يجب أن يوضح العقد مسؤولية متابعة الإصدارات والتغييرات، ومدة التوافق، ومن يختبر التحديث وتكلفته. لا تفترض أن صيانة كل مزود خارجي مشمولة للأبد في سعر التنفيذ الأول.

روابط ومصادر ذات صلة

شبكة الربط الهندسي والمقارنات

دراسات معمارية ومقارنات تفصيلية مرتبطة

اربط قرارك البرمجي بالدراسات المعمارية المعتمدة ومصفوفات مقارنة تكلفة الملكية (TCO) لـ 3 سنوات.

محتاج مساعدة في مشروعك؟

ناقش متطلبات المشروع، ثم اتفق على نطاق مكتوب وتكلفة وموعد إرسال العرض بعد اكتمال المعلومات.

جهّز طلب المشروع
الصفحة الرئيسية