يوضّح هذا الدليل كيفية تعامل 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:
| Sub-API | الإصدارات | الحالة |
|---|---|---|
| حسابات | v1 v1alpha v1beta |
نشطة نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| الإحالات الناجحة | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| مصادر البيانات | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| المستودعات | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| حلّ المشاكل | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| برنامج الشراكة في الخلاصات المحلية | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| الإشعارات | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| تتبُّع الطلبات | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| المنتجات | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| Product Studio | v1alpha | نشطة |
| العروض الترويجية | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| الحصة | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| التقارير | v1 v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
| المراجعات | v1alpha v1beta |
نشطة سيتم إيقافها نهائيًا في 28 فبراير 2026 |
أفضل الممارسات
- راجِع ملاحظات الإصدار وآخر التحديثات بانتظام للاطّلاع على الإصدارات الجديدة والتحديثات الرئيسية والتحسينات والإشعارات بشأن إطلاق وإيقاف واجهات برمجة التطبيقات الفرعية نهائيًا.
- إذا كان لواجهة برمجة تطبيقات فرعية إصداران ثابتان أو أكثر، ننصحك باستخدام أحدث إصدار في جميع الأوقات.
- صمِّم تطبيقك للتعامل بسلاسة مع مختلف أخطاء واجهات برمجة التطبيقات الفرعية، بما في ذلك مشاكل الشبكة وحدود المعدّل ورموز الخطأ أو الرسائل الجديدة التي قد يتم طرحها مع إصدارات أحدث من واجهات برمجة التطبيقات الفرعية.
- لا تنتظر حتى توشك صلاحية إصدار فرعي من واجهة برمجة التطبيقات على الانتهاء لتبدأ التخطيط لعملية الترقية. ابدأ بتقييم الإصدارات الجديدة واختبارها فور توفّرها.
- لتقديم طلبات بشأن ميزات أو إبداء مخاوف بشأن خارطة طريق لواجهة برمجة تطبيقات فرعية، يُرجى التواصل معنا لطرح الأسئلة أو تقديم الملاحظات. للحصول على معلومات حول كيفية التواصل مع فريق Merchant API للحصول على الدعم الفني، اطّلِع على الحصول على المساعدة بشأن Merchant API.