Elige entre los feeds de archivos y la API de Merchant

Puedes subir datos de productos a Merchant Center con feeds basados en archivos, la API de Merchant o una combinación de ambos:

  • Feeds de productos basados en archivos: Sube archivos CSV, TSV o XML con SFTP, Google Cloud Storage, Hojas de cálculo de Google o actualizaciones de datos programadas.
  • API de Merchant: Envía solicitudes programáticas directamente desde tu backend para realizar actualizaciones incrementales a medida que cambian los datos de productos, junto con sincronizaciones periódicas del catálogo completo.

En esta guía, se comparan ambos enfoques, se explica cuándo usar uno en lugar del otro (o ambos juntos) y se proporciona un instructivo de migración paso a paso si decides mover algunos o todos tus productos de los feeds de archivos a la API.

Elige tu enfoque de fuente de datos

Evalúa la volatilidad de tu catálogo, la arquitectura de backend y los flujos de trabajo operativos para decidir si usar la API de Merchant, los feeds de archivos o una configuración híbrida.

Cuándo usar la API de Merchant

Usa una fuente de datos principal de la API en los siguientes casos:

  • Integración programática directa: Prefieres llamar a una API directamente desde tu backend en lugar de generar archivos y administrar canalizaciones de transferencia de archivos (como SFTP o Google Cloud Storage).
  • Alta volatilidad de precios y de inventario: Los precios de tus productos o los niveles de stock cambian con frecuencia durante el día.
  • Actualizaciones inmediatas cuando cambian los datos: Quieres enviar los cambios de los productos a Google en cuanto se produzcan en tu backend, en lugar de esperar a que se genere y suba el siguiente archivo programado.
  • Actualizaciones incrementales del catálogo: Deseas insertar, actualizar o borrar productos individuales a medida que cambian, sin volver a subir todo el catálogo cada vez.
  • Actualizaciones parciales de atributos: Deseas actualizar campos específicos de un producto (como price o availability con productInputs.patch) sin volver a enviar la carga útil completa del producto.

Cuándo usar feeds de archivos

Usa una fuente de datos principal basada en archivos en los siguientes casos:

  • Catálogo estático: Los datos de tus productos cambian con poca frecuencia (por ejemplo, una vez al día o menos).
  • Backend solo de instantáneas sin seguimiento delta: Tu backend solo exporta instantáneas completas del catálogo y no puede hacer un seguimiento de los cambios a nivel de los artículos ni de las eliminaciones explícitas de productos.
  • Flujos de trabajo basados en hojas de cálculo: Los equipos que no son de ingeniería seleccionan o anulan los datos de productos directamente en Hojas de cálculo de Google o archivos CSV.
  • Operaciones de bajo mantenimiento: Prefieres una exportación de archivos programada en la que Merchant Center se encargue de la recuperación y el procesamiento de instantáneas, en lugar de operar una integración de API con ritmo de solicitudes, manejo de reintentos y sincronizaciones periódicas del catálogo completo.

Cuándo usar ambos recursos

Puedes combinar feeds de archivos y la API de Merchant en la misma cuenta de Merchant Center en las siguientes situaciones:

  • Catálogos de productos particionados: Usas la API de Merchant para los productos que cambian con rapidez (como las ofertas relámpago o el inventario de alta rotación) y los feeds de archivos para los segmentos estáticos del catálogo o las líneas de productos independientes. Asegúrate de que cada producto se suba solo con una fuente de datos principal (consulta Uso paralelo y propiedad de la fuente de datos principal).
  • Datos principales de la API con feeds complementarios basados en archivos: Administras los datos de productos principales a través de una fuente de datos principal de la API, mientras que los equipos que no son de ingeniería o los socios externos proporcionan atributos adicionales a través de feeds complementarios basados en archivos (como archivos CSV o de Hojas de cálculo de Google) unidos con reglas de atributos, o viceversa.
  • Migración parcial o por fases: Transfieres mercados, categorías o cuentas secundarias específicos a la API, mientras mantienes el resto de tu catálogo en feeds de archivos.

Si decides transferir algunos o todos tus productos de los feeds de archivos a la API de Merchant, sigue la guía de migración paso a paso.

Diferencias arquitectónicas clave

Los feeds de archivos y la API de Merchant basada en envíos difieren en la forma en que Google procesa y administra los datos de productos:

