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

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

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

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

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

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

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

كم مرة عليّ التسجيل؟

يتم التسجيل مرة واحدة لكل مشروع على 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.
• الوكالات والمطوّرون والجهات الخارجية الأخرى: إذا كنت تمثّل نشاطًا تجاريًا تابعًا لجهة خارجية، مثل وكالة أو مطوّر خارجي يدير حسابات تجّار متعدّدة وليس لديك معرّف 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"؟

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

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

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

نقل البيانات من Content API إلى Merchant API لمستخدمي تطبيق Google & YouTube على Shopify

الأسئلة الشائعة حول نقل البيانات من Content API إلى Merchant API للمنصات والتطبيقات الخارجية:

هل عليّ اتّخاذ أي إجراء لنقل البيانات من Content API إلى Merchant API؟

ليس عليك اتّخاذ أي إجراء. إذا كنت تستخدم تطبيق Google & YouTube على Shopify لإدارة خلاصاتك في Merchant Center، ستتولّى Google عملية نقل البيانات من Content API إلى Merchant API.

هل سيؤدي نقل البيانات إلى تغيير معرِّفات المنتجات؟

لا تؤدي عملية نقل البيانات إلى تغيير معرِّفات المنتجات في خلاصاتك على Merchant Center.

هل يلزم إعادة تثبيت تطبيق Google & YouTube على Shopify لإكمال عملية الانتقال؟

ليس عليك اتّخاذ أي إجراء لإكمال عملية الانتقال. ليس عليك إعادة تثبيت تطبيق Google & YouTube.

لماذا لا تزال مصادر بيانات Content API تظهر في Merchant Center؟

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