Integración Google Merchant XML & API: configuración y ayuda

Sube e instala mprgooglemerchant desde la pantalla de carga de módulos del Back Office. Haz clic en "Configure" para abrir Google Merchant > Feeds. Usa un subconjunto del catálogo para tu primer feed.

Elige XML si quieres la URL de un archivo generado. Elige Products API si quieres que el módulo envíe entradas de producto. Ambos métodos usan el idioma, la moneda, la selección de productos y los ajustes de variantes del feed. Un feed API necesita una cuenta Merchant y una activación LIVE independiente.

Abre Google Merchant > Ajustes > Configuración.

Configuración

• TTL de caché predeterminado. TTL de caché inicial de los nuevos feeds, inicialmente 3600 segundos. Los nuevos feeds usan la preferencia guardada; los existentes conservan su propio TTL de caché.
• Directorio de feeds. Muestra la ruta del sistema de archivos donde se escriben los XML generados y si el directorio permite escritura; valor predeterminado: _PS_MODULE_DIR_ . 'mprgooglemerchant/feeds/'.

Concede al proceso PHP acceso de escritura al directorio de feeds. Protege los XML generados, los comprobantes y los archivos temporales. El archivo Apache .htaccess incluido deniega el acceso directo a este directorio. Si tu servidor no procesa .htaccess, configura una regla equivalente. Usa la URL del controlador de feed autenticado para recuperar el XML.

"Access & Feed URLs"

• Token de acceso. Autoriza los controladores frontales de feeds y cron; valor predeterminado: generated 32-character token.

• Regenerar token. Crea un nuevo token de acceso e invalida las URL existentes de feeds y cron; valor predeterminado: manual action.

• URL de cron. Muestra el endpoint cron protegido por token que debes ejecutar desde tu programador; valor predeterminado: https://your-shop.example/module/mprgooglemerchant/cron?token=TOKEN.

• Patrón de URL del feed. Muestra el patrón del endpoint de feed protegido por token para enviarlo a Merchant Center; valor predeterminado: https://your-shop.example/module/mprgooglemerchant/feed?id={ID}&token=TOKEN.

• "Canonical Merchant Base URL". Valor predeterminado: vacío. Introduce la URL base de tu tienda en producción, incluido cualquier subdirectorio de la tienda. Las URL de productos e imágenes usan esta base.

• Modo API Merchant. Valor predeterminado: test. TEST realiza vistas previas locales y mantiene disponibles las exportaciones XML. LIVE permite escrituras en Google solo cuando se superan las demás comprobaciones de identidad.

• Activación LIVE. Guarda primero la URL canónica. Un superadministrador debe hacer clic en Activar LIVE para esta tienda en el contexto de tienda previsto. La activación vincula esa tienda y esa instalación a la identidad guardada. No se sustituye una vinculación existente que no coincida.

• Estado efectivo de escritura en Google. Lee este estado antes de una ejecución API real. Tras la activación, el selector de modo permite pausar y reanudar las escrituras en la misma instalación.

La preferencia interna sync_lock_ttl_seconds tiene el valor predeterminado 600. No es un campo normal de esta pantalla. Una segunda ejecución para un feed ya bloqueado devuelve un estado de bloqueo en lugar de iniciar trabajo duplicado.

Abre Google Merchant > Cuentas de comerciante y añade una cuenta.

• Nombre de cuenta. Etiqueta interna para una cuenta Merchant Center; valor predeterminado: "".
• ID de Merchant Center. ID de tu cuenta Google Merchant Center; valor predeterminado: "".
• Ruta del JSON de cuenta de servicio. Introduce la ruta del archivo JSON de la cuenta de servicio. Valor predeterminado: vacío. Guarda el archivo fuera de la raíz web pública y permite que el proceso PHP lo lea.
• Activo. Habilita la cuenta Merchant para usarla en feeds API; valor predeterminado: 1.