Concepto Feeds de archivos API de Merchant
Modelo de integración Volcado de archivos sin conexión: Exportas tu catálogo a un archivo y lo transfieres con SFTP, Google Cloud Storage, Hojas de cálculo de Google o actualizaciones de datos programadas. Integración programática directa: Tu backend envía solicitudes directamente al extremo de la API.
Nivel de detalle de la mutación Procesamiento masivo: Por lo general, para modificar un elemento, se debe volver a procesar todo el archivo. Transacciones detalladas: Puedes insertar, aplicar parches o borrar solo los productos que cambiaron.
Sincronización de tiempos Sincronización por lotes: Los cambios esperan en tu backend hasta el próximo ciclo programado de exportación y transferencia de archivos. Llamadas inmediatas o programadas: Puedes enviar cambios incrementales de inmediato a medida que se producen, junto con sincronizaciones completas periódicas.
Comportamiento de eliminación Implícita (instantánea): Cada archivo es una instantánea completa. Si quitas una fila de tu archivo principal, se borrará el producto. Explícito: No existe el concepto de instantánea. Llama a productInputs.delete para quitar un producto descontinuado.
Representación de recursos Estado único: Las filas de tu archivo representan la entrada sin procesar. Separa los datos sin procesar de los procesados: La API divide los datos en ProductInput (tu entrada sin procesar) y Product (el estado final procesado).
Reglas de atributos (feed) Se aplica a las columnas de archivos sin procesar en la IU de Merchant Center. Se admite en la IU de Merchant Center. Es obligatorio cuando se combinan datos de la API con archivos complementarios de terceros; es opcional para las transformaciones de una sola fuente si se controlan en tu backend.

Uso paralelo y propiedad de la fuente de datos principal ("gana la última actualización")

Si bien puedes usar tanto los feeds de archivos como la API en la misma cuenta de Merchant Center, te recomendamos que uses solo un método para insertar un producto determinado.

Merchant Center funciona con un modelo de "la última actualización gana". La fuente de datos principal (API o feed de archivos) que envió la inserción de productos más reciente obtiene la propiedad principal de los datos de ese producto:

  • Cuando la fuente de datos del archivo es propietaria del producto: Si omites el producto en una carga de archivo posterior, se activará la eliminación implícita, lo que quitará el producto de Merchant Center.
  • Cuando la fuente de datos de la API es propietaria del producto: Omitir el producto de una carga de archivo no tiene ningún efecto porque el feed de archivos ya no es propietario del producto. Debes llamar a accounts.productInputs.delete para quitarlo.
  • Riesgo de reasignación accidental de la propiedad: Si un feed de archivos actualizado se ejecuta después de un envío de API y contiene el producto, la fuente de datos del archivo recupera la propiedad. Las omisiones posteriores del archivo borrarán el producto de forma inesperada.

Para evitar eliminaciones inesperadas o la pérdida de actualizaciones de la API, no realices actualizaciones simultáneas en los mismos productos con las fuentes de datos principales de la API y de archivos.

Consideraciones clave sobre las APIs

Comprende estos comportamientos fundamentales de la API de Merchant antes de comenzar la implementación:

Fuentes de datos flexibles (sin idioma ni etiqueta)

A diferencia de los feeds de archivos, que requieren que definas una etiqueta de feed de segmentación y un idioma específicos por adelantado, la API de Merchant te permite crear fuentes de datos principales sin especificar un feedLabel ni un contentLanguage.

  • Cargas flexibles: Te permiten subir productos con cualquier combinación de idioma o etiqueta de feed a una sola fuente de datos.
  • Administración simplificada: No es necesario que crees y administres fuentes de datos independientes para cada mercado objetivo. Nota: Para obtener más detalles sobre cómo elegir una estrategia de fuente de datos, consulta Elige una estrategia de fuente de datos.

Estrategia de sincronización y cuotas

A diferencia de un feed de archivos en el que subes todo tu catálogo en un solo lote, diseña tu integración de la API de Merchant en torno a actualizaciones incrementales y sincronizaciones completas periódicas:

  • Combina las actualizaciones incrementales con sincronizaciones completas periódicas: Envía solicitudes productInputs.insert o productInputs.patch a medida que cambien los atributos de los productos en tu backend. Debido a que depender únicamente de las actualizaciones incrementales puede hacer que tus datos se desincronicen con el tiempo, también debes ejecutar sincronizaciones completas periódicas para conciliar tu catálogo con tu fuente de información (lo que también actualiza el vencimiento de 30 días del producto). La frecuencia con la que ejecutas una sincronización completa depende del tamaño de tu catálogo y de la cuota de API disponible.
  • Controla el ritmo de las solicitudes para respetar las cuotas de la API: No llames a la API para todos tus productos a la vez. Si bien los cambios incrementales se pueden enviar a medida que ocurren, distribuye las solicitudes de sincronización completa de manera uniforme a lo largo del día para mantenerte dentro de tus cuotas de llamadas de método diarias y por minuto. Para obtener más detalles, consulta Cuotas y límites y Realiza actualizaciones frecuentes de tus productos.

