الأسئلة الشائعة

يتناول هذا القسم الأسئلة الشائعة حول تسجيل المطوّرين في Merchant API.

التسجيل العام

الأسئلة الشائعة حول عملية التسجيل:

هل تسجيل المطوّر إلزامي لاستخدام Merchant API؟

نعم. يجب تسجيل معلومات الاتصال الخاصة بك كمطوِّر حتى تتمكّن Google من إرسال إشعارات مهمة خاصة بواجهة برمجة التطبيقات، مثل إشعارات الخدمة ومعلومات الميزات الجديدة.

إذا كنت تريد استكشاف Merchant API واختبارها فقط، يمكنك استخدام أدوات مثل Google OAuth Playground وAPI Explorer اللتين لا تتطلّبان التسجيل.

كم مرة يجب أن أسجّل؟

التسجيل هو عملية إعداد للمرة الأولى لكل مشروع على Google Cloud. سواء كنت تعمل باستخدام حسابات تاجر متعدّدة أو لا، عليك إجراء عملية التسجيل مرة واحدة فقط، وهي تنطبق على جميع المستخدمين وحسابات الخدمة ضمن مشروع على السحابة الإلكترونية المرتبط بـ Google Cloud.

بعد تسجيل مشروع على السحابة الإلكترونية بنجاح، يظل الرابط نشطًا ما لم تتم إزالته بشكل صريح من خلال استدعاء طريقة unregisterGcp. لا يمكنك تسجيل المشاريع المشترَكة التي تملكها Google، مثل مستكشف واجهات برمجة التطبيقات أو مساحة بروتوكول OAuth.

ما هو عنوان البريد الإلكتروني الذي يجب تقديمه كمعلومات اتصال بالمطوّر؟

ننصح باستخدام عنوان بريد إلكتروني خاص بموظف في الشركة. يمكنك بدلاً من ذلك استخدام أسماء مستعارة عامة للمجموعات. لا يمكنك استخدام عناوين البريد الإلكتروني لحسابات الخدمة، لأنّ المراسلات مخصّصة للمستلمين من البشر. ترسل Google إشعارات مهمة خاصة بواجهات برمجة التطبيقات، مثل إشعارات الخدمة ومعلومات عن الميزات الجديدة.

إذا كان عنوان البريد الإلكتروني يخص مستخدمًا حاليًا في حساب Merchant Center، سيتم تلقائيًا منحه دور API_DEVELOPER. إذا لم يكن كذلك، سيتم إرسال دعوة إلى هذا العنوان.

حقل عنوان البريد الإلكتروني الخاص بالتواصل مع المطوّر اختياري في طريقة registerGcp. إذا لم تقدّم قيمة لهذا الحقل عند التسجيل، عليك إنشاء مستخدم لديه دور API_DEVELOPER إما في واجهة مستخدم Merchant Center أو من خلال استدعاء طريقة accounts.users.create.

هل يجب أن يكون عنوان البريد الإلكتروني لجهة اتصال المطوّر حسابًا على Google؟

نعم. لاستخدام عنوان بريد إلكتروني حالي غير تابع لـ Google، يمكنك ربطه بحساب Google من خلال اختيار الخيار استخدام عنوان بريدك الإلكتروني الحالي في عملية الاشتراك إنشاء حساب على Google. لا يمكنك استخدام عناوين البريد الإلكتروني لحسابات الخدمة لأنّ حسابات الخدمة لا يمكنها تلقّي رسائل إلكترونية.

كيف يمكنني إجراء المصادقة والترخيص لمكالمة التسجيل؟

يتوفّر سيناريوهان مختلفان للمصادقة على طلب التسجيل ومنحه الإذن، وذلك حسب حالة الاستخدام:

  • بروتوكول OAuth 2.0: لمقدّمي الخدمات الخارجيين أو الوكالات التي تدير حسابات تجارية متعدّدة
  • حسابات الخدمة: للوصول إلى حسابك على Merchant Center

النص البديل لتسهيل الاستخدام

يوضّح المخطّط البياني السابق مسارَي المصادقة والتفويض لمكالمة التسجيل. يمكنك اختيار أي مما يلي:

  • استخدام OAuth مع عنوان بريد إلكتروني، مثل account@email.com، مرتبط بحساب Google
  • استخدام حساب خدمة، مثل sa@project.iam.gserviceaccount.com