Las solicitudes API necesitan PHP cURL y OpenSSL, un archivo JSON de cuenta de servicio legible y acceso a la cuenta Merchant Center. El cliente lee campos de la cuenta de servicio, incluidos client_email, private_key y token_uri. Usa tu archivo de credenciales real. No pegues una clave privada en plantillas o en una carpeta pública.

Abre Google Merchant > Feeds y añade o edita un feed.

• Nombre del feed. Nombre interno mostrado en la lista de feeds; valor predeterminado: "".
• Cuenta de comerciante. Asigna el feed a una cuenta Merchant para la sincronización API, las comprobaciones de solapamiento y la deduplicación; valor predeterminado: 0.
• Modo de sincronización. Elige la salida en archivo XML o la sincronización Merchant Products API; valor predeterminado: file_only.
• Países objetivo. Establece uno o varios códigos de país de destino Merchant de dos letras, como FR o AE,AU,GB,US; valor predeterminado: FR.
• Etiqueta del feed. Establece la etiqueta del feed Merchant con letras mayúsculas, números o guiones; valor predeterminado: FR.
• Idioma del contenido. Establece el idioma del contenido Merchant con dos letras; valor predeterminado: fr.
• Nombre de fuente de datos Merchant API. Guarda el nombre de recurso de la fuente de datos Merchant API tras configurar la API; valor predeterminado: "".
• Prioridad. Establece la prioridad del feed para la deduplicación; los números más altos reservan primero los productos; valor predeterminado: 0.
• Idioma. Elige el idioma de PrestaShop usado para nombres de productos, descripciones, características y atributos; valor predeterminado: current Back Office language.
• Moneda. Elige la moneda del feed o usa la predeterminada de la tienda; valor predeterminado: 0.
• Nombre del archivo. Establece el nombre del archivo XML generado sin .xml; valor predeterminado: "".
• Activo. Habilita el feed para la generación y el procesamiento cron/API; valor predeterminado: 1.
• Incluir variantes. Exporta las combinaciones de productos como artículos separados; valor predeterminado: 0.
• Deduplicar automáticamente. Excluye los productos ya presentes en feeds activos de mayor prioridad de la misma cuenta Merchant; valor predeterminado: 0.
• Caché TTL. Establece cuánto tiempo sigue siendo válido el archivo XML generado de este feed; los nuevos feeds empiezan con el TTL de caché predeterminado guardado (inicialmente 3600 segundos).
• Selección de producto. Define qué productos se incluyen en el feed; valor predeterminado: all active products with visibility both or catalog.
• Filtros de atributos. Excluye los grupos de atributos desmarcados de la resolución de etiquetas {attribute:...}; valor predeterminado: all attribute groups included.
• Encabezado XML. Controla el contenido XML escrito antes de los artículos de producto; valor predeterminado: standard RSS header.
• Plantilla de elemento XML. Controla el XML generado para cada producto o combinación; valor predeterminado: standard Google Merchant item template.
• Pie de página XML. Controla el contenido XML escrito después de los artículos de producto; valor predeterminado: standard RSS footer.

Cambia los valores iniciales FR de país/etiqueta y fr de idioma por los de tu destino real. Idioma es el idioma de PrestaShop usado para los textos del catálogo; Idioma del contenido es el código de idioma del contenido Merchant. Moneda = 0 usa el valor predeterminado de la tienda.

Usa un Nombre del archivo único sin .xml. Una Selección de producto vacía recurre a los productos activos con visibilidad both o catalog. Usa las condiciones de inclusión/exclusión del selector para acotar el feed. Los Filtros de atributos afectan a la resolución de etiquetas de atributos; por sí solos no determinan qué combinaciones se incluyen.

Los valores numéricos más altos de Prioridad reservan primero los productos cuando Deduplicar automáticamente está activado en los feeds de la misma cuenta Merchant. Revisa los solapamientos antes de habilitar varios feeds para una cuenta.

