واجهة Account API: كيف تنتقل من GET v1/managers/profile

ما الذي يتغيّر ومتى

في 16 يونيو 2026 أعلنت زد في سجل تحديثات الشركاء أن نقطة GET v1/managers/profile سيجري إيقافها، وأن موعد الانتقال 30 سبتمبر 2026. وبعد هذا التاريخ لن تكون النقطة متاحة، فإذا كان تطبيقك ما زال يستدعيها فعليك الانتقال بحلول هذا الموعد.

والبديل هو Account API: مجموعة نقاط أصغر، لكل نقطة منها Scope OAuth خاص بها. والهدف كما تذكر زد تحكّم أدق في الصلاحيات يتماشى مع أفضل ممارسات الأمان. فبدل API Call واحد يعيد كل شيء، يطلب تطبيقك البيانات التي يحتاجها فقط، ويوافق التاجر على الـ Scopes التي تتطلبها هذه البيانات فقط.

النقاط الجديدة ونطاقاتها

تجد النقاط في التوثيق تحت Merchant APIs > Account، والنقاط التالية كلها طلبات GET على https://api.zid.sa/:

• Account Identity: النقطة /v1/managers/account/me تعيد الهوية الأساسية للمستخدم المسجّل: الـ ID وUUID والاسم والبريد والجوال والجنس واللغة المفضلة وتاريخ الإنشاء. الـ Scope: third_account_identity_read.
• Store Details: النقطة /v1/managers/account/store تعيد ID المتجر وUUID والعنوان والهاتف والبريد والرابط والمنطقة الزمنية. الـ Scope: third_store_details_read.
• Store Branding: النقطة /v1/managers/account/store/branding تعيد الثيم المفعّل والشعارات وصورة الغلاف والأيقونة وألوان الأزرار. الـ Scope: third_store_details_read.
• Store Localization: النقطة /v1/managers/account/store/localization تعيد اللغات المدعومة والمفعّلة (مع اتجاه النص) والعملات، ومنها العملة الافتراضية. الـ Scope: third_store_details_read.
• Store Social: النقطة /v1/managers/account/store/social تعيد حسابات المتجر في وسائل التواصل. الـ Scope: third_store_details_read.
• Store Operations: النقطة /v1/managers/account/store/operations تعيد إعدادات التشغيل، مثل وضع الصيانة وطرق تسجيل دخول العملاء المفعّلة وتوفر تطبيق الجوال وحالة توفر المتجر. الـ Scope: third_store_details_read.
• Store Business: النقطة /v1/managers/account/store/business تعيد بيانات التحقق (KYC)، ومنها معلومات السجل التجاري وبيانات النشاط. الـ Scope في صفحة التوثيق: third_store_business_read.

ويذكر سجل التحديثات أيضًا نقطة Account Profile بـ Scope third_account_profile_read، لبيانات موسّعة مثل تاريخ الميلاد والمسمى الوظيفي والمعلومات الجغرافية.

قبل وبعد

يحدد التوثيق أن Authorization وX-Manager-Token مطلوبتان في كل نقاط Account API. أما Accept-Language فاختيارية، وتقبل en أو ar، وقيمتها الافتراضية en.

# قبل: نقطة يجري إيقافها (موعد الانتقال 30 سبتمبر 2026)
GET v1/managers/profile

# بعد: Account Identity (الـ Scope: third_account_identity_read)
GET https://api.zid.sa/v1/managers/account/me
Authorization: Bearer {{authorization}}
X-Manager-Token: {{access_token}}
Accept-Language: en

وعند نجاح الطلب تعيد /me بيانات المستخدم داخل Object user (اختصرنا هنا القيم الشخصية):

{
  "status": "object",
  "user": {
    "id": 1,
    "uuid": "e5616699-6f91-4e84-a655-19f1ecb4b166",
    "name": "...",
    "email": "...",
    "mobile": "966500000005",
    "mobile_object": { "country_code": "966", "mobile": "500000005" },
    "gender": "f",
    "preferred_language": "ar",
    "created_at": "2019-07-28 22:26:53"
  },
  "message": { "type": "object", "code": null, "name": null, "description": null }
}

ونقاط المتجر تتبع النمط نفسه، والبيانات فيها تحت مفتاح باسم النقطة: store أو branding أو localization أو social أو operations أو business.

قائمة خطوات الانتقال

1. اعثر على كل API Call. ابحث في الكود والمهام الخلفية والـ Scripts عن v1/managers/profile.
2. حدّد الحقول التي تستخدمها فعلًا. لكل API Call، دوّن القيم التي يقرؤها تطبيقك: اسم المدير وبريده، رابط المتجر، العملة، الشعار، وهكذا.
3. اربط الحقول بالنقاط. استعن بالقائمة أعلاه، واستدعِ فقط النقاط التي يقرأ تطبيقك حقولها.
4. اختر الـ Scopes في لوحة الشركاء. تُختار الـ Scopes من صفحة تطبيقك في لوحة الشركاء. أضف فقط الـ Scopes التي تحتاجها النقاط التي تستدعيها.
5. حدّث واختبر. استبدل الـ API Calls، ثم جرّب مسار التثبيت كاملًا على المتجر التجريبي وتأكد أن كل حقل يعتمد عليه تطبيقك يصل كما تتوقع.
6. احذف الـ API Call القديم. عندما لا يبقى شيء يعتمد على v1/managers/profile، احذفه حتى لا يفشل لاحقًا.

curl -X GET 'https://api.zid.sa/v1/managers/account/store' \
  --header 'Authorization: Bearer {{authorization}}' \
  --header 'X-Manager-Token: {{access_token}}' \
  --header 'Accept-Language: ar'

تفاصيل تستحق التأكد منها

• Scope Business. يذكر سجل التحديثات الـ Scope third_store_details_read لنقطة Store Business، بينما تذكر صفحة Business في التوثيق third_store_business_read. اعتمد على صفحة التوثيق عند ضبط الـ Scopes، واختبر الـ API Call قبل أن تعتمد عليه.
• صفحة Account Profile. وقت كتابة هذا المقال، رابط Account Profile في سجل التحديثات لا يفتح، وقسم Account في التوثيق يعرض Me ونقاط المتجر. إذا كان تطبيقك يحتاج تاريخ الميلاد أو المسمى الوظيفي أو البيانات الجغرافية، فتحقق أولًا من الصفحة الحالية في التوثيق.
• الاستجابات 401 و403. كل صفحات Account API توثّقهما. ومن الممارسات الجيدة أن تسجّل نص الاستجابة وتتأكد أن الـ Scope المطلوب مفعّل قبل إعادة المحاولة.