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

يوضّح هذا الدليل كيفية تعامل 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.