El formulario también incluye "Acknowledge XML removals". Lee el mensaje de generación y revisa los productos retirados antes de confirmar un cambio de publicación protegido. No cambies las selecciones solo para eliminar una advertencia.

• Tamaño de lote API. Limita las operaciones de inserción/eliminación de Product API por lote; valor predeterminado: 25. Una ejecución de cron o sincronización manual puede procesar varios lotes dentro de sus límites de tiempo y número de lotes.
• Eliminar productos API ausentes. Elimina entradas de producto Merchant cuando los productos salen de este feed; valor predeterminado: 1.
• "Delete guard threshold (%)". Bloquea las eliminaciones API cuando una ejecución eliminaría más de este porcentaje de artículos conocidos y más de 10 artículos; valor predeterminado: 20.
• Excluir productos sin imágenes. Omite productos cuyo {image_link} resuelto está vacío; valor predeterminado: 1.
• "Export loyalty member prices". Añade entradas loyaltyPrograms de Merchant API cuando los precios de los grupos de clientes asignados son inferiores al precio normal; valor predeterminado: 0.
• "Loyalty program label". Etiqueta del programa de fidelización Merchant Center usada para los precios de miembros API; valor predeterminado: "".
• "Loyalty group tier map". Objeto JSON que asigna los ID de grupos de clientes PrestaShop a las etiquetas de niveles Merchant Center; valor predeterminado: "".
• Plantilla de título Merchant. Plantilla de título solo para API; valor predeterminado: "".
• Plantilla de descripción Merchant. Plantilla de descripción solo para API; valor predeterminado: "".
• Plantilla de tipo de producto Merchant. Plantilla de tipo de producto solo para API; valor predeterminado: "".
• Categoría de producto Google. Valor API predeterminado para googleProductCategory, sustituido por google_product_category a nivel de producto; valor predeterminado: "".
• Custom label 0. Valor API predeterminado para customLabel0, sustituido por custom_label_0 a nivel de producto; valor predeterminado: "".
• Custom label 1. Valor API predeterminado para customLabel1, sustituido por custom_label_1 a nivel de producto; valor predeterminado: "".
• Custom label 2. Valor API predeterminado para customLabel2, sustituido por custom_label_2 a nivel de producto; valor predeterminado: "".
• Custom label 3. Valor API predeterminado para customLabel3, sustituido por custom_label_3 a nivel de producto; valor predeterminado: "".
• Custom label 4. Valor API predeterminado para customLabel4, sustituido por custom_label_4 a nivel de producto; valor predeterminado: "".

Nombre de fuente de datos Merchant API guarda la vinculación del recurso. Usa "Rebind data source" solo si quieres cambiar esa vinculación y has revisado el efecto sobre los artículos ya enviados. Está desactivado por defecto.

"Delete guard threshold (%)" bloquea un lote de eliminaciones si se eliminarían más de 10 artículos conocidos y el porcentaje de eliminación supera el umbral. El valor predeterminado es 20; 0 desactiva esta protección porcentual. Las inserciones y actualizaciones pueden continuar mientras las eliminaciones siguen bloqueadas. Revisa los cambios de selección y el mensaje de estado antes de autorizar las eliminaciones pendientes.

Para los precios de miembros, activa "Export loyalty member prices", introduce "Loyalty program label" y asigna los ID de grupos de clientes a las etiquetas de niveles Merchant en "Loyalty group tier map", por ejemplo {"4":"trade","5":"vip"}. La indicación "Customer groups" situada al lado enumera los grupos de la tienda. Solo los precios de grupo inferiores que cumplen los requisitos generan entradas de fidelización.

Envío

Selecciona "Shipping carriers" solo si quieres entradas de envío físico. La selección predeterminada está vacía, lo que omite estas entradas. El módulo elige el transportista seleccionado disponible más barato para un artículo físico en cada país de destino. Selecciona transportistas activos con rangos nativos de precio o peso.

