v1beta에서 v1로 마이그레이션

이 가이드에서는 Merchant API v1beta에서 정식 버전인 v1로 이전하는 방법을 설명합니다. v1 버전에는 여러 업데이트와 코드 업데이트가 필요할 수 있는 몇 가지 변경사항이 도입되었습니다. 이번 변경사항은 API를 간소화하고 판매자 센터 계정 관리를 개선하기 위해 마련되었습니다.

주요 차이점

v1beta에서 v1로 이전할 때 알아야 할 가장 중요한 변경사항은 다음과 같습니다.

• Merchant API를 사용하기 위한 하나 이상의 API 개발자 일회성 등록: registerGcp 메서드를 호출하여 (인증에 사용되는 각 Google Cloud 프로젝트에 대해 한 번만) 연락처 세부정보를 제공해야 합니다. 이렇게 하면 API를 사용하고 Merchant API와 관련된 업데이트 및 공지사항을 받을 수 있습니다. 이 단계를 완료할 때까지 v1 또는 v1alpha API를 사용할 수 없습니다. 안내는 개발자로 등록하기를 참고하세요.
• Product.attributes 이름 변경: Product.attributes 필드의 이름이 Product.productAttributes로 변경되었습니다.
• 제품 수준 세금 정보 삭제: taxes 및 taxCategory 필드가 Product.productAttributes 객체에서 삭제되었습니다. 자세한 내용은 세금에 관한 Google 판매자 센터 도움말을 참고하세요.
• GTIN 필드 변경: 여러 값을 보유할 수 있음을 더 잘 반영하기 위해 Product.productAttributes 객체의 gtin 필드 이름이 gtins로 바뀌었습니다. OrderTrackingSignals.lineItemDetails 객체의 gtin 필드가 이제 array이며 gtins로 이름이 바뀌었습니다.
• 채널 필드 삭제: channel 필드가 제품, 제품 입력, 데이터 소스에서 삭제되었습니다. 오프라인 매장에서만 판매되는 제품을 명확하게 지정하기 위해 새로운 불리언 필드인 legacyLocal가 도입되었습니다. 참고: legacyLocal 필드는 이전 작업을 지원하는 보조 필드이며, 온라인 및 오프라인 마케팅 방법을 단일 제품 소스로 완전히 타겟팅할 수 있게 되면 결국 지원 중단됩니다. 자세한 내용은 다음 섹션의 표를 확인하세요.
• 리전별 및 오프라인 판매점 인벤토리 속성의 새로운 필드:
  • name, account, region를 제외한 모든 RegionalInventory 필드가 이제 regionalInventoryAttributes이라는 새 객체 아래에 래핑됩니다. 예를 들어 RegionalInventory.price 속성은 이제 RegionalInventory.regionalInventoryAttributes.price 아래에 있습니다.
  • name, account, storeCode를 제외한 모든 LocalInventory 필드가 이제 localInventoryAttributes이라는 새 객체 아래에 래핑됩니다. 예를 들어 LocalInventory.price 속성은 이제 LocalInventory.localInventoryAttributes.price 아래에 있습니다.
• 지역 및 오프라인 인벤토리에서 customAttributes 삭제: customAttributes 필드가 RegionalInventory 및 LocalInventory 리소스에서 삭제되었습니다.
• 계정 생성 개선: 중복된 users 필드가 CreateAndConfigureAccountRequest에서 삭제되었습니다. 단수형 user 필드를 사용하여 초기 사용자를 새 계정과 연결합니다.
• 특정 속성 유형이 문자열에서 enum으로 변경됨: 값이 정의된 짧은 목록이 있는 Product 및 Inventory 리소스 내 일부 필드가 더 나은 데이터 검증을 위해 string 유형에서 enum 유형으로 변경되었습니다 (예: Product.ProductAttributes.condition 필드가 이제 enum임).
• 온라인 반품 정책 업데이트 메서드 삭제: onlineReturnPolicy.update 메서드가 v1에서 삭제됩니다. 대신 onlineReturnPolicy.create 메서드를 사용하여 온라인 반품 정책을 만드세요.

마이그레이션 방법

Merchant API의 v1beta 버전은 2026년 2월 28일에 지원 중단될 예정입니다. 지원 중단 일정에 대한 자세한 내용은 판매자 API 버전 관리 가이드를 참고하세요.

• 이전의 첫 번째 단계는 일회성 개발자 등록을 실행하는 것입니다(개발자로 등록하기 참고). v1 메서드가 작동하려면 인증에 사용하는 각 Google Cloud 프로젝트에 대해 registerGcp 메서드를 호출해야 합니다.

• API를 호출하는 방법 (REST, gRPC 또는 클라이언트 라이브러리 사용)에 관계없이 단계별로 이전할 수 있습니다. 즉, 전체 통합을 한 번에 업데이트하지 않고도 한 번에 하나의 API씩 코드를 업데이트하고 이전할 수 있습니다 (예: Accounts API를 v1beta에 유지하면서 Products API를 v1로 이동).

세부 필드 변경사항

이 표에서는 v1beta 버전과 v1 버전 간에 변경된 필드를 자세히 비교합니다.

v1beta	v1	설명
Product.gtin	Product.gtins	GTIN 필드의 이름이 변경되었습니다.
Product.taxes	삭제됨	taxes 필드가 삭제되었습니다.
Product.taxCategory	삭제됨	taxCategory 필드가 삭제되었습니다.
Product.channel	삭제됨	channel 필드가 삭제되었습니다. 로컬 사용 사례에는 legacyLocal 필드를 사용합니다.
Product.attributes	Product.productAttributes	attributes 필드의 이름이 productAttributes로 변경되었습니다.
Product 필드의 availability, condition, gender, includedDestinations, excludedDestinations은 strings (또는 strings의 array)로 표시됩니다.	이제 이러한 필드는 enums (또는 enums의 array)입니다.	정의된 짧은 값 목록이 있는 필드가 string 유형에서 enum로 변경되었습니다.
RegionalInventory의 price, salePrice, salePriceEffectiveDate, availability	RegionalInventory.regionalInventoryAttributes 폴더로 이동했습니다.	이러한 필드는 regionalInventoryAttributes 아래로 이동되었습니다.
RegionalInventory.availability 필드가 string임	RegionalInventory.regionalInventoryAttributes.availability은 이제 enums입니다.	사용 가능 여부 유형이 string에서 enum로 변경되었습니다.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla, instoreProductLocation(LocalInventory)	LocalInventory.localInventoryAttributes 폴더로 이동했습니다.	이러한 필드는 localInventoryAttributes 아래로 이동되었습니다.
LocalInventory.availability 필드가 string임	LocalInventory.localInventoryAttributes.availability은 이제 enums입니다.	사용 가능 여부 유형이 string에서 enum로 변경되었습니다.
LocalInventory.customAttributes	삭제됨	오프라인 판매점 인벤토리에는 더 이상 맞춤 속성이 지원되지 않습니다.
RegionalInventory.customAttributes	삭제됨	지역 인벤토리의 맞춤 속성은 더 이상 지원되지 않습니다.
ProductInput.channel	삭제됨	channel 필드가 삭제되었습니다. 로컬 사용 사례에는 legacyLocal 필드를 사용합니다.
DataSource.channel	삭제됨	channel 필드가 삭제되었습니다. 로컬 사용 사례에는 legacyLocal 필드를 사용합니다.
사용할 수 없음	ProductInput.legacyLocal	제품이 로컬 마케팅 방법만 타겟팅할 수 있음을 나타내는 새 불리언 필드입니다. 제품 리소스 ID에는 'local~' 접두사가 붙습니다.
사용할 수 없음	Product.legacyLocal	제품이 오프라인 매장에서만 판매되고 온라인 구매가 불가능함을 나타내는 새로운 불리언 필드입니다.
사용할 수 없음	DataSource.legacyLocal	데이터 소스에 오프라인 매장에서만 판매되는 제품이 포함되어 있음을 나타내는 새로운 불리언 필드입니다.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	gtin 필드의 이름이 gtins로 변경되었으며 이제 문자열이 아닌 문자열 배열입니다.
CreateAndConfigureAccountRequest.users	삭제됨	users 필드가 삭제되었습니다. user 필드를 사용하여 계정에 초기 관리자를 추가합니다.