Migra de Content API for Shopping a Merchant API

En esta guía, se explica el proceso de migración de Content API for Shopping a Merchant API para la administración de datos de la empresa.

Puedes usar esta guía para migrar tu implementación existente de Content API for Shopping a Merchant API. Para obtener más información sobre los detalles de la API de Merchant y sus APIs secundarias, consulta Diseño de la API de Merchant.

Comenzar

Para comenzar a usar la API de Merchant, cambia las URLs de tus solicitudes al siguiente formato:

https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}…

Para usar la API de Merchant, debes vincular tu cuenta de Merchant Center y tu proyecto de Google Cloud con el método de registro de desarrollador, de la siguiente manera:

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  developer_email:"example-email@example.com"
}

Para obtener más información, consulta la guía de inicio rápido y la referencia de la API de Merchant.

Mejoras en comparación con Content API for Shopping

La Merchant API te permite automatizar y optimizar los flujos de trabajo en Merchant Center, y ofrece capacidades mejoradas en comparación con Content API for Shopping.

Casos de uso clave:

  • Administración automatizada de cuentas
  • Administración de productos automatizada
  • Administración automatizada del inventario
  • Informes personalizados

Áreas clave de mejora:

¿Qué cambió?

  • La cantidad máxima de pageSize aumentó de 250 a 1,000 filas por llamada a la API.
  • Se corrigió una demora que existía para la inserción de productos, las promociones, las opiniones sobre productos y las opiniones sobre comercios después de la creación de DataSources.

Próximamente:

  • Se lanzó una definición actualizada para clickPotentialRank en la tabla productView de la sub-API de Reporting: * La clasificación de los productos según clickPotential se normaliza a valores entre 1 y 1,000.
    • Los productos con un clickPotentialRank bajo siguen teniendo el mayor potencial de clics entre los productos del comercio que cumplen con las condiciones de la búsqueda. Este es un cambio no interrumpido que podría lanzarse el 1 de julio de 2025.
  • El campo AccountIdAlias del recurso AccountRelationship permite administrar mejor las estructuras de cuentas complejas. Por ejemplo, los mercados usan un alias definido por el usuario en lugar del ID interno del comercio, como el ID de la cuenta.

Compatibilidad con gRPC

La API de Merchant admite gRPC y REST. Puedes usar gRPC para la API de Merchant y REST para la Content API for Shopping al mismo tiempo.

Las bibliotecas cliente de la API de Merchant requieren gRPC.

Para obtener más información, consulta la descripción general de gRPC.

Compatibilidad

En esta guía, se describen los cambios generales que se aplican a toda la API de Merchant.

La API de Merchant está diseñada para funcionar junto con las funciones existentes de Content API for Shopping.

Por ejemplo, puedes usar la API de Merchant Inventories junto con tu implementación existente de la API de Content v2.1 de Shopping products. Puedes usar Content API for Shopping para subir un producto local nuevo (que vendes en una tienda local) y, luego, usar el recurso LocalInventory de la API de Merchant Inventories para administrar la información en la tienda de ese producto.

Mejoras en Content API

La API de Merchant mejora la API de Content en las siguientes áreas:

Analicemos estos cambios con más detalle.

Control de versiones y APIs secundarias

La API de Merchant introduce los conceptos de control de versiones y APIs secundarias. Su diseño modular mejora la facilidad de uso, ya que te permite enfocarte en las sub-APIs que necesitas y facilita las migraciones futuras a versiones más recientes. El control de versiones se aplicará con tus URLs de solicitud. La estrategia es similar a la experiencia de la API de Google Ads.

Solicitudes más robustas

Las solicitudes de URL de la API de Merchant requieren más parámetros para llamar a la API de Merchant. Esto incluye el recurso, la versión, el nombre (identificadores) y el método (métodos no estándar). Para obtener más información, consulta los identificadores de cuenta y producto y los ejemplos.

Principios de la AIP para identificadores

Si bien Content API for Shopping usa IDs para identificar recursos (por ejemplo, merchantId, productId), Merchant API usa un identificador name para alinearse con la AIP (consulta los principios de mejora de la API).

El identificador {name} incluye el identificador del recurso y su elemento superior (o potencialmente varios elementos superiores), de modo que {name} sea igual a accounts/{account}/products/{product}.

Todas las llamadas de lectura y escritura devuelven el campo name como identificador del recurso.

{name} también incluye los identificadores de colección accounts/ y products/.

