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 v1 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 API para usar la API de Merchant: Deberás llamar al método registerGcp (solo una vez por cada proyecto de Google Cloud que se use para la autenticación) para proporcionar tus datos 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 v1 ni v1alpha hasta que se complete este paso. Para obtener más información sobre el proceso de registro, consulta Registro.

  • Codificación del nombre del producto: Los ProductInput.name y Product.name campos admiten la codificación base64url sin relleno (sección 5 del RFC 4648). Para ello, sigue estos lineamientos:

    • Antes de la codificación, la cadena debe respetar el formato contentLanguage~feedLabel~offerId.

    • La codificación es obligatoria si el nombre de tu producto contiene caracteres que usa la API de Merchant o caracteres reservados para URL, como los siguientes:

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

    • Si el nombre de tu producto cumple con el contentLanguage~feedLabel~offerId formato y no contiene ningún carácter que use la API de Merchant o caracteres reservados para URL, puedes usar el formato simple, sin codificación.

    • Para garantizar un análisis coherente y correcto, te recomendamos que uses la codificación base64url sin relleno para todos los nombres de productos.

  • Eliminación de la información fiscal a nivel del producto: Los campos taxes y taxCategory.

  • Cambio de nombre de Product.attributes: Se cambió el nombre del campo Product.attributes a Product.productAttributes.

  • Eliminación de la información fiscal a nivel del producto: Se quitaron los campos taxes y taxCategory del Product.productAttributes objeto. 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 OrderTrackingSignals.lineItemDetails objeto ahora es un array y también se le cambió el nombre a gtins.

  • Eliminación del campo de canal: 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, dejará de estar disponible una vez que los métodos de marketing en línea y locales 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 RegionalInventory campos, excepto name, account y region, ahora están incluidos en un objeto nuevo llamado regionalInventoryAttributes . Por ejemplo, el atributo RegionalInventory.price ahora se encuentra en RegionalInventory.regionalInventoryAttributes.price.
    • Todos los LocalInventory campos, excepto name, account y storeCode, ahora están incluidos en un objeto nuevo llamado localInventoryAttributes . Por ejemplo, el atributo LocalInventory.price ahora se encuentra en LocalInventory.localInventoryAttributes.price.

  • Eliminación de customAttributes de los inventarios regionales y locales: Se quitó el campo customAttributes de los recursos RegionalInventory y LocalInventory.

  • Creación de cuentas refinada: Se quitó el campo users redundante de CreateAndConfigureAccountRequest. Usa el campo user singular 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 mejorar la validación de datos (por ejemplo, el Product.ProductAttributes.condition ahora es un enum).

  • Eliminación del método de actualización de la política de devoluciones en línea: Se onlineReturnPolicy.update quitó el método 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 la migración es realizar un registro único de desarrollador (consulta Registrarse 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 mediante el uso de bibliotecas cliente), puedes realizar la migración por 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 la integración a la vez.

Cambios detallados en los campos

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

v1beta v1 Descripción
ProductInput.name ProductInput.name Unpadded base64url encoding Se admite y es obligatoria para los nombres de productos que contienen caracteres que usa la API de Merchant o caracteres reservados para URL.
Product.name Product.name Unpadded base64url encoding Se admite y es obligatoria para los nombres de productos que contienen caracteres que usa la API de Merchant o caracteres reservados para URL.
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 legacyLocal campo 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 al tipo enum.
price, salePrice, salePriceEffectiveDate y availability en RegionalInventory Se movieron a RegionalInventory.regionalInventoryAttributes. Estos campos se movieron a regionalInventoryAttributes.
El campo RegionalInventory.availability es una 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 movieron a LocalInventory.localInventoryAttributes. Estos campos se movieron a localInventoryAttributes.
El campo LocalInventory.availability es una string. LocalInventory.localInventoryAttributes.availability ahora es un enums. El tipo de disponibilidad cambió de string a enum.
LocalInventory.customAttributes Quitada Ya no se admiten los atributos personalizados para 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 legacyLocal campo para los casos de uso locales.
DataSource.channel Quitada Se quitó el campo channel. Usa el legacyLocal campo para los casos de uso locales.
No disponible ProductInput.legacyLocal Un nuevo campo booleano para indicar que un producto solo puede segmentar métodos de marketing locales El ID del recurso del producto tendrá el prefijo "local~".
No disponible Product.legacyLocal 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 Un nuevo campo booleano para indicar que una fuente de datos contiene productos vendidos 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 user campo para agregar el administrador inicial a la cuenta.

Anterior
Refactor code for concurrent requests
Siguiente
Overview