إذا قرّرت استخدام OAuth، عليك اتّباع الخطوات التالية:

  • إنشاء بيانات اعتماد OAuth في مشروعك على Google Cloud لبريدك الإلكتروني
  • تأكَّد من أنّ عنوان البريد الإلكتروني الذي يمنح الإذن متوفّر في حسابك على Merchant Center وأنّ لديه نوع إذن الوصول ADMIN

إذا قرّرت استخدام حساب خدمة، عليك اتّباع الخطوات التالية:

  • تأكَّد من أنّ حساب الخدمة متوفّر في مشروعك على Google Cloud.
  • تأكَّد من أنّ عنوان البريد الإلكتروني المرتبط بحساب الخدمة متوفّر في حسابك على Merchant Center وأنّ لديه نوع إذن الوصول ADMIN.

نفِّذ طلب التسجيل ضمن سياق الأمان الخاص بهوية المصادقة، وذلك باستخدام طلبات مباشرة من واجهة برمجة التطبيقات أو مكتبات العميل. قدِّم عنوان بريد إلكتروني للتواصل مع المطوّر، مثل developer@email.com.

في حال نجاح طلب التسجيل، سيظهر مستخدم في حسابك على Merchant Center بعنوان البريد الإلكتروني للمطوّر الذي تم تقديمه ودور API_DEVELOPER. ستتلقّى ردًا على شكل مورد DeveloperRegistration.

ما الفرق بين عنوان البريد الإلكتروني المخصّص للمصادقة وعنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر؟

يخدم عنوانا البريد الإلكتروني غرضَين مختلفَين ضمن نظام Merchant API المتكامل:

  • المصادقة على عنوان البريد الإلكتروني: يمكنك عادةً استخدام عنوان بريد إلكتروني مرتبط بحسابك على Google أو بحساب خدمة كمعرّف للمصادقة على الطلبات الموجّهة إلى Merchant API، وذلك في حال استيفاء الشروط التالية:
    • يجب أن يكون هذا الحساب موجودًا في Merchant Center وأن يكون لديه دور ADMIN.
    • يستضيف مشروع على Google Cloud تم تفعيل Merchant API فيه عميل OAuth أو حساب الخدمة المرتبط بعنوان البريد الإلكتروني الذي يمنح الإذن بإجراء طلبات البيانات من واجهة برمجة التطبيقات.
  • عنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر: يجب أن يكون عنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر مرتبطًا أيضًا بحساب Google، ولكنّه يُستخدَم كجهة الاتصال الأساسية للإشعارات المهمة عن الخدمة والتعديلات على واجهة برمجة التطبيقات من Google. ويمكن أن يكون هذا الحساب خاصًا بمستخدم أو بمجموعة من المستخدمين. يتم تلقائيًا منح هذا الحساب دور API developer في Merchant Center.

هل يجب قبول الدعوة التي تم تلقّيها على عنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر؟

نعم. لدى المستلم الذي تقدّمه لعنوان البريد الإلكتروني الخاص بالتواصل مع المطوّرين مهلة 14 يومًا لقبول الدعوة. لا يكتمل التسجيل إلا بعد قبول الدعوة. ومع ذلك، يمكنك إجراء طلبات إلى واجهة برمجة التطبيقات خلال هذه الفترة.

إذا لم يتم قبول الدعوة خلال الوقت المحدّد، ستنتهي صلاحية رابط الدعوة. لن تتمكّن بعد ذلك من تنفيذ طلبات بيانات من واجهة Merchant API، وسيكون عليك إعادة بدء عملية التسجيل.

إدارة الحسابات والمشاريع

الأسئلة الشائعة حول إدارة الحساب والمشروع:

أعمل مع حسابات متعدّدة على Merchant Center. هل يجب تسجيل كل حساب على Merchant Center أريد استخدامه مع Merchant API؟

لا، إذا كنت مطوّرًا تابعًا لجهة خارجية أو وكالة تدير حسابات متعددة لتجّار، عليك تسجيل مشروعك على Google Cloud باستخدام حسابك الأساسي على Merchant Center، وليس باستخدام حسابات كل التجّار. وبهذه الطريقة، تمثّل المطوّر في جميع أعمال واجهة برمجة التطبيقات التي تنفّذها للتجّار.

أعمل مع حسابات متعدّدة على Merchant Center. كيف يمكنني اختيار حسابي الأساسي على Merchant Center؟