"Minimum handling days", "Maximum handling days", "Minimum transit days" y "Maximum transit days" aceptan números enteros de días opcionales. Vacío significa que no se envía el valor; cero significa el mismo día. Los hooks de precios e impuestos solo se usan cuando la tienda del feed es la de la solicitud actual. Los demás contextos de tienda usan las tablas nativas de precios, reducciones e impuestos.

Opciones guardadas de compatibilidad y ejecución

fetch_hour = 2 y fetch_timezone = Europe/Paris son campos heredados guardados, no controles de programación del formulario actual. Ejecuta el endpoint cron desde tu programador en su lugar.

El módulo también tiene preferencias internas para la disponibilidad de productos sin stock que se pueden pedir (in_stock por defecto, o backorder), plazo de reposición (21 días), etiquetado de texto generado (desactivado), marca predeterminada (vacía), renovación API (7 días), tiempo disponible para cron (105 segundos) y tipo de imagen (vacío para la original). No son campos adicionales de la pantalla de configuración. Los requisitos de procedencia de imágenes de la tienda pueden retener productos cuya imagen original no incluya los metadatos de origen requeridos. Revisa los diagnósticos si un producto con imagen sigue retenido.

Abre Google Merchant > Campos personalizados > Grupos para definir etiquetas. Crea un campo antes de usar su etiqueta en una plantilla de texto XML o API.

• Nombre de la etiqueta. Crea el nombre de etiqueta usado en las plantillas, normalizado a letras minúsculas, números y guiones bajos; valor predeterminado: "".
• Etiqueta de visualización. Establece la etiqueta del campo personalizado en el Back Office; valor predeterminado: "".
• Tipo de campo. Elige text, textarea, select o number; valor predeterminado: text.
• Valor predeterminado. Proporciona un valor cuando no existe uno específico del producto; valor predeterminado: "".
• Opciones. Guarda una opción por línea para los campos de selección; valor predeterminado: "".
• Activo. Hace que la etiqueta personalizada esté disponible para las plantillas y la asignación de valores; valor predeterminado: 1.

Los nombres de etiqueta se normalizan a letras minúsculas, números y guiones bajos. La posición se gestiona mediante el orden guardado, en vez de un campo Posición independiente en este formulario.

Abre Campos personalizados > Valores para asignar un valor a los productos seleccionados:

• Nombre del grupo. Etiqueta opcional del Back Office para una operación de asignación masiva; valor predeterminado: "".
• Campo personalizado. Selecciona qué etiqueta personalizada recibe un valor; valor predeterminado: "".
• Valor. Establece el valor asignado a los productos seleccionados; valor predeterminado: "".
• Productos objetivo. Selecciona los productos que reciben el valor personalizado; valor predeterminado: empty selection.

Por ejemplo, define merchant_title, merchant_description, merchant_product_type, google_product_category o custom_label_0 y asigna valores antes de hacer referencia a las etiquetas. Los valores predeterminados de los campos completan los valores específicos de producto que falten.

Conserva la cabecera y el pie iniciales para la primera prueba XML. Edita Plantilla de elemento XML con las etiquetas disponibles y después regenera e inspecciona el XML. La plantilla inicial de artículo incluye:

<item>
  <g:id>{id}</g:id>
  <g:title>{title}</g:title>
  <g:description>{description_short}</g:description>
  <g:link>{link}</g:link>
  <g:image_link>{image_link}</g:image_link>
  <g:additional_image_link>{additional_image_links}</g:additional_image_link>
  <g:price>{price} {currency}</g:price>
  <g:sale_price>{sale_price} {currency}</g:sale_price>
  <g:availability>{availability}</g:availability>
  <g:brand>{brand}</g:brand>
  <g:gtin>{ean13}</g:gtin>
  <g:mpn>{mpn}</g:mpn>
  <g:condition>{condition}</g:condition>
  <g:product_type>{categories}</g:product_type>
  <g:item_group_id>{item_group_id}</g:item_group_id>
</item>

Puedes usar campos personalizados y características o atributos con nombre, por ejemplo {merchant_title}, {attribute:size}, {attribute:color}, {feature:material}, {gtin} y {custom_label_0}. Los nombres de atributos y características deben coincidir con tu catálogo. Las longitudes o sumas de comprobación GTIN EAN/UPC no válidas generan un identificador vacío.

Las plantillas de texto API usan las mismas etiquetas del catálogo, por ejemplo:

Merchant title template: {name} {attribute:size} {feature:style_de_grille}
Merchant description template: {merchant_description}
Merchant product type template: Sanitaire > Receveurs de douche > {feature:serie}

Con Incluir variantes activado, los artículos de combinación usan ID como 125-842 y comparten {item_group_id}. Comprueba el precio, los identificadores, la imagen y el enlace de cada variante.

Copia los valores reales de URL de cron y Patrón de URL del feed desde la configuración. Sustituye {ID} por el ID del feed. Ejemplos:

wget -q -O - "https://your-shop.example/module/mprgooglemerchant/cron?token=YOUR_ACCESS_TOKEN"
wget -q -O - "https://your-shop.example/module/mprgooglemerchant/cron?token=YOUR_ACCESS_TOKEN&id=3&force=1"
wget -q -O - "https://your-shop.example/module/mprgooglemerchant/cron?token=YOUR_ACCESS_TOKEN&api_limit=25&api_max_batches=3&api_max_seconds=90"

https://your-shop.example/module/mprgooglemerchant/feed?id=3&token=YOUR_ACCESS_TOKEN
https://your-shop.example/module/mprgooglemerchant/feed?file=google-fr&token=YOUR_ACCESS_TOKEN
https://your-shop.example/module/mprgooglemerchant/feed?id=3&token=YOUR_ACCESS_TOKEN&generate=1

Ejecuta primero la acción del feed manualmente. Para XML, abre la URL autenticada e inspecciona el número de productos, idioma, moneda, imágenes e identificadores. El controlador envía XML y X-Robots-Tag: noindex, nofollow, noarchive. Envía la URL verificada a tu cuenta Merchant. Los hooks de actualización/eliminación de productos invalidan la caché; no regeneran el XML inmediatamente por sí mismos.

Para API, inspecciona el resultado TEST local, completa la activación LIVE y ejecuta una pequeña sincronización real. Comprueba Estado de API, el mensaje de la última sincronización y los diagnósticos de la cuenta Merchant. La aceptación por Google es independiente de que el envío se complete correctamente. El formulario ofrece los modos de archivo XML y API; los valores heredados api_fetch y both se normalizan a API en el formulario.

Abre Google Merchant > Ajustes > Integridad para comprobar tablas, hooks, directorio de salida, token, feeds, solapamientos y cuentas. Ante una respuesta 403, comprueba el token y sustituye las URL copiadas después de Regenerar token. Si falta un artículo, comprueba el estado activo, la visibilidad, la selección, la determinación de la URL de la imagen, la procedencia de la imagen y la deduplicación. Para ejecuciones bloqueadas, comprueba el trabajo activo antes de iniciar otro. Si las escrituras API están bloqueadas, lee Estado efectivo de escritura en Google y el mensaje del feed.

Haz una copia de seguridad de las definiciones de feeds, campos personalizados, registros de cuentas y archivos generados antes de desinstalar. Elimina las entradas del programador y deja de usar las URL de feeds enviadas. La desinstalación elimina tareas, menús, esquema y configuración del módulo. No realiza una eliminación general de productos Google. Elimina o sustituye por separado la fuente de datos Google si esa es tu intención. Mantén bajo tu control la limpieza del archivo de la cuenta de servicio.

Requiere PrestaShop 1.6.1 o posterior y PHP 7.1 o posterior.