تحديد الإصدار

يوضّح هذا الدليل كيفية تعامل Merchant API مع الإصدارات وعمليات الإصدار ودورة حياة إصداراته المختلفة.

مخطط تحديد الإصدار

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

تنسيق العرض التقديمي وإصداراته

• إصدارات فرعية ثابتة من واجهة برمجة التطبيقات: إذا كان الإصدار الفرعي من واجهة برمجة التطبيقات ثابتًا، يعني ذلك أنّ جميع طُرقها ثابتة. يتم تمثيل إصدار فرعي ثابت من واجهة برمجة التطبيقات بالصيغة vX (على سبيل المثال، v1 أو v2). وهي إصدارات رئيسية جاهزة للاستخدام في بيئة الإنتاج.

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

تغييرات الإصدار

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

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

سياسة إيقاف المنتجات نهائيًا

نوقف نهائيًا بشكل دوري الإصدارات القديمة من واجهات Merchant الفرعية. نلتزم بفترة إيقاف نهائي مدتها 12 شهرًا للإصدارات الرئيسية الثابتة (vX)، بدءًا من تاريخ الإعلان الرسمي عن الإيقاف النهائي.

على سبيل المثال، إذا أوقفنا الإصدار 1 من واجهة برمجة التطبيقات الفرعية "المنتجات" نهائيًا في 15 يناير 2026، لن يتم إيقافه نهائيًا قبل 15 يناير 2027. بعد هذا التاريخ، لن يعود الإصدار السابق من واجهة برمجة التطبيقات الفرعية متاحًا للاستخدام.

إصدار واجهة برمجة التطبيقات الفرعية وحالة مراحل النشاط

يسرد الجدول التالي أحدث إصدارات كل واجهة فرعية من Merchant API:

أفضل الممارسات

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