يعتمد اختيار الحساب الأساسي على نوع نشاطك التجاري:

  • الأسواق التي لديها حساب بامتيازات متقدّمة حالي: إذا كان نشاطك التجاري يعمل كسوق ولديه حساب بامتيازات متقدّمة يمثّل المنصة بأكملها، استخدِم معرّف هذا الحساب الحالي كحساب Merchant Center الرئيسي.
  • خدمات مقارنة الأسعار (CSS): إذا كنت تستخدم CSS، استخدِم رقم تعريف حساب CSS الفريد أو رقم تعريف حساب مجموعة CSS.
  • الوكالات والمطوّرون والجهات الخارجية الأخرى: إذا كنت تدير نشاطًا تجاريًا تابعًا لجهة خارجية، مثل وكالة أو مطوّر تابع لجهة خارجية، وتدير حسابات متعدّدة للتجّار وليس لديك معرّف Merchant Center واحد يمثّل نشاطك التجاري، عليك إنشاء حساب أساسي جديد على Merchant Center وطلب تحويله إلى حساب بامتيازات متقدّمة.

بعد تسجيل مشروع Google Cloud في حسابك الأساسي على Merchant Center، يمكنك استخدام المشروع نفسه لإدارة أي حساب آخر على Merchant Center يمكنك الوصول إليه، بدون الحاجة إلى تسجيل هذه الحسابات بشكل فردي.

أستخدم عدة مشاريع على Google Cloud. هل عليّ تسجيل كلّ منها؟

نعم. بما أنّ عملية التسجيل تربط مشروع Google Cloud الذي يتم استدعاؤه، عليك تنفيذ طلب registerGcp من كل مشروع Google Cloud تستخدمه لإجراء طلبات البيانات من واجهة برمجة التطبيقات.

يمكن تسجيل مشروع واحد على Google Cloud في حساب واحد فقط على Merchant Center في كل مرة. ومع ذلك، يمكن أن يتضمّن حساب واحد على Merchant Center مشاريع متعدّدة على Google Cloud مسجّلة فيه. وبالمثل، يمكنك استخدام عنوان البريد الإلكتروني نفسه الخاص بالمطوّر لإجراء عمليات تسجيل متعدّدة في مشاريع Google Cloud أو حسابات Merchant Center متعدّدة.

ماذا يحدث إذا سجّلتُ مشروع Google Cloud باستخدام عدة حسابات على Merchant Center؟

ستؤدي محاولة تسجيل مشروع على السحابة الإلكترونية من Google سبق أن تم تسجيله باستخدام حساب آخر على Merchant Center إلى ظهور الخطأ ALREADY_REGISTERED.

كيف يمكنني إثبات صحة طلب البيانات من واجهة برمجة التطبيقات الخاصة بتسجيل المطوّرين؟

للمصادقة على طلب بيانات من واجهة برمجة التطبيقات لتسجيل المطوّرين في Merchant API، عليك استخدام بيانات اعتماد تتم إدارتها من خلال مشروع على Google Cloud. يتوفّر لك خياران أساسيان للهوية التي تجري عملية المصادقة:

  • حساب Google، مثل Gmail، باستخدام بروتوكول OAuth 2.0: تستخدم هذه الطريقة بيانات اعتماد عميل OAuth 2.0 التي يتم إنشاؤها ضمن مشروعك على Google Cloud. يتم تفويض طلب البيانات من واجهة برمجة التطبيقات نيابةً عن حساب Google محدّد يسجّل المستخدم الدخول إليه.
  • حساب الخدمة: تستخدم هذه الطريقة حساب خدمة Google Cloud، وهو نوع خاص من حسابات Google مخصّص للتطبيقات. تتم أيضًا إدارة بيانات اعتماد حساب الخدمة ضمن مشروعك على السحابة الإلكترونية على Google Cloud.

لإكمال عملية تسجيل المطوّر بنجاح، يجب أن تستوفي هوية المصادقة (حساب Google أو حساب الخدمة) المعايير التالية في Merchant Center:

  • موجود كمستخدم في Merchant Center: يجب إضافة عنوان البريد الإلكتروني المرتبط بحساب Google أو حساب الخدمة الذي يتم التحقّق منه إلى حساب Merchant Center الذي تسجّله كمستخدم.
  • دور المشرف مطلوب: يجب أن يكون لدى هذا المستخدم دور ADMIN في حساب Merchant Center المحدّد.

