نقل إدارة الحساب

تنقسم Accounts API إلى مجموعة من الموارد تتيح إدارة حساباتك على Merchant Center بشكل أكثر فعالية مع إمكانية التحكّم بشكل أكثر دقة في مختلف جوانب حسابك.

يوضّح هذا الدليل التغييرات الرئيسية ويساعدك في نقل عملية دمج إدارة الحساب الحالية من Content API for Shopping إلى Merchant API.

من مصدر واحد إلى مصادر متعددة

في Content API for Shopping، كان العنصر Account عبارة عن كائن متكامل يحتوي على كل شيء، بدءًا من اسم الحساب وعنوان URL للموقع الإلكتروني وصولاً إلى قوائم المستخدمين ومعلومات النشاط التجاري.

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

في ما يلي ملخّص حول كيفية ربط المفاهيم من مرجع Content API for ShoppingAccount بالمراجع الجديدة في Merchant API:

الإمكانات الجديدة

توفّر Merchant API أيضًا إمكانات جديدة لإدارة الحسابات لم تكن متاحة في Content API for Shopping، وهي:

  • بنود الخدمة: يمكنك استرداد بنود الخدمة وقبولها آليًا باستخدام الموردَين TermsOfService وTermsOfServiceAgreementState.
  • إنشاء الحساب: تتيح طريقة accounts.createAndConfigure الآن إنشاء حسابات تتضمّن علاقات (مثل accountManagement)، وتحديد alias، وإيقاف عملية إثبات ملكية عنوان البريد الإلكتروني باستخدام الحقل user.verificationMailSettings.verificationMailMode بدلاً من إثبات الملكية المستند إلى واجهة برمجة التطبيقات باستخدام الطريقة الجديدة accounts.verifySelf.
  • الوصول إلى الحساب باستخدام الاسم المستعار: يمكنك الوصول إلى الحسابات باستخدام التنسيق providerId~accountAlias، ما يوفّر طريقة متّسقة للأنشطة التجارية التي تدير حسابات متعدّدة لاستخدام معرّفات حساباتها الخاصة.

الطلبات

يقدّم هذا الجدول مقارنة موحّدة لعناوين URL الخاصة بالطلبات المتعلقة بمهام إدارة الحسابات الشائعة بين Content API for Shopping وMerchant API.

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
الحصول على حساب GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
الحصول على حساب من خلال الاسم المستعار غير متوفّر بشكل مباشر GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
إدراج الحسابات الفرعية GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts
إنشاء حساب فرعي POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure
تعديل بيانات الحساب PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} PATCH على المرجع المناسب. على سبيل المثال، لتعديل اسم الحساب: PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
حذف حساب فرعي DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
المطالبة بالموقع الإلكتروني POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim
ربط الحسابات POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose

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

يتضمّن مرجع Account في Merchant API التفاصيل الأساسية لحساب Merchant Center، مثل اسمه ورقم تعريفه وإعداداته الأساسية.

طلب المقارنة

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
الحصول على تفاصيل الحساب GET /content/v2.1/{merchantId}/accounts/{accountId} (الوصول إلى السمات الأساسية، مثل name وadult_content) GET /accounts/v1/accounts/{account}
إنشاء حساب فرعي POST /content/v2.1/{merchantId}/accounts POST /accounts/v1/accounts:createAndConfigure
تعديل تفاصيل الحساب PUT /content/v2.1/{merchantId}/accounts/{accountId} (تعديل السمات الأساسية) PATCH /accounts/v1/accounts/{account}
حذف حساب فرعي DELETE /content/v2.1/{merchantId}/accounts/{accountId} DELETE /accounts/v1/accounts/{account}

مقارنة تفصيلية للحقول

‫Content API for Shopping (Account) ‫Merchant API (Account) ملاحظات
id account_id أصبح المعرّف الرقمي الآن حقل إخراج فقط. المعرّف الأساسي هو المرجع name.
name account_name تمثّل هذه السمة اسم الحساب الذي يمكن للمستخدم قراءته.
language language_code أصبح اسم الحقل الآن language_code.

إدارة معلومات المؤسسة

استخدِم مورد BusinessInfo لإدارة المعلومات المتاحة للجميع عن نشاطك التجاري، مثل العنوان ومعلومات التواصل مع فريق خدمة العملاء. يحلّ هذا النوع محلّ العنصر businessInformation في Content API for Shopping.

طلب المقارنة

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
الحصول على معلومات النشاط التجاري GET /content/v2.1/{merchantId}/accounts/{accountId} (الوصول إلى السمة business_information) GET /accounts/v1/accounts/{account}/businessInfo
تعديل معلومات النشاط التجاري PUT /content/v2.1/{merchantId}/accounts/{accountId} (تعديل السمة business_information) PATCH /accounts/v1/accounts/{account}/businessInfo

مقارنة تفصيلية للحقول

‫Content API for Shopping (business_information) ‫Merchant API (BusinessInfo) ملاحظات
phone_number phone أصبح الحقل الآن phone ويستخدم google.type.PhoneNumber.
customer_service.url customer_service.uri أصبح اسم الحقل الآن uri.

إدارة صفحتك الرئيسية

لإدارة عنوان URL الخاص بالموقع الإلكتروني لمتجرك وإجراء عملية إثبات الملكية والمطالبة، استخدِم مورد Homepage. يحلّ هذا الحقل محلّ الحقل websiteUrl والطريقة accounts.claimwebsite من Content API for Shopping.

طلب المقارنة

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
الحصول على عنوان URL للصفحة الرئيسية GET /content/v2.1/{merchantId}/accounts/{accountId} (الوصول إلى السمة website_url) GET /accounts/v1/accounts/{account}/homepage
تعديل عنوان URL للصفحة الرئيسية PUT /content/v2.1/{merchantId}/accounts/{accountId} (تعديل السمة website_url) PATCH /accounts/v1/accounts/{account}/homepage
المطالبة بالصفحة الرئيسية POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite POST /accounts/v1/accounts/{account}/homepage:claim
إلغاء المطالبة بالصفحة الرئيسية غير متوفر POST /accounts/v1/accounts/{account}/homepage:unclaim

مقارنة تفصيلية للحقول

‫Content API for Shopping (Account) ‫Merchant API (Homepage) ملاحظات
website_url uri تمثّل هذه السمة عنوان URL للصفحة الرئيسية الخاصة بالمتجر.
غير متوفّر بشكل مباشر claimed حقل منطقي تكون قيمته true إذا تمّت المطالبة بالصفحة الرئيسية.

إدارة المستخدمين

يتيح لك مرجع User إدارة المستخدمين الذين يمكنهم الوصول إلى حساب على Merchant Center. يحلّ هذا الحقل محلّ مصفوفة users ضمن المورد Account. ويكمن الاختلاف الرئيسي في عملية إنشاء المستخدم. في Merchant API، تؤدي إضافة مستخدم إلى إرسال دعوة. على المستخدم قبول الدعوة قبل أن يتمكّن من الوصول إلى الحساب.

طلب المقارنة

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
قائمة المستخدمين GET /content/v2.1/{merchantId}/accounts/{accountId} (الوصول إلى السمة users) GET /accounts/v1/accounts/{account}/users
إنشاء مستخدم PUT /content/v2.1/{merchantId}/accounts/{accountId} (تعديل السمة users) POST /accounts/v1/accounts/{account}/users
تعديل مستخدم PUT /content/v2.1/{merchantId}/accounts/{accountId} (تعديل السمة users) PATCH /accounts/v1/accounts/{account}/users/{email}
حذف مستخدم PUT /content/v2.1/{merchantId}/accounts/{accountId} (تعديل السمة users) DELETE /accounts/v1/accounts/{account}/users/{email}

مقارنة تفصيلية للحقول

‫Content API for Shopping (عنصر مصفوفة users) ‫Merchant API (المورد User) ملاحظات
email_address ‫name (بالتنسيق accounts/{account}/users/{email}) أصبح عنوان البريد الإلكتروني للمستخدم الآن جزءًا من اسم المورد.
admin، order_manager، reporting_manager، إلخ access_rights تم الآن دمج أذونات الوصول في حقل تعداد متكرر.
غير متوفر state حقل جديد مخصّص للإخراج فقط يشير إلى ما إذا كان المستخدم PENDING أو VERIFIED.

إدارة علاقات الحسابات والخدمات

في Content API for Shopping، كانت تتم إدارة العلاقات باستخدام accounts.link. توفّر Merchant API نموذجًا أكثر وضوحًا يتضمّن موارد AccountService و AccountRelationship، ما يتطلّب إجراء عملية مصافحة (اقتراح وقبول).

طلب المقارنة

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
ربط الحسابات POST /content/v2.1/{merchantId}/accounts/{accountId}/link POST /accounts/v1/accounts/{account}/services:propose
عرض قائمة بالحسابات المرتبطة GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks GET /accounts/v1/accounts/{account}/relationships وGET /accounts/v1/accounts/{account}/services

مقارنة تفصيلية للحقول

‫Content API for Shopping (AccountLink) Merchant API (AccountService، AccountRelationship) ملاحظات
linked_account_id ‫provider (في AccountService) معرّف الحساب الذي يقدّم الخدمة
service ‫service_type (في AccountService) نوع الخدمة المقدَّمة (مثل ACCOUNT_AGGREGATION).
status ‫handshake.approval_state (في AccountService) حالة الرابط (مثلاً PENDING, ESTABLISHED).

إعدادات الضريبة في الحساب

لا تتوفّر خدمة accounttax من Content API for Shopping في Merchant API. لم يعُد مطلوبًا تقديم ضريبة المبيعات في الولايات المتحدة. لمزيد من المعلومات، يُرجى الاطّلاع على التعديلات المتعلقة بمواصفات بيانات المنتجات للعام 2025 في Merchant Center.

إدارة هوية النشاط التجاري

استخدِم مورد BusinessIdentity للإفصاح الذاتي عن سمات نشاطك التجاري. يحلّ هذا النوع محل الكائن businessIdentity في Content API for Shopping.

طلب المقارنة

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
الحصول على هوية النشاط التجاري GET /content/v2.1/{merchantId}/accounts/{accountId} (الوصول إلى السمة business_identity) GET /accounts/v1/accounts/{account}/businessIdentity
تعديل المعلومات الأساسية للنشاط التجاري PUT /content/v2.1/{merchantId}/accounts/{accountId} (تعديل السمة business_identity) PATCH /accounts/v1/accounts/{account}/businessIdentity

مقارنة تفصيلية للحقول

‫Content API for Shopping (business_identity) ‫Merchant API (BusinessIdentity) ملاحظات
black_owned.self_identified (قيمة منطقية) black_owned.identity_declaration (تعداد) تم استبدال القيمة المنطقية بقيمة تعداد (SELF_IDENTIFIES_AS، DOES_NOT_SELF_IDENTIFY_AS) لتوضيح البيان بشكل أكبر. وينطبق ذلك على جميع سمات الهوية.
include_for_promotions (قيمة منطقية) promotions_consent (تعداد) يتم استبدال قيمة منطقية عامة بتعداد وصفي أكثر (PROMOTIONS_CONSENT_GIVEN، PROMOTIONS_CONSENT_DENIED).

سرد الحسابات

في Content API for Shopping، كان نوع الحساب المتقدّم الوحيد هو "الحساب المتعدّد العملاء" (MCA)، وكان يعرض طريقة accounts.list لإدراج حسابات الحساب المتعدّد العملاء المحدّد. تتسم الحسابات المتقدّمة في Merchant API بقدرات أكبر بكثير، ما يتيح نطاقًا أوسع من أنواع الحسابات والعلاقات. للسماح بعملية نقل مباشرة للحسابات المتقدّمة، توفّر Merchant API مكافئًا مباشرًا لـ accounts.list في Content API for Shopping كطريقة accounts.listSubaccounts. نقدّم طريقة جديدة وأكثر فعالية accounts.list تتيح فلترة الحسابات المتقدّمة.

طلب المقارنة

وصف الطلب واجهة برمجة تطبيقات المحتوى في Shopping Merchant API
عرض قائمة بحسابات حساب بامتيازات متقدّمة GET /content/v2.1/{merchantId}/accounts GET /accounts/v1/accounts/{providerId}:listSubaccounts
إدراج جميع الحسابات التي يمكن الوصول إليها غير متوفر GET /accounts/v1/accounts

مقارنة تفصيلية بين الحقول (مَعلمات الطلب)

‫Content API for Shopping (accounts.list) ‫Merchant API (accounts.listSubaccounts) ملاحظات
‫merchant_id (مَعلمة المسار) ‫provider (مَعلمة المسار) رقم تعريف الحساب المتقدّم بالتنسيق accounts/{account}.
max_results page_size الحد الأقصى لعدد الحسابات المطلوب عرضه.