از v1beta به v1 مهاجرت کنید

این راهنما به شما کمک می‌کند از Merchant API v1beta به v1 ، اولین نسخه برای دسترسی عمومی، مهاجرت کنید. نسخه v1 چندین به روز رسانی و چند تغییر را معرفی می کند که ممکن است به به روز رسانی کد نیاز داشته باشد. این تغییرات برای ساده‌سازی API و بهبود مدیریت حساب Merchant Center شما طراحی شده‌اند.

تفاوت های کلیدی

در اینجا مهمترین تغییراتی است که باید هنگام مهاجرت از v1beta به v1 از آنها آگاه باشید:

• ثبت‌نام یک‌باره حداقل یک توسعه‌دهنده API برای استفاده از Merchant API: شما باید با روش registerGcp (فقط یک بار برای هر پروژه Google Cloud که برای احراز هویت استفاده می‌شود) تماس بگیرید تا جزئیات تماس خود را ارائه دهید، که به شما امکان می‌دهد از API استفاده کنید و به‌روزرسانی‌ها و اعلان‌های مربوط به Merchant API را دریافت کنید. تا زمانی که این مرحله کامل نشود، نمی‌توانید از هیچ API v1 یا v1alpha استفاده کنید. برای دستورالعمل ها، به ثبت نام به عنوان توسعه دهنده مراجعه کنید
• Product.attributes renamed : قسمت Product.attributes به Product.productAttributes تغییر نام داده است.
• حذف اطلاعات مالیاتی در سطح محصول: فیلدهای taxes و taxCategory از شی Product.productAttributes حذف شده اند. برای اطلاعات بیشتر ، مقاله راهنمای Google Merchant Center درباره مالیات را بررسی کنید
• تغییرات در فیلد GTIN: فیلد gtin در شی Product.productAttributes به gtins تغییر نام داده است تا بهتر نشان دهد که می تواند چندین مقدار را در خود نگه دارد. فیلد gtin در شی OrderTrackingSignals.lineItemDetails اکنون یک array است و به gtins نیز تغییر نام داده است.
• حذف فیلد کانال: فیلد channel از محصولات، ورودی محصول و منابع داده حذف شده است. یک فیلد بولی جدید، legacyLocal ، معرفی شده است که به وضوح محصولاتی را که منحصراً در فروشگاه‌های فیزیکی فروخته می‌شوند، مشخص می‌کند. توجه: فیلد legacyLocal یک فیلد کمکی برای کمک به مهاجرت است و در نهایت زمانی که روش‌های بازاریابی آنلاین و محلی به طور کامل با یک منبع محصول مورد هدف قرار گیرند، منسوخ خواهد شد. برای اطلاعات بیشتر جدول در بخش زیر را بررسی کنید.
• فیلدهای جدید برای ویژگی های موجودی منطقه ای و محلی :
  • همه فیلدهای RegionalInventory به جز name ، account و region اکنون تحت یک شی جدید به نام regionalInventoryAttributes پیچیده شده‌اند. به عنوان مثال، ویژگی RegionalInventory.price اکنون تحت RegionalInventory.regionalInventoryAttributes.price است.
  • همه فیلدهای LocalInventory به جز name ، account و storeCode اکنون تحت یک شی جدید به نام localInventoryAttributes پیچیده شده‌اند. به عنوان مثال، ویژگی LocalInventory.price اکنون تحت LocalInventory.localInventoryAttributes.price است.
• حذف customAttributes از موجودی های منطقه ای و محلی: قسمت customAttributes از منابع RegionalInventory و LocalInventory حذف شده است.
• ایجاد حساب تصفیه شده: فیلد users اضافی از CreateAndConfigureAccountRequest حذف شده است. از فیلد user منفرد برای مرتبط کردن یک کاربر اولیه با یک حساب جدید استفاده کنید.
• انواع مشخصه‌های مشخصی از رشته‌ها به enums تغییر یافتند: برخی از فیلدهای موجود در منابع Product و Inventory با فهرست کوتاهی از مقادیر از نوع string به نوع enum برای اعتبارسنجی بهتر داده‌ها تغییر کردند (به عنوان مثال، فیلد Product.ProductAttributes.condition اکنون یک enum است).
• حذف روش به روز رسانی سیاست بازگشت آنلاین: روش onlineReturnPolicy.update در v1 حذف شده است. در عوض با استفاده از روش onlineReturnPolicy.create یک خط مشی بازگشت آنلاین ایجاد کنید.

نحوه مهاجرت

نسخه v1beta Merchant API قرار است در 28 فوریه 2026 غروب شود. برای اطلاعات بیشتر در مورد زمان‌بندی منسوخ شدن، به راهنمای نسخه‌سازی Merchant API مراجعه کنید.

• اولین قدم شما در مهاجرت، انجام یک بار ثبت نام توسعه دهنده است (به ثبت نام به عنوان توسعه دهنده مراجعه کنید). قبل از اینکه هر روش v1 کار کند، باید برای هر پروژه Google Cloud که برای احراز هویت استفاده می کنید، متد registerGcp فراخوانی کنید.

• صرف نظر از نحوه فراخوانی API ها (با REST، gRPC یا با استفاده از کتابخانه های سرویس گیرنده )، می توانید به صورت مرحله ای مهاجرت کنید. این بدان معناست که می‌توانید کد خود را یکبار API به‌روزرسانی و انتقال دهید (برای مثال، انتقال API Products به v1 در حالی که API Accounts روی v1beta نگه‌دارید) بدون نیاز به به‌روزرسانی کل یکپارچه‌سازی خود در یک زمان.

تغییرات میدان دقیق

این جدول مقایسه دقیقی از فیلدهایی که بین نسخه های 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 تغییر نام داده است.
availability ، condition ، gender ، includedDestinations و excludedDestinations در فیلدهای Product به صورت strings (یا array از strings ) نشان داده می‌شوند.	این فیلدها اکنون enums (یا array از enums ) هستند.	فیلدهایی با لیست کوتاه تعریف شده از مقادیر از نوع string به enum تغییر یافتند.
price , salePrice , salePriceEffectiveDate تاریخ و availability در موجودی RegionalInventory	به 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	یک فیلد بولی جدید برای نشان دادن اینکه یک محصول فقط می تواند روش های بازاریابی محلی را هدف قرار دهد. شناسه منبع محصول دارای پیشوند "local~" خواهد بود.
در دسترس نیست	Product.legacyLocal	یک فیلد بولی جدید برای نشان دادن اینکه یک محصول فقط در فروشگاه های محلی فروخته می شود و برای خرید آنلاین در دسترس نیست.
در دسترس نیست	DataSource.legacyLocal	یک فیلد بولی جدید برای نشان دادن اینکه یک منبع داده حاوی محصولاتی است که فقط در فروشگاه‌های محلی فروخته می‌شوند.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	فیلد gtin به gtins تغییر نام داده است و اکنون آرایه ای از رشته ها (به جای یک رشته) است.
CreateAndConfigureAccountRequest.users	حذف شد	فیلد users حذف شده است. از فیلد user برای اضافه کردن مدیر اولیه به حساب کاربری استفاده کنید.