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

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

نظام تحديد الإصدارات

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

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

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

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

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

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

سياسة إيقاف الإصدارات نهائيًا

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

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

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

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

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

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