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

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

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

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

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

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

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

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

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

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

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

ننصح باستخدام عنوان البريد الإلكتروني الخاص بموظف في الشركة. بدلاً من ذلك، يمكنك استخدام الأسماء المستعارة العامة للمجموعات. لا يمكنك استخدام عناوين البريد الإلكتروني لحسابات الخدمة، لأنّ الرسائل الإلكترونية مخصّصة للمستلِمين من البشر. ترسل 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.
• الوكالات والمطوّرون والجهات الخارجية الأخرى: إذا كنت مؤسسة تابعة لجهة خارجية، مثل وكالة أو مطوّر تابع لجهة خارجية يدير حسابات تجّار متعددة و ليس لديك معرّف 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 Cloud سبق تسجيله في حساب آخر على 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 عادةً إدارة تعقيدات الحصول على رموز الدخول وإعادة تحميلها نيابةً عنك كجزء من عملية الإعداد.

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

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

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

• تستخدم حسابات الخدمة مفتاحًا خاصًا أو بيانات اعتماد البيئة لإنشاء رمز دخول جديد كلما دعت الحاجة إلى ذلك.
• تستخدم مسارات 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 App Scripts؟

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

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

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