계정 관리 이전

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

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

하나의 리소스에서 여러 리소스로

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

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

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

새로운 기능으로

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

  • 서비스 약관: TermsOfService 및 TermsOfServiceAgreementState 리소스를 사용하여 서비스 약관을 프로그래매틱 방식으로 검색하고 수락합니다.
  • 별칭을 통한 계정 액세스: 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

핵심 계정 정보 관리

판매자 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
비즈니스 ID 가져오기 GET /content/v2.1/{merchantId}/accounts/{accountId} (business_identity 속성 액세스) GET /accounts/v1/accounts/{account}/businessIdentity
비즈니스 ID 업데이트 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 (경로 매개변수) 고급 계정의 ID입니다(accounts/{account} 형식).
max_results page_size 반환할 계정의 최대 개수입니다.