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