يوضّح هذا الدليل كيفية تعامل Merchant API مع تحديد الإصدارات والإصدارات الجديدة ومراحل نشاط إصداراته المختلفة.
نظام تحديد الإصدارات
تستخدم Merchant API استراتيجية لتحديد الإصدارات على مستوى واجهة برمجة التطبيقات الفرعية. ويعني ذلك أنّ كل واجهة برمجة تطبيقات فرعية في Merchant API، مثل المنتجات ضمن Merchant API، سيكون لها مرحلة نشاط خاصة بها.
تنسيق الإصدار وعرضه
إصدارات واجهة برمجة التطبيقات الفرعية الثابتة: إذا كانت واجهة برمجة التطبيقات الفرعية في إصدار ثابت، فإنّ جميع طرقها تكون في إصدار ثابت. ويتم تمثيل إصدار واجهة برمجة التطبيقات الفرعية الثابتة على النحو vX (على سبيل المثال، الإصدار 1 والإصدار 2). هذه هي الإصدارات الرئيسية الجاهزة للاستخدام.
إصدارات واجهة برمجة التطبيقات الفرعية التجريبية: إذا كانت واجهة برمجة التطبيقات الفرعية في إصدار تجريبي، فإنّ جميع طرقها تكون في إصدار تجريبي. ويتم تمثيل إصدار واجهة برمجة التطبيقات الفرعية التجريبية على النحو vXalpha (على سبيل المثال، الإصدار 1alpha والإصدار 2alpha). تحتوي هذه الإصدارات على ميزات تجريبية يمكن استخدامها قبل إطلاقها، وهي مخصّصة للاختبار والتكرار السريع. لا تضمن الإصدارات التجريبية أي ثبات، وليس لها فترة صلاحية محدّدة، ويمكن تغييرها أو إيقافها نهائيًا مع إرسال إشعار قبل 30 يومًا من إجرائها.
تغييرات الإصدار
- زيادة رقم الإصدار الرئيسي (على سبيل المثال، من الإصدار 1 إلى الإصدار 2): تشير هذه الزيادة إلى تغييرات غير متوافقة مع الأنظمة القديمة وتغييرات قد تؤدي إلى أعطال، ما يتطلّب اتخاذ إجراء من قِبل المطوّر. لن يتم تغيير رقم الإصدار إلا للتغييرات التي قد تؤدي إلى أعطال في واجهات برمجة التطبيقات الفرعية الثابتة. على سبيل المثال، من الإصدار 1 إلى الإصدار 2.
- التغييرات الثانوية: يتم عرض الإضافات أو الإصلاحات المتوافقة مع الأنظمة القديمة كتغييرات في رقم الإصدار الرئيسي الحالي. وسيتم تفصيل هذه التغييرات في ملاحظات الإصدار لرقم الإصدار الرئيسي هذا. سيتم إطلاق الإضافات غير المؤدية إلى أعطال في واجهة برمجة التطبيقات الفرعية على القناة التجريبية لأحدث إصدار ثابت أو مباشرةً على أحدث إصدار ثابت.
سياسة إيقاف الإصدارات نهائيًا
نوقف نهائيًا بشكل دوري إصدارات واجهات برمجة التطبيقات الفرعية الأقدم في Merchant. نلتزم بفترة إيقاف نهائي مدتها 12 شهرًا للإصدارات الرئيسية الثابتة (vX)، بدءًا من الإشعار الرسمي بإيقاف الإصدار نهائيًا.
على سبيل المثال، إذا أوقفنا نهائيًا الإصدار 1 من واجهة برمجة التطبيقات الفرعية "المنتجات" في 15 يناير 2026، فلن يتم إيقافه نهائيًا قبل 15 يناير 2027. بعد هذا التاريخ، لن يعود الإصدار السابق من واجهة برمجة التطبيقات الفرعية متاحًا للاستخدام.
إصدار واجهة برمجة التطبيقات الفرعية وحالة مرحلة النشاط
يسرد الجدول التالي أحدث إصدارات كل واجهة برمجة تطبيقات فرعية في Merchant API:
| واجهة برمجة التطبيقات الفرعية | الإصدارات | الحالة |
|---|---|---|
| حسابات | الإصدار 1 الإصدار 1alpha الإصدار 1beta |
نشطة نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| الإحالات الناجحة | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| مصادر البيانات | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| المخزون | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| حلّ المشاكل | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| برنامج الشراكة في الخلاصات المحلية | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| الإشعارات | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| تتبُّع الطلبات | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| المنتجات | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| Product Studio | v1alpha | نشطة |
| العروض الترويجية | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| Quota | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| التقارير | الإصدار 1 الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
| المراجعات | الإصدار 1alpha الإصدار 1beta |
نشطة تم إيقافها نهائيًا في 28 فبراير 2026 |
أفضل الممارسات
- ننصحك بالاطّلاع بانتظام على ملاحظات الإصدار وأحدث التعديلات لمعرفة الإصدارات الجديدة والتعديلات الرئيسية والتحسينات والإشعارات حول إطلاق واجهات برمجة التطبيقات الفرعية وإيقافها نهائيًا.
- إذا كانت لواجهة برمجة تطبيقات فرعية إصداران ثابتان أو أكثر، ننصحك باستخدام أحدث إصدار في جميع الأوقات.
- ننصحك بتصميم تطبيقك للتعامل بشكل سليم مع مختلف أخطاء واجهات برمجة التطبيقات الفرعية، بما في ذلك مشاكل الشبكة وحدود المعدّل ورموز الخطأ أو الرسائل الجديدة التي قد يتم تقديمها مع إصدارات أحدث من واجهات برمجة التطبيقات الفرعية.
- لا تنتظر حتى يتم إيقاف إصدار واجهة برمجة تطبيقات فرعية نهائيًا لتبدأ التخطيط للترقية. ابدأ بتقييم الإصدارات الجديدة واختبارها فور توفّرها.
- لطلب ميزات أو إذا كانت لديك مخاوف بشأن خارطة طريق واجهة برمجة تطبيقات فرعية، يُرجى التواصل معنا لطرح الأسئلة أو تقديم الملاحظات. للحصول على معلومات حول كيفية التواصل مع فريق Merchant API للحصول على الدعم الفني، يُرجى الاطّلاع على مقالة الحصول على مساعدة بشأن Merchant API.