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

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

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

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

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

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

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

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

التسجيل هو عملية إعداد لمرة واحدة لكل مشروع على السحابة الإلكترونية من Google. سواء كنت تعمل مع حسابات التاجر متعددة أم لا، عليك إجراء عملية التسجيل مرة واحدة فقط، وهي تنطبق على جميع المستخدمين وحسابات الخدمة ضمن مشروع 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 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"؟

دور 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 أو إزالتهم.

ماذا يحدث إذا تمت إزالة آخر مستخدم لديه دور "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.

لماذا لا يمكنني الاطّلاع على دور "API developer" في Merchant Center؟

لا يظهر دور API developer في واجهة مستخدم Merchant Center إلا بعد إجراء تسجيل المطوّر لحساب Merchant Center المحدّد. لا يظهر دور API developer في حسابات 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.