La API de Merchant usa {account} para hacer referencia a un ID de Merchant Center y {product} para hacer referencia a identificadores de productos.

Por ejemplo, implementa un método getName() para recuperar el name de un recurso y almacena el resultado como una variable en lugar de construir el name a partir de los IDs del comercio y del recurso por tu cuenta.

A continuación, se muestra un ejemplo de cómo usar el campo name en tus llamadas:

   POST https://merchantapi.googleapis.com/inventories/v1/{PARENT}/regionalInventories:insert

En la tabla, se muestra cómo cambia la solicitud products.get de Content API for Shopping:

Content API for Shopping API de Merchant
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/{name}

Para obtener más detalles, consulta Cambios en los identificadores.

Como otro ejemplo, recuperar un producto con el identificador en~US~1234 del ID de Merchant Center 4321 con la API de Merchant se vería de la siguiente manera:

    GET
    https://merchantapi.googleapis.com/products/v1/accounts/4321/products/online~en~US~1234

donde {name} es igual a accounts/4321/products/en~US~1234. Este nuevo campo de nombre se devuelve como el identificador de recursos para todas las llamadas de lectura y escritura en la API de Merchant.

En Content API for Shopping, los dos puntos (:) denotan un delimitador en el nombre del producto, mientras que, en Merchant API, la virgulilla (~) realiza esta función. El identificador de la API de Merchant no contiene la parte channel.

Por ejemplo, el ID del producto en Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

en la API de Merchant se convierte en lo siguiente:

contentLanguage~feedLabel~offerId.

Campos principales para recursos secundarios

En la API de Merchant, todos los recursos secundarios tienen el campo parent. Puedes usar el campo parent para especificar el {name} del recurso en el que se insertará el secundario, en lugar de pasar todo el recurso principal. También puedes usar el campo parent con list.

Por ejemplo, para enumerar los inventarios locales de un producto determinado, especifica el name del producto en el campo parent del método list. En este caso, el product proporcionado es el parent de los recursos LocalInventory que se muestran.

    GET
    https://merchantapi.googleapis.com/inventories/v1/{parent}/localInventories

Para recuperar todos los inventarios locales del producto en~US~1234' y la cuenta 4321, la solicitud se vería de la siguiente manera:

    GET
    https://merchantapi.googleapis.com/inventories/v1/accounts/4321/products/online~en~US~1234/localInventories</code>

El elemento superior es accounts/{account}/products/{product}. Ten en cuenta que, en este caso, el recurso localInventories tiene dos elementos superiores incluidos en el identificador de nombre (accounts/ y products/), ya que la cuenta es el elemento superior del recurso del producto.

Enums comunes

El uso de enumeraciones comunes proporciona más coherencia.

El campo Destination.DestinationEnum especifica las plataformas en las que se mostrarán tus recursos. DestinationEnum enumera todos los valores disponibles para la segmentación por destino y se unifica en todas las APIs secundarias, por ejemplo, para los atributos de promociones.

El campo ReportingContext.ReportingContextEnum representa el contexto al que se aplican los problemas de tu cuenta y tus productos. Este campo se usa en todos los métodos de informes (por ejemplo, para IssueSeverityPerReportingContext).

Compatibilidad con versiones anteriores

Cuando comiences a usar la API de Merchant, tu integración existente de Content API for Shopping seguirá funcionando sin interrupciones. Para obtener más información, consulta Compatibilidad.

Una vez que migres tus APIs secundarias a la API de Merchant, te recomendamos que solo uses la API de Merchant para tus APIs secundarias migradas.

Disponibilidad de llamadas de procedimiento remoto (gRPC)

gRPC es la nueva forma recomendada de realizar la integración con la API de Merchant.

Sus ventajas incluyen las siguientes:

El procesamiento por lotes personalizado se convierte en procesamiento por lotes integrado

El procesamiento por lotes funciona de manera más eficiente cuando usas llamadas asíncronas. Obtén más información sobre cómo usar llamadas paralelas para lograr el procesamiento por lotes en la API de Merchant y cómo refactorizar el código para solicitudes simultáneas.

Para acelerar la migración, te recomendamos que uses las bibliotecas cliente.

La API de Merchant no admite el método customBatch que se incluye en Content API for Shopping. En su lugar, consulta Cómo enviar varias solicitudes a la vez o ejecuta tus llamadas de forma asíncrona.

En el siguiente ejemplo de Java, se muestra cómo insertar una entrada de producto.

   import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1.Availability;
import com.google.shopping.merchant.products.v1.Condition;
import com.google.shopping.merchant.products.v1.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1.ProductAttributes;
import com.google.shopping.merchant.products.v1.ProductInput;
import com.google.shopping.merchant.products.v1.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1.Shipping;
import com.google.shopping.type.Price;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert a product input */
public class InsertProductInputAsyncSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static ProductInput createRandomProduct() {
    Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();

    Shipping shipping =
        Shipping.newBuilder().setPrice(price).setCountry("GB").setService("1st class post").build();

    Shipping shipping2 =
        Shipping.newBuilder().setPrice(price).setCountry("FR").setService("1st class post").build();

    ProductAttributes attributes =
        ProductAttributes.newBuilder()
            .setTitle("A Tale of Two Cities")
            .setDescription("A classic novel about the French Revolution")
            .setLink("https://exampleWebsite.com/tale-of-two-cities.html")
            .setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
            .setAvailability(Availability.IN_STOCK)
            .setCondition(Condition.NEW)
            .setGoogleProductCategory("Media > Books")
            .addGtins("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setProductAttributes(attributes)
        .build();
  }

  public static void asyncInsertProductInput(Config config, String dataSource) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to insert the product.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (ProductInputsServiceClient productInputsServiceClient =
        ProductInputsServiceClient.create(productInputsServiceSettings)) {

      // Creates five insert product input requests with random product IDs.
      List<InsertProductInputRequest> requests = new ArrayList<>(5);
      for (int i = 0; i < 5; i++) {
        InsertProductInputRequest request =
            InsertProductInputRequest.newBuilder()
                .setParent(parent)
                // You can only insert products into datasource types of Input "API", and of Type
                // "Primary" or "Supplemental."
                // This field takes the `name` field of the datasource.
                .setDataSource(dataSource)
                // If this product is already owned by another datasource, when re-inserting, the
                // new datasource will take ownership of the product.
                .setProductInput(createRandomProduct())
                .build();

        requests.add(request);
      }

      System.out.println("Sending insert product input requests");
      List<ApiFuture<ProductInput>> futures =
          requests.stream()
              .map(
                  request ->
                      productInputsServiceClient.insertProductInputCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<ProductInput>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<ProductInput>>() {
            @Override
            public void onSuccess(List<ProductInput> results) {
              System.out.println("Inserted products below");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // Identifies the data source that will own the product input.
    String dataSource = "accounts/" + config.getAccountId() + "/dataSources/{datasourceId}";

    asyncInsertProductInput(config, dataSource);
  }
}
InsertProductInputAsyncSample.java

Si usas customBatch en Content API y necesitas esta función para la API de Merchant, indícanos el motivo en tus comentarios.

Funciones exclusivas

Las funciones futuras solo aparecerán en la API de Merchant. (Habrá algunas excepciones, como las especificaciones del feed anual de 2025).

Las funciones exclusivas de la API de Merchant incluyen las siguientes:

  • API de Reviews Usa la función Opiniones para implementar y administrar las calificaciones de tus productos y tu tienda. Para obtener más información, consulta Revisión del vendedor y Revisión del producto.
  • Notificaciones: Regístrate para recibir notificaciones push sobre los cambios en los datos de productos de una cuenta.

Precio

Estos son los cambios que se realizaron en Price en el paquete Merchant Common:

Content API for Shopping API de Merchant
Campo de importe value:string amountMicros:int64
Campo de moneda currency:string currencyCode:string

El importe de Price ahora se registra en micros, en el que 1 millón de micros equivale a la unidad estándar de tu moneda.

En Content API for Shopping, Price era un número decimal en forma de cadena.

El nombre del campo de cantidad cambió de value a amountMicros

El nombre del campo de moneda cambió de currency a currencyCode. El formato sigue siendo ISO 4217.

Actualizaciones y anuncios más recientes

Para obtener actualizaciones más detalladas, consulta las notas de la versión específicas de cada sub-API. Para obtener actualizaciones agregadas más periódicas de la API de Merchant, consulta nuestras actualizaciones más recientes.

Para obtener detalles más específicos y aprender aún más sobre la API de Merchant, consulta nuestra descripción general del sitio para desarrolladores y la guía general de migración para obtener más detalles.

Consulta Diseño de la API de Merchant para obtener detalles sobre la API de Merchant y sus APIs secundarias.

Anterior
Quickstart
Siguiente
Migrate accountstatuses to Account Issues