遷移帳戶管理

帳戶 API 分為多個資源集合，可讓您更有效率地管理 Merchant Center 帳戶，並更精確地控管帳戶的各個層面。

本指南說明主要異動，並協助您將現有的帳戶管理整合功能從 Shopping 的 Content API 遷移至 Merchant API。

從單一資源到多個資源

在 Shopping 內容 API 中，Account 資源是單一物件，包含帳戶名稱、網站網址、使用者清單和商家資訊等所有內容。

Merchant API 會將這項資源拆分成多個較小的資源，並著重於特定用途。這項異動可讓您更有效率地呼叫 API，舉例來說，如要只更新商家地址，現在可以對 BusinessInfo 資源提出 PATCH 要求，不必更新整個 Account 物件。

以下摘要說明 Content API for Shopping Account 資源如何對應至 Merchant API 中的新資源：

新功能

Merchant API 也推出新的帳戶管理功能，這些功能在 Content API for Shopping 中無法使用：

  • 服務條款：使用 TermsOfService 和 TermsOfServiceAgreementState 資源，以程式輔助方式擷取及接受服務條款。
  • 透過別名存取帳戶：使用「 providerId~accountAlias」格式存取帳戶，為管理多個帳戶的商家提供一致的方式，使用自己的帳戶 ID。

要求

下表整合比較 Content API for Shopping 和 Merchant API 中，常見帳戶管理工作的要求網址。

要求說明 Content API for 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

管理核心帳戶資訊

Merchant API 中的 Account 資源包含 Merchant Center 帳戶的基本詳細資料，例如名稱、ID 和基本設定。

要求比較

要求說明 Content API for 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 數字 ID 現在是僅供輸出的欄位。主要 ID 是資源 name。
name account_name 帳戶的使用者可解讀名稱。
language language_code 欄位名稱現為「language_code」。

管理商家資訊

使用 BusinessInfo 資源管理商家公開資訊，例如地址和客戶服務聯絡人。這會取代 Content API for Shopping 中的 businessInformation 物件。

要求比較

要求說明 Content API for 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」。

管理首頁

如要管理商店網站網址，並執行驗證和聲明擁有權作業，請使用 Homepage 資源。這會取代 Content API for Shopping 的 websiteUrl 欄位和 accounts.claimwebsite 方法。

要求比較

要求說明 Content API for Shopping Merchant API
取得首頁網址 GET /content/v2.1/{merchantId}/accounts/{accountId} (存取 website_url 屬性) GET /accounts/v1/accounts/{account}/homepage
更新首頁網址 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 商店首頁的網址。
無法直接使用 claimed 布林值欄位，如果已聲明首頁，則為 true。

管理使用者

User 資源可讓您管理誰能存取 Merchant Center 帳戶。這會取代 Account 資源中的 users 陣列。主要差異在於使用者建立程序。在 Merchant API 中新增使用者時，系統會傳送邀請。使用者必須先接受邀請，才能存取帳戶。

要求比較

要求說明 Content API for 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 資源，因此需要交握程序 (提議和接受)。

要求比較

要求說明 Content API for 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) 提供服務的帳戶 ID。
service service_type (位於 AccountService) 提供的服務類型 (例如ACCOUNT_AGGREGATION)。
status handshake.approval_state (位於 AccountService) 連結的狀態 (例如PENDING、ESTABLISHED)。

帳戶稅金設定

Content API for Shopping 的 accounttax 服務不適用於 Merchant API。現在不必提供美國銷售稅，詳情請參閱「2025 年 Merchant Center 產品資料規格更新」。

管理商家身分

使用 BusinessIdentity 資源自行聲明商家屬性。這會取代 Content API for Shopping 中的 businessIdentity 物件。

要求比較

要求說明 Content API for 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 提供與 Content API for Shopping 的 accounts.list 直接對應的 accounts.listSubaccounts 方法。我們即將推出更強大的新方法，accounts.list可進行進階帳戶篩選。

要求比較

要求說明 Content API for 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 (路徑參數) 進階帳戶的 ID，格式為 accounts/{account}。
max_results page_size 要傳回的帳戶數量上限。