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

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

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

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

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

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

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

كم مرة يجب التسجيل؟

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

هل يمكنني تسجيل حساب فرعي أديره لأحد العملاء؟

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

هل يجب المطالبة بموقعي الإلكتروني أو تأكيده فقط؟

للتسجيل كمطوِّر، يجب أن يكون الموقع الإلكتروني مثبت الملكية. ويثبت ذلك أنّ لديك تحكّمًا إداريًا في الموقع الإلكتروني المرتبط بالحساب. مع أنّ المطالبة ضرورية لميزات أخرى، مثل "إعلانات Shopping"، إلا أنّ إثبات الملكية هو الشرط الأساسي للتسجيل في واجهة برمجة التطبيقات.

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

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

أعمل مع حسابات متعدّدة على 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 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 عادةً معالجة تعقيدات الحصول على رموز الدخول وتحديثها نيابةً عنك كجزء من عملية الإعداد.

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

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

تنتهي صلاحية رموز الدخول لكل من حسابات الخدمة والإصدار 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"؟

دور 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"؟

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

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

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