عند إجراء طلبات البيانات من واجهة برمجة التطبيقات، اتّبِع ما يلي:

  • في حال استخدام طلبات البيانات من واجهة برمجة التطبيقات المباشرة، يجب الحصول على رمز دخول صالح وتقديمه في عنوان Authorization. يتم إنشاء هذا الرمز المميّز من خلال مسار OAuth 2.0 لحساب Google أو مسار المصادقة من خادم إلى خادم لحساب خدمة.
  • تتولّى مكتبات العملاء التي توفّرها Google عادةً معالجة تعقيدات الحصول على رموز الدخول المميزة وتحديثها نيابةً عنك كجزء من عملية الإعداد.

قد لا يكون المستخدم الذي تتم مصادقته هو نفسه المستخدم الذي يتم التواصل معه من قِبل المطوّر. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة ما هو الفرق بين عنوان البريد الإلكتروني المخصّص للمصادقة وعنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر؟

كم مرة يجب إعادة تحميل رموز الدخول المميزة؟

تنتهي صلاحية رموز الدخول لكلّ من حسابات الخدمة والإصدار 2.0 من OAuth عادةً بعد ساعة واحدة. ومع ذلك، تعتمد آلية الحصول على رمز جديد على طريقة المصادقة التي تستخدمها:

  • تستخدم حسابات الخدمة مفتاحًا خاصًا أو بيانات اعتماد البيئة لإنشاء رمز دخول جديد كلما دعت الحاجة إلى ذلك.
  • تستخدم مسارات OAuth 2.0 refresh_token للاتصال بنقطة نهاية رمز Google OAuth2 المميز من أجل تلقّي رمز دخول جديد لمدة ساعة واحدة.

ننصحك بشدة باستخدام مكتبات Google Auth الرسمية التي تتعامل مع عملية التدوير هذه تلقائيًا حتى لا يتعطّل تطبيقك أبدًا.

المستخدمون والأدوار

الأسئلة الشائعة حول المستخدمين والأدوار:

هل يجب أن يكون حساب البريد الإلكتروني للمطوّر موجودًا من قبل في Merchant Center؟

لا، إذا لم يكن حساب البريد الإلكتروني المستخدَم في التسجيل متوفّرًا في Merchant Center، تنشئ Merchant API الحساب في Merchant Center باستخدام البريد الإلكتروني المحدّد مع ضبط الحالة على "في انتظار المراجعة". إذا كان عنوان البريد الإلكتروني الخاص بالمطوّر يخص مستخدمًا حاليًا في حساب Merchant Center، سيتم تلقائيًا منحه دور API_DEVELOPER.

هل يجب أن يكون لعنوان البريد الإلكتروني الخاص بالتواصل مع المطوّر حقوق المشرف في Merchant Center؟

لا، لأنّ مستخدم Merchant Center المرتبط بعنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر يحصل تلقائيًا على دور API_DEVELOPER المطلوب لتلقّي الإشعارات المهمة. ومع ذلك، لديه الحد الأدنى من الأذونات داخل Merchant Center. للسماح لهذا المستخدم بإجراء طلبات أخرى إلى واجهة برمجة التطبيقات أو إدارة الإعدادات في واجهة مستخدم Merchant Center، عليك منحه أدوارًا إضافية، مثل STANDARD أو ADMIN. لمزيد من المعلومات حول أدوار Merchant Center، راجِع أنواع الوصول.

ما هي الأذونات التي يتضمّنها دور "مطوّر واجهة برمجة التطبيقات"؟

دور API Developer هو دور يتضمّن الحد الأدنى من الحقوق في Merchant Center. إذا كنت تخطّط لاستخدام عنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر من أجل منح الإذن بإجراء طلبات إلى Merchant API، ننصحك بإضافة أذونات ADMIN أو STANDARD لتمكين المستخدم من إجراء طلبات إلى واجهة برمجة التطبيقات.

هل يجب تسجيل كل حساب مستخدم أو حساب خدمة خاص بالمطوّرين يستدعي واجهة برمجة التطبيقات؟

لا، لأنّ عملية تسجيل المطوّر مرتبطة بمشروع Google Cloud المستخدَم لإجراء طلبات البيانات من واجهة برمجة التطبيقات، وليس بالمستخدمين الفرديين أو حسابات الخدمة. بعد تسجيل مشروع على Google Cloud بنجاح باستخدام حسابك الأساسي على Merchant Center، يمكنك استخدام أي هوية تتم إدارتها من خلال مشروع Google Cloud المرتبط باستخدام بيانات اعتماد OAuth أو حسابات الخدمة للسماح باستدعاءات Merchant API، شرط أن تكون هذه الهوية متوفرة في حسابك على Merchant Center وأن يكون لها دور ADMIN.