Prueba tu integración

Valida tu lógica de integración en un entorno seguro antes de pasar a producción.

Usa cuentas de prueba.

Antes de realizar cambios en la producción, te recomendamos que ejecutes los pasos iniciales de la migración en una cuenta de prueba de zona de pruebas:

  1. Crea una cuenta de prueba: Configura una cuenta de prueba aislada para experimentar de forma segura sin afectar los anuncios o las fichas gratuitas publicados.
  2. Crea una fuente de datos de la API: Practica cómo crear tu fuente de datos principal de la API.
  3. Prueba las reglas de atributos: Verifica las transformaciones de datos y las uniones de feeds complementarios.
  4. Valida las cargas útiles y las claves de producto: Envía productos de muestra para verificar el uso de mayúsculas y minúsculas, la codificación y el manejo de errores de los SKU.

Para obtener más detalles, consulta el Paso 1: Crea cuentas de prueba y la guía de cuentas de prueba.

Validar la alineación de la clave de producto

Asegúrate de que la clave de producto de la carga útil programática coincida exactamente con los SKUs de tu feed de archivos. Google identifica los productos combinando los siguientes elementos:

  • offerId (se llama id en los feeds de archivos, distingue mayúsculas de minúsculas)
  • contentLanguage (por ejemplo, en)
  • feedLabel (por ejemplo, US)

Caracteres especiales y codificación

Si tus identificadores de productos contienen caracteres como /, % o ~, usa el formato codificado (codificación base64url sin relleno) en tus llamadas a la API. Para obtener más información, consulta ProductInput.name

Control de simultaneidad

En una integración en tiempo real, las actualizaciones pueden llegar desordenadas debido a la latencia de la red. Para evitar que las actualizaciones más antiguas reemplacen los datos más recientes, usa el campo versionNumber en el recurso ProductInput.

Guía de migración paso a paso

Si decides mover algunos o todos tus productos de los feeds de archivos a la API de Merchant, sigue esta guía para realizar la transición de tus productos sin perder impresiones ni el historial de publicación.

1. Ensaya la migración en una cuenta de prueba

Antes de realizar cambios en la producción, crea una cuenta de prueba de zona de pruebas con el método accounts.createTestAccount (consulta la guía Cuentas de prueba). Las cuentas de prueba proporcionan un entorno aislado en el que las ofertas se aprueban de forma predeterminada, no se requiere la verificación del dominio y los datos nunca se publican.

Usa tu cuenta de prueba para replicar tu configuración de producción y ensayar la migración de extremo a extremo:

  1. Refleja la configuración de tu feed de archivos: Crea una fuente de datos principal de archivos (y cualquier fuente de datos complementaria) en la cuenta de prueba y sube una muestra de tu archivo de feed de producción.
  2. Crea una fuente de datos y reglas de la API de prueba: Crea una fuente de datos principal de la API y configura las reglas de atributos o las uniones de feeds complementarios que sean necesarias.
  3. Prueba la toma de posesión y la alineación de claves: Envía solicitudes productInputs.insert para los productos de ejemplo y verifica que la fuente de datos de la API tome posesión de los artículos existentes sin crear productos duplicados.
  4. Verifica las actualizaciones y las eliminaciones: Prueba las actualizaciones parciales con productInputs.patch y las eliminaciones con productInputs.delete, y, luego, inspecciona los recursos resultantes con products.get.

2. Crea fuentes de datos de la API de producción

Antes de enviar datos, crea una fuente de datos principal de tipo API en tu cuenta.

Crea tu fuente de datos principal de la API

Para crear una fuente de datos que acepte envíos de la API, envía una solicitud POST al extremo dataSources. Para obtener más detalles, consulta Cómo crear una fuente de datos de productos principal.

3. Transición de las reglas de atributos personalizados

Las reglas de atributos personalizadas se vinculan a fuentes de datos específicas y no se transfieren automáticamente de tu fuente de datos de archivo a tu nueva fuente de datos de la API.

La forma en que realices la transición de tus reglas de atributos dependerá de su propósito:

  • Combinación de varias fuentes y feeds complementarios de terceros: Si combinas datos principales de la API con fuentes de datos complementarias externas (como archivos de proveedores externos, hojas de cálculo de inventario o feeds de promociones), debes volver a crear las reglas de atributos en la IU de Merchant Center y adjuntarlas a la nueva fuente de datos de la API. El procesamiento previo del cliente no puede reemplazar las reglas que unen datos de varias fuentes independientes.
  • Transformaciones de datos de una sola fuente: Para la limpieza de una sola fuente, los valores predeterminados o el formato de cadena en los datos de tu catálogo principal, elige entre las siguientes opciones:
    • Transformaciones de backend (recomendado): Aplica transformaciones en tu propio sistema antes de llamar a la API. Esto te brinda un mayor control programático, pruebas más sencillas y una depuración simplificada.
    • Reglas de atributos de Merchant Center: Vuelve a crear las reglas de transformación para tu nueva fuente de datos de la API en la IU de Merchant Center si quieres que Merchant Center siga administrándolas automáticamente.

4. Habilita la integración de la API

Activa la integración de la API de producción para comenzar a insertar, actualizar y borrar productos en tu nueva fuente de datos principal de la API:

  • Inserta y actualiza productos (adquisición de propiedad): Envía solicitudes productInputs.insert y productInputs.patch desde tu integración. Cuando insertas un producto con la API con la misma clave (offerId, contentLanguage, feedLabel) que un producto de feed de archivos existente, la fuente de datos de la API se apropia de ese producto y conserva su historial de publicación. Para obtener más orientación, consulta Inserta un producto y Agrega y administra productos.

  • Borra los productos descontinuados: Configura tu integración para llamar de forma explícita a productInputs.delete cada vez que se quite un producto de tu catálogo.

  • Implementa de forma gradual: En el caso de los catálogos grandes, habilita la integración de una cuenta secundaria de Merchant Center o una fuente de datos a la vez.

  • Configura la simultaneidad: Si envías muchas solicitudes, configura tu cliente para que controle las solicitudes simultáneas y administre varias conexiones. Consulta la guía Refactoriza el código para solicitudes simultáneas.

5. Cómo pausar las actualizaciones de la fuente de datos de archivo

Una vez que se active la integración de la API, detén las actualizaciones de archivos antes de la próxima ejecución programada para que la fuente de datos del archivo no reemplace las actualizaciones de la API:

  1. Deja de subir archivos nuevos a tu ubicación de SFTP/FTP, Google Cloud Storage o Hojas de cálculo de Google.
  2. En la IU de Merchant Center, navega a la fuente de datos de tu archivo y pausa su actualización de datos programada.
  3. Los productos existentes que pertenecen a la fuente de datos de archivos permanecen activos durante un máximo de 30 días hasta que tu integración de la API los inserte.

6. Espera a que se complete la migración y verifícala

Espera hasta que todos los productos activos se migren de la fuente de datos de archivo a la fuente de datos de la API. Si bien las actualizaciones incrementales migran los productos a medida que cambian, ejecutar una sincronización completa del catálogo a través de tu integración habitual acelera la migración de todo el catálogo (consulta Estrategia de sincronización y cuotas).

Durante esta fase, ocurre lo siguiente:

  1. En la IU de Merchant Center, supervisa los recuentos de artículos. Espera hasta que el recuento de fuentes de datos de archivos disminuya a 0 y el recuento de fuentes de datos de la API coincida con tu catálogo activo.
  2. Usa products.get para verificar que los atributos y las reglas de atributos personalizados se combinen según lo esperado.
  3. Supervisa la herramienta de diagnóstico de la API en la IU de Merchant Center para hacer un seguimiento de las tasas de error y el rendimiento de la API.

7. Cómo retirar la fuente de datos de archivo

Una vez que se complete la transición y el recuento de elementos del feed de archivos sea 0, haz lo siguiente:

  1. Confirma que las actualizaciones se reflejen en tiempo real.
  2. Borra la fuente de datos de archivos heredada en la IU de Merchant Center para evitar que las actualizaciones accidentales basadas en archivos reemplacen tus datos de la API.
Anterior
Migrate Local Inventory Ads settings