계정 관리 이전

Accounts API는 계정의 다양한 측면을 더 정밀하게 제어하여 판매자 센터 계정을 더 효율적으로 관리할 수 있도록 리소스 모음으로 나뉩니다.

이 가이드에서는 주요 변경사항을 설명하고 기존 계정 관리 통합을 Content API for Shopping에서 Merchant API로 이전하는 방법을 안내합니다.

하나의 리소스에서 다수의 리소스로

Content API for Shopping에서 Account 리소스는 계정 이름과 웹사이트 URL부터 사용자 목록 및 비즈니스 정보에 이르기까지 모든 것을 포함하는 모놀리식 객체였습니다.

Merchant API는 이를 더 작고 집중적인 여러 리소스로 분할합니다. 이 변경사항을 통해 더 타겟팅되고 효율적인 API 호출이 가능합니다. 예를 들어 비즈니스 주소만 업데이트하려면 이제 전체 Account 객체를 업데이트하는 대신 BusinessInfo 리소스에 PATCH 요청을 수행합니다.

다음은 Content API for Shopping Account 리소스의 개념이 Merchant API의 새 리소스에 매핑되는 방식을 요약한 것입니다.

• 핵심 계정 세부정보 (ID, 이름, 성인용 콘텐츠 설정)는 Account 리소스에 남아 있습니다.
• 비즈니스 정보 (주소, 전화번호, 고객 서비스)는 이제 BusinessInfo 리소스로 관리됩니다.
• 웹사이트 URL 및 소유권 주장은 Homepage 리소스에서 처리합니다.
• 사용자 관리는 User 리소스에서 처리합니다.
• 계정 관계(고급 계정, 서드 파티 제공업체, 기타 Google 서비스에 대한 링크)는 AccountRelationship 및 AccountService 리소스로 관리됩니다.
• 비즈니스 아이덴티티 속성 (예: 흑인이 소유하거나 운영함, 여성이 소유하거나 운영함)은 BusinessIdentity 리소스로 관리됩니다.
• 새로운 기능인 서비스 약관 (ToS) 계약은 TermsOfService 및 TermsOfServiceAgreementState 리소스에서 관리됩니다.

새로운 기능으로

또한 Merchant API에는 Content API for Shopping에서 사용할 수 없었던 계정 관리를 위한 새로운 기능이 도입되었습니다.

• 서비스 약관: TermsOfService 및 TermsOfServiceAgreementState 리소스를 사용하여 프로그래매틱 방식으로 서비스 약관을 검색하고 동의합니다.
• 계정 생성: 이제 accounts.createAndConfigure 메서드가 관계 (예: accountManagement)가 있는 계정 생성, alias 설정, user.verificationMailSettings.verificationMailMode 필드를 사용한 이메일 인증 억제를 지원하여 새로운 accounts.verifySelf 메서드를 사용한 API 기반 인증을 지원합니다.
• 별칭으로 계정 액세스: providerId~accountAlias 형식을 사용하여 계정에 액세스하므로 여러 계정을 관리하는 비즈니스에서 자체 계정 식별자를 일관된 방식으로 사용할 수 있습니다.

요청

이 표에서는 Content API for Shopping과 Merchant API 간의 일반적인 계정 관리 작업에 대한 요청 URL을 통합하여 비교합니다.

요청 설명	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 리소스에는 이름, 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는 이제 출력 전용 필드입니다. 기본 식별자는 리소스 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로 변경되었습니다.

홈페이지 관리하기

매장의 웹사이트 URL을 관리하고 인증 및 소유권 주장을 수행하려면 Homepage 리소스를 사용하세요. 이는 Content API for Shopping의 websiteUrl 필드와 accounts.claimwebsite 메서드를 대체합니다.

요청 비교

요청 설명	Content API for 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 리소스를 사용하면 판매자 센터 계정에 액세스할 수 있는 사용자를 관리할 수 있습니다. 이렇게 하면 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	이제 액세스 권한이 반복 enum 필드로 통합됩니다.
사용 불가	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년 판매자 센터 제품 데이터 사양 업데이트를 참고하세요.

비즈니스 ID 관리

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(열거형)	더 명시적인 선언을 위해 불리언이 enum (SELF_IDENTIFIES_AS, DOES_NOT_SELF_IDENTIFY_AS)으로 대체됩니다. 이는 모든 ID 속성에 적용됩니다.
include_for_promotions (불리언)	promotions_consent(열거형)	전역 불리언이 더 설명적인 enum (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 (경로 매개변수)	accounts/{account} 형식의 고급 계정 ID입니다.
max_results	page_size	반환할 최대 계정 수입니다.