كيف يمكنني تغيير عنوان البريد الإلكتروني المخصّص للتواصل مع المطوّر بعد التسجيل الأوّلي؟

لإدارة جهات الاتصال أو تغييرها، استخدِم خدمة accounts.users العادية أو صفحة "الوصول والخدمات" في واجهة مستخدم Merchant Center لإضافة مستخدمين لديهم دور API Developer أو إزالتهم.

ماذا يحدث إذا تمت إزالة آخر مستخدم لديه إذن "مطوّر واجهة برمجة التطبيقات" من حساب Merchant Center؟

يتم تفعيل فترة سماح مدتها 30 يومًا لتجنُّب انقطاع الخدمة على الفور. خلال هذه الفترة:

  • سيتلقّى المشرفون ثلاثة إشعارات إلزامية بشأن الخدمة عبر البريد الإلكتروني (عادةً قبل 30 و17 و4 أيام من الحظر).
  • ستستمر طلبات البيانات من واجهة برمجة التطبيقات في العمل بشكل طبيعي.
  • إذا لم تتم إضافة API Developer جديد قبل انتهاء فترة السماح، سيتم حظر طلبات البيانات من واجهة برمجة التطبيقات الواردة من مشاريع Google Cloud المرتبطة، وسيظهر الخطأ AUTH_GCP_NOT_REGISTERED.

عند انتهاء فترة السماح البالغة 30 يومًا، يتم حظر طلبات البيانات من واجهة برمجة التطبيقات الواردة من مشاريع Google Cloud المرتبطة، ويتم عرض الخطأ AUTH_GCP_NOT_REGISTERED إلى أن تتم استعادة معلومات الاتصال الصحيحة الخاصة بالمطوّر.

ماذا يحدث إذا تم حذف معرّف Merchant Center الذي تم تسجيل المطوِّر من خلاله؟

لا تحذف حساب Merchant Center المستخدَم لتسجيل المطوّرين طالما أنّ عملية الدمج نشطة. سيؤدي حذف هذا الحساب إلى إيقاف عملية الدمج على الفور، ولن تتمكّن بعد ذلك من تنفيذ طلبات البيانات من واجهة برمجة التطبيقات من مشروع Google Cloud المرتبط.

إذا كان عليك حذف حساب Merchant Center هذا، عليك أولاً استدعاء طريقة unregisterGcp لإزالة الرابط بأمان، ثم المتابعة لحذف رقم تعريف Merchant Center. إذا أردت مواصلة استخدام Merchant API، عليك التسجيل باستخدام معرّف Merchant Center آخر بعد إلغاء تسجيل المعرّف الحالي مباشرةً. بعد ذلك فقط، يمكنك المتابعة وحذف معرّف Merchant Center.

حالات الاستخدام الخاصة

الأسئلة الشائعة حول حالات الاستخدام الخاصة:

أنا وكالة أو مطوّر خارجي يدير حسابات تجّار متعدّدة. ما هي أفضل طريقة لإعداد ذلك؟

على المطوّرين والوكالات التابعة لجهات خارجية الاحتفاظ بحسابهم الأساسي على Merchant Center وتسجيل جميع مشاريعهم على Google Cloud في هذا الحساب المركزي الواحد. لا تسجِّل مشروعك على Google Cloud باستخدام حساب كل تاجر على حدة.

كيف يعمل التسجيل في "برمجة تطبيقات Google"؟

يتم عادةً تشغيل برمجة تطبيقات على مشروع على السحابة الإلكترونية تلقائي. يجب تسجيل معرّف Google Cloud التلقائي هذا في حسابك على Merchant Center. تحصل واجهة برمجة التطبيقات تلقائيًا على معرّف Google Cloud، لذا لا تحتاج إلى تقديمه كمَعلمة.

هل يمكنني التحقّق ممّا إذا كان معرّف Merchant Center مسجّلاً في رقم تعريف مشروع Google Cloud معيّن؟

نعم. يمكنك التحقّق من معرّف Merchant Center المسجّل في مشروع معيّن على Google Cloud باستخدام طريقة getAccountForGcpRegistration. لإزالة رابط مشروع Google Cloud بحسابك على Merchant Center، استخدِم طريقة unregisterGcp.