v1beta'dan v1'e taşıma

Bu kılavuz, Merchant API v1beta'den v1'ye (Genel Kullanıma Sunulan ilk sürüm) geçiş yapmanıza yardımcı olur. v1 sürümünde, kod güncellemeleri gerektirebilecek birkaç değişiklik ve çeşitli güncellemeler yapıldı. Bu değişiklikler, API'yi basitleştirmek ve Merchant Center hesabınızın yönetimini iyileştirmek için tasarlanmıştır.

Temel farklar

v1beta sürümünden v1 sürümüne geçerken dikkat etmeniz gereken en önemli değişiklikler şunlardır:

• Merchant API'yi kullanmak için en az bir API geliştiricinin tek seferlik kaydı: İletişim bilgilerinizi sağlamak için registerGcp yöntemini (kimlik doğrulama için kullanılan her Google Cloud projesi için yalnızca bir kez) çağırmanız gerekir. Bu sayede API'yi kullanabilir ve Merchant API ile ilgili güncellemeleri ve duyuruları alabilirsiniz. Bu adım tamamlanana kadar hiçbir v1 veya v1alpha API'sini kullanamazsınız. Talimatlar için Geliştirici olarak kaydolma başlıklı makaleyi inceleyin.

• Ürün adı kodlaması: ProductInput.name ve Product.name alanları, doldurulmamış Base64URL (RFC 4648 Bölüm 5) kodlamasını destekler. Aşağıdaki yönergeleri uygulayın:

  • Dizenin kodlanmadan önce contentLanguage~feedLabel~offerId biçiminde olması gerekir.

  • Ürün adınızda Merchant API tarafından kullanılan karakterler veya URL'de ayrılmış karakterler (ör. aşağıdaki karakterler) varsa kodlama zorunludur:

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • Ürün adınız contentLanguage~feedLabel~offerId biçimine uyuyorsa ve Merchant API veya URL'de ayrılmış karakterler tarafından kullanılan herhangi bir karakter içermiyorsa kodlama olmadan düz biçimi kullanabilirsiniz.

  • Tutarlı ve doğru ayrıştırma için tüm ürün adlarında doldurulmamış base64url kodlaması kullanmanızı öneririz.

• Ürün düzeyinde vergi bilgilerinin kaldırılması: taxes ve taxCategory.

• Product.attributes yeniden adlandırıldı: Product.attributes alanı, Product.productAttributes olarak yeniden adlandırıldı.

• Ürün düzeyinde vergi bilgilerinin kaldırılması: taxes ve taxCategory alanları, Product.productAttributes nesnesinden kaldırıldı. Daha fazla bilgi için vergi hakkındaki Google Merchant Center Yardım makalesini inceleyin.

• GTIN alanında yapılan değişiklikler: Product.productAttributes nesnesindeki gtin alanı, birden fazla değer içerebileceğini daha iyi yansıtmak için gtins olarak yeniden adlandırıldı. OrderTrackingSignals.lineItemDetails nesnesindeki gtin alanı artık array ve gtins olarak yeniden adlandırıldı.

• Kanal alanı kaldırıldı: channel alanı ürünlerden, ürün girişlerinden ve veri kaynaklarından kaldırıldı. Yalnızca fiziksel mağazalarda satılan ürünleri net bir şekilde belirtmek için yeni bir Boole alanı olan legacyLocal kullanıma sunuldu. Not: legacyLocal alanı, taşıma işlemine yardımcı olan bir yardımcı alandır ve internette ve yerel pazarlama yöntemleri tek bir ürün kaynağıyla tam olarak hedeflenebildiğinde kullanımdan kaldırılacaktır. Daha fazla bilgi için aşağıdaki bölümdeki tabloya bakın.

• Bölgesel ve yerel envanter özellikleri için yeni alanlar:

  • name, account ve region dışındaki tüm RegionalInventory alanları artık regionalInventoryAttributes adlı yeni bir nesne altında yer alıyor. Örneğin, RegionalInventory.price özelliği artık RegionalInventory.regionalInventoryAttributes.price altında yer alıyor.
  • name, account ve storeCode dışındaki tüm LocalInventory alanları artık localInventoryAttributes adlı yeni bir nesne altında yer alıyor. Örneğin, LocalInventory.price özelliği artık LocalInventory.localInventoryAttributes.price altında yer alıyor.

• customAttributes özelliğinin bölgesel ve yerel envanterlerden kaldırılması: customAttributes alanı hem RegionalInventory hem de LocalInventory kaynaklarından kaldırıldı.

• Geliştirilmiş hesap oluşturma: Gereksiz users alanı, CreateAndConfigureAccountRequest bölümünden kaldırıldı. İlk kullanıcıyı yeni bir hesapla ilişkilendirmek için tekil user alanını kullanın.

• Belirli özellik türleri dizelerden numaralandırılmış değerlere dönüştürüldü: Product ve Inventory kaynaklarındaki bazı alanlar, tanımlanmış kısa değer listeleriyle birlikte daha iyi veri doğrulaması için string türünden enum türüne dönüştürüldü (örneğin, Product.ProductAttributes.condition alanı artık enum türünde).

• Online iade politikası güncelleme yöntemi kaldırıldı: onlineReturnPolicy.update yöntemi v1 sürümünde kaldırıldı. Bunun yerine onlineReturnPolicy.create yöntemini kullanarak online iade politikası oluşturun.

Taşıma işlemi nasıl yapılır?

Merchant API'nin v1beta sürümünün 28 Şubat 2026'da kullanımdan kaldırılması planlanıyor. Desteği sonlandırma takvimi hakkında daha fazla bilgi için Merchant API sürüm oluşturma kılavuzuna bakın.

• Taşıma işlemindeki ilk adımınız, tek seferlik geliştirici kaydı yapmaktır (Bkz. Geliştirici olarak kaydolma). v1 yöntemlerinin çalışması için kimlik doğrulama amacıyla kullandığınız her Google Cloud projesi için registerGcp yöntemini çağırmanız gerekir.

• API'leri nasıl çağırdığınızdan (REST, gRPC veya istemci kitaplıklarını kullanarak) bağımsız olarak aşamalı olarak taşıma yapabilirsiniz. Bu, kodunuzu tek seferde güncellemek zorunda kalmadan her seferinde bir API'yi güncelleyip taşıyabileceğiniz (ör. Products API'sini v1'ye taşırken Accounts API'sini v1beta'de tutma) anlamına gelir.

Ayrıntılı alan değişiklikleri

Bu tabloda, v1beta ve v1 sürümleri arasında değişen alanların ayrıntılı bir karşılaştırması verilmektedir.

v1beta	v1	Açıklama
ProductInput.name	ProductInput.name	Unpadded base64url encoding Merchant API veya URL'de ayrılmış karakterler içeren ürün adları için desteklenir ve zorunludur.
Product.name	Product.name	Unpadded base64url encoding Merchant API veya URL'de ayrılmış karakterler içeren ürün adları için desteklenir ve zorunludur.
Product.gtin	Product.gtins	GTIN'ler için alanın adı değiştirildi.
Product.taxes	Kaldırıldı	taxes alanı kaldırıldı
Product.taxCategory	Kaldırıldı	taxCategory alanı kaldırıldı
Product.channel	Kaldırıldı	channel alanı kaldırıldı. Yerel kullanım alanları için legacyLocal alanını kullanın.
Product.attributes	Product.productAttributes	attributes alanı, productAttributes olarak yeniden adlandırıldı.
Product alanlarındaki availability, condition, gender, includedDestinations ve excludedDestinations alanları strings (veya strings'nın array'ü) olarak gösterilir.	Bu alanlar artık enums (veya enums'nın array)	Tanımlanmış kısa değer listesine sahip alanlar string türünden enum türüne değiştirildi.
RegionalInventory adlı albümde price, salePrice, salePriceEffectiveDate ve availability	RegionalInventory.regionalInventoryAttributes hedefine taşındı	Bu alanlar regionalInventoryAttributes bölümüne taşındı.
RegionalInventory.availability alanı bir string	RegionalInventory.regionalInventoryAttributes.availability artık enums	Kullanılabilirlik türü string iken enum olarak değiştirildi.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla ve instoreProductLocation LocalInventory	LocalInventory.localInventoryAttributes hedefine taşındı	Bu alanlar localInventoryAttributes bölümüne taşındı.
LocalInventory.availability alanı bir string	LocalInventory.localInventoryAttributes.availability artık enums	Kullanılabilirlik türü string iken enum olarak değiştirildi.
LocalInventory.customAttributes	Kaldırıldı	Özel özellikler artık yerel envanter için desteklenmiyor.
RegionalInventory.customAttributes	Kaldırıldı	Bölgesel envanter için özel özellikler artık desteklenmiyor.
ProductInput.channel	Kaldırıldı	channel alanı kaldırıldı. Yerel kullanım alanları için legacyLocal alanını kullanın.
DataSource.channel	Kaldırıldı	channel alanı kaldırıldı. Yerel kullanım alanları için legacyLocal alanını kullanın.
Kullanılamıyor	ProductInput.legacyLocal	Bir ürünün yalnızca yerel pazarlama yöntemlerini hedefleyebileceğini belirten yeni bir boolean alanı. Ürün kaynağı kimliğinde "local~" öneki bulunur.
Kullanılamıyor	Product.legacyLocal	Bir ürünün yalnızca yerel mağazalarda satıldığını ve online satın alınamayacağını belirten yeni bir Boole alanı.
Kullanılamıyor	DataSource.legacyLocal	Bir veri kaynağının yalnızca yerel mağazalarda satılan ürünler içerdiğini belirten yeni bir Boole alanı.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	gtin alanı gtins olarak yeniden adlandırıldı ve artık bir dize dizisi (dize yerine) olarak kullanılıyor.
CreateAndConfigureAccountRequest.users	Kaldırıldı	users alanı kaldırıldı. Hesaba ilk yöneticiyi eklemek için user alanını kullanın.