Migra de v1beta a v1

Esta guía te ayuda a migrar de la API de Merchant v1beta a v1, la primera versión para la disponibilidad general. La versión 1 incluye varias actualizaciones y algunos cambios que podrían requerir actualizaciones de código. Estos cambios están diseñados para simplificar la API y mejorar la administración de tu cuenta de Merchant Center.

Diferencias clave

Estos son los cambios más importantes que debes tener en cuenta cuando migres de v1beta a v1:

• Registro único de al menos un desarrollador de la API para usar la API de Merchant: Deberás llamar al método registerGcp (solo una vez para cada proyecto de Google Cloud que se use para la autenticación) para proporcionar tus detalles de contacto, lo que te permitirá usar la API y recibir actualizaciones y anuncios relacionados con la API de Merchant. No podrás usar ninguna API de v1 o v1alpha hasta que se complete este paso. Para obtener instrucciones, consulta Regístrate como desarrollador
• Se cambió el nombre de Product.attributes: Se cambió el nombre del campo Product.attributes por Product.productAttributes.
• Eliminación de la información fiscal a nivel del producto: Se quitaron los campos taxes y taxCategory del objeto Product.productAttributes. Consulta el artículo de ayuda de Google Merchant Center sobre impuestos para obtener más información.
• Cambios en el campo GTIN: Se cambió el nombre del campo gtin en el objeto Product.productAttributes a gtins para reflejar mejor que puede contener varios valores. El campo gtin en el objeto OrderTrackingSignals.lineItemDetails ahora es un array y también se cambió su nombre a gtins.
• Eliminación del campo Channel: Se quitó el campo channel de los productos, las entradas de productos y las fuentes de datos. Se introdujo un nuevo campo booleano, legacyLocal, para designar claramente los productos que se venden exclusivamente en tiendas físicas. Nota: El campo legacyLocal es un campo auxiliar para ayudar con la migración y, finalmente, quedará obsoleto cuando los métodos de marketing en línea y local se puedan segmentar por completo con una sola fuente de productos. Consulta la tabla de la siguiente sección para obtener más información.
• Nuevos campos para los atributos de inventario regional y local:
  • Todos los campos RegionalInventory, excepto name, account y region, ahora se incluyen en un objeto nuevo llamado regionalInventoryAttributes. Por ejemplo, el atributo RegionalInventory.price ahora se encuentra en RegionalInventory.regionalInventoryAttributes.price.
  • Todos los campos LocalInventory, excepto name, account y storeCode, ahora se incluyen en un objeto nuevo llamado localInventoryAttributes. Por ejemplo, el atributo LocalInventory.price ahora se encuentra en LocalInventory.localInventoryAttributes.price.
• Se quitó customAttributes de los inventarios regionales y locales: Se quitó el campo customAttributes de los recursos RegionalInventory y LocalInventory.
• Creación de cuentas perfeccionada: Se quitó el campo redundante users de CreateAndConfigureAccountRequest. Usa el campo singular user para asociar un usuario inicial con una cuenta nueva.
• Se cambiaron ciertos tipos de atributos de cadenas a enumeraciones: Algunos campos dentro de los recursos Product y Inventory con una lista corta de valores definida se cambiaron del tipo string al tipo enum para una mejor validación de datos (por ejemplo, el campo Product.ProductAttributes.condition ahora es un enum).
• Se quitó el método de actualización de la política de devoluciones en línea: El método onlineReturnPolicy.update se quitó en v1. En su lugar, crea una política de devoluciones en línea con el método onlineReturnPolicy.create.

Cómo realizar la migración

Está previsto que la versión v1beta de la API de Merchant deje de estar disponible el 28 de febrero de 2026. Para obtener más información sobre el cronograma de baja, consulta la guía de control de versiones de la API de Merchant.

• El primer paso para migrar es registrarte como desarrollador por única vez (consulta Cómo registrarte como desarrollador). Debes llamar al método registerGcp para cada proyecto de Google Cloud que uses para la autenticación antes de que funcione cualquier método v1.

• Independientemente de cómo llames a las APIs (con REST, gRPC o con bibliotecas cliente), puedes migrar en etapas. Esto significa que puedes actualizar y migrar tu código una API a la vez (por ejemplo, mover la API de Products a v1 y mantener la API de Accounts en v1beta) sin tener que actualizar toda tu integración de una vez.

Cambios detallados en los campos

En esta tabla, se proporciona una comparación detallada de los campos que cambiaron entre las versiones v1beta y v1.

v1beta	v1	Descripción
Product.gtin	Product.gtins	Se cambió el nombre del campo para los GTIN.
Product.taxes	Quitada	Se quitó el campo taxes
Product.taxCategory	Quitada	Se quitó el campo taxCategory
Product.channel	Quitada	Se quitó el campo channel. Usa el campo legacyLocal para los casos de uso locales.
Product.attributes	Product.productAttributes	Se cambió el nombre del campo attributes a productAttributes.
availability, condition, gender, includedDestinations y excludedDestinations en los campos Product se representan como strings (o array de strings)	Estos campos ahora son enums (o array de enums).	Los campos con una lista corta de valores definida se cambiaron del tipo string a enum.
price, salePrice, salePriceEffectiveDate y availability en RegionalInventory	Se movió a RegionalInventory.regionalInventoryAttributes	Estos campos se trasladaron a regionalInventoryAttributes.
El campo RegionalInventory.availability es un string	RegionalInventory.regionalInventoryAttributes.availability ahora es un enums	El tipo de disponibilidad cambió de string a enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla y instoreProductLocation en LocalInventory	Se movió a LocalInventory.localInventoryAttributes	Estos campos se trasladaron a localInventoryAttributes.
El campo LocalInventory.availability es un string	LocalInventory.localInventoryAttributes.availability ahora es un enums	El tipo de disponibilidad cambió de string a enum.
LocalInventory.customAttributes	Quitada	Los atributos personalizados ya no son compatibles con el inventario local.
RegionalInventory.customAttributes	Quitada	Ya no se admiten los atributos personalizados para el inventario regional.
ProductInput.channel	Quitada	Se quitó el campo channel. Usa el campo legacyLocal para los casos de uso locales.
DataSource.channel	Quitada	Se quitó el campo channel. Usa el campo legacyLocal para los casos de uso locales.
No disponible	ProductInput.legacyLocal	Es un nuevo campo booleano que indica que un producto solo puede segmentarse para métodos de marketing locales. El ID del recurso del producto tendrá el prefijo "local~".
No disponible	Product.legacyLocal	Es un nuevo campo booleano para indicar que un producto solo se vende en tiendas locales y no está disponible para la compra en línea.
No disponible	DataSource.legacyLocal	Es un nuevo campo booleano que indica que una fuente de datos contiene productos que se venden solo en tiendas locales.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	Se cambió el nombre del campo gtin a gtins, y ahora es un array de cadenas (en lugar de una cadena).
CreateAndConfigureAccountRequest.users	Quitada	Se quitó el campo users. Usa el campo user para agregar el administrador inicial a la cuenta.