Product Channel Sync für Google Merchant Center einrichten

Richten Sie Product Channel Sync ein, wenn Workspace veröffentlichte Shop-Produkte an Google Merchant Center senden soll. Nach Abschluss gibt es ein aktives Product-Channel-Binding für Site, Vertriebskanal, Google Merchant Center und ein tenant-gebundenes OAuth-Credential. Ein Taskstream-Job kann dann die freigegebenen Produkte als Google ProductInputs übertragen.

Dies ist die Hauptanleitung für Google Merchant Center. Die Provider-Verbindung ist nur ein vorbereitender Credential-Schritt. Nutzen Sie Provider-Verbindungen einrichten, wenn Sie das OAuth-Credential anlegen oder prüfen müssen.

Product Channel Sync ist provider-neutral angelegt. Google Merchant Center ist der erste unterstützte Adapter; spätere Zielkanäle wie Amazon nutzen denselben Grundvertrag mit eigenem Provider-Adapter.

Arbeitsablauf

Arbeiten Sie die Einrichtung in dieser Reihenfolge ab:

1. Prüfen Sie Workspace-, Google- und Produktvoraussetzungen.
2. Legen Sie die Google-Provider-Verbindung an oder prüfen Sie das bestehende OAuth-Credential.
3. Öffnen Sie Handel > Stammdaten > Profile & Kanäle > Produktkanäle.
4. Legen Sie das Product-Channel-Binding für Site und Vertriebskanal an.
5. Prüfen Sie die Binding-Readiness.
6. Beheben Sie Blocker bei Binding, Credential oder Produktdaten.
7. Starten Sie den Product-Channel-Sync.
8. Prüfen Sie lokalen Sync-Lauf, lokale Item-States, Taskstream-Ergebnis und Google-Verarbeitung.

Die Einrichtung ist erst abgeschlossen, wenn die Binding-Readiness nicht blockiert, der Sync-Job erfolgreich startet und Google ProductInputs annimmt. Google prüft und genehmigt Produkte danach asynchron.

Voraussetzungen

Prüfen Sie diese Punkte, bevor Sie ein Binding anlegen:

Speichern Sie keine OAuth-Client-Dateien, Client Secrets, Access Tokens oder Refresh Tokens in Tickets, Skripten, Repository-Dateien oder Betriebsprotokollen.

Google und Credential vorbereiten

1. Öffnen Sie Google Merchant Center und notieren Sie die Merchant Center Account ID.
2. Aktivieren Sie die Merchant API im passenden Google-Cloud-Projekt.
3. Richten Sie den OAuth Consent Screen und einen OAuth-Client für diese Workspace-Umgebung ein.
4. Tragen Sie die Redirect URI aus System > Integrationen > Provider-Verbindungen im OAuth-Client ein.
5. Legen Sie in Workspace eine Provider-Verbindung für Google Merchant Center an.
6. Wählen Sie nur den von Workspace angezeigten Scope https://www.googleapis.com/auth/content.
7. Schließen Sie den Google-OAuth-Dialog im Browser ab.
8. Prüfen Sie in der Verbindungsliste Provider, Konto-ID, Credential-ID und Teststatus.
9. Registrieren Sie das Google-Cloud-Projekt des OAuth-Clients für die Merchant API, wenn Google API-Aufrufe mit einem nicht registrierten GCP-Projekt blockiert.

Nach dem Release auf Provider-Verbindungen müssen bestehende Google-Merchant- OAuths normalerweise nicht neu autorisiert werden. Prüfen Sie das Credential operativ. Verbinden Sie nur neu, wenn der Verbindungstest fehlschlägt, der Scope fehlt, Google den Zugriff widerrufen hat oder das Binding auf eine falsche Credential-ID zeigt.

Merchant API Developer Registration durchführen

Google verlangt zusätzlich zum OAuth-Consent eine einmalige Developer Registration. Dieser Schritt verknüpft das Google-Cloud-Projekt, aus dem der OAuth-Client stammt, mit einem Merchant-Center-Konto. Merchant API aktivieren, den Scope https://www.googleapis.com/auth/content hinzufügen oder einen neuen OAuth-Token erzeugen reicht nicht aus, wenn diese Registrierung fehlt.

Führen Sie die Registrierung mit demselben Google-Cloud-Projekt aus, das den OAuth-Client für Workspace bereitstellt. Der aufrufende Google-Nutzer muss im Merchant Center direkt als Admin berechtigt sein. Bei Advanced Accounts, Hauptkonten oder Unterkonten kann Google melden, dass die Registrierung nicht gegen das Ziel-Unterkonto erfolgen darf. Registrieren Sie dann gegen das von Google genannte Haupt- oder Advanced-Konto. Das Product-Channel-Binding in Workspace kann weiter auf das Merchant-Konto zeigen, in das Produkte gesendet werden, sofern der OAuth-Nutzer dort Zugriff hat.

Die Registrierung nutzt die Google-Methode accounts.developerRegistration.registerGcp. Der Ressourcenname hat dieses Format:

accounts/<merchant-account-id>/developerRegistration

Der Request enthält optional eine Entwicklerkontaktadresse:

{
  "developerEmail": "admin@example.com"
}

Ein erfolgreicher Aufruf liefert eine developerRegistration-Ressource mit der registrierten Google-Cloud-Projekt-ID. Warten Sie danach einige Minuten und testen Sie die Provider-Verbindung oder den kleinsten Product-Channel-Sync erneut. Der Google-Account-Blocker ist behoben, wenn Google nicht mehr wegen eines nicht registrierten GCP-Projekts oder mit GCP_NOT_REGISTERED blockiert und Workspace die Merchant DataSource erstellen oder auflösen kann.

Speichern Sie den Access Token für diesen einmaligen API-Aufruf nicht in Tickets, Skripten, Repository-Dateien oder Betriebsprotokollen.

Binding anlegen

Legen Sie ein Product-Channel-Binding für die Site und den Vertriebskanal an, dessen Produkte Sie an Google senden möchten.

Workspace speichert im Binding keine geheimen OAuth-Werte. Das Binding enthält nur Tenant-, Site-, Vertriebskanal-, Credential- und Provider-Referenzen. Die Site muss demselben Vertriebskanal zugeordnet sein wie das Binding. So kann ein Mandant mehrere Sites und mehrere Google-Merchant-Bindings betreiben, ohne Produktdaten aus einem Shop mit Produktlinks eines anderen Shops zu vermischen.

Google-Versandregeln synchronisieren

Aktivieren Sie googleShippingSyncEnabled, wenn Workspace die Versandkostenregeln im Google Merchant Center aus lokalen Commerce-Daten pflegen soll. Workspace nutzt dabei einen klar begrenzten Ownership-Vertrag: Vor dem Schreiben liest Workspace die bestehenden Google Shipping Settings, entfernt nur Shipping Services mit dem konfigurierten googleShippingServicePrefix und schreibt anschließend die zusammengeführte Ressource zurück. Manuell gepflegte oder fremd verwaltete Google-Services außerhalb dieses Prefix bleiben erhalten.

Der erste Sync-Schnitt nutzt aktive ShippingConditionSet und aktive ShippingConditionRate der Default-Preisliste des Commerce-Profils am gebundenen Vertriebskanal. Aktive ShippingRule-Datensätze am Commerce-Profil liefern zusätzliche Label-Aliase für die zugeordnete Versandart. Der Sync bildet folgende Tarifarten nach Google ab:

Workspace blockiert die Readiness, wenn ein aktiver Versandkonditionssatz nicht deterministisch nach Google übersetzt werden kann. Dazu gehören gemischte Tarifbasen innerhalb eines Konditionssatzes, package, pallet und formelbasierte Tarifzeilen mit unitAmount.

Google-Merchant-Shipping 6.0 nutzt ausschließlich diese Shipping Condition Sets und deren aktive Rate-Zeilen.

Produktbezogene Sonderkonditionen laufen über Google shippingLabel. Pflegen Sie dazu in der Variantenlogistik ein shippingTags-Tag, das dem Key eines aktiven Versandkonditionssatzes, dem bucketKey einer aktiven Shipping Rule oder dem Rule-Key entspricht, zum Beispiel bulky oder sperrgut. Workspace normalisiert den Wert zu einem Google-Shipping-Label und sendet dieses Label im ProductInput. Google nutzt es anschließend, um das Produkt der passenden Rate Group zuzuordnen.

Für gewichtsabhängige Google-Services bleibt ein positives Bruttoversandgewicht in der Variantenlogistik erforderlich. Workspace sendet das Gewicht als shippingWeight mit Einheit kg.

Produktauswahl und Feldzuordnung

Workspace definiert die Produktmenge über das Product-Channel-Binding. Das Binding verweist auf Site, Vertriebskanal und Provider. Der Google-Merchant- Sync liest daraus die öffentlichen, gelisteten und veröffentlichten Produkte des Vertriebskanals. Für Google Merchant gilt zusätzlich: Workspace sendet nur physische Varianten. Dienstleistungen, digitale Produkte und Lizenzen sind für Google Merchant ausgeschlossen; Workspace exportiert sie nicht mit Dummy-Versanddaten.

Der Produktlink entsteht nicht aus Google-spezifischer Binding-Konfiguration und nicht aus einer festen Kategorie wie produkte. Workspace liest die veröffentlichte dynamische Produktdetail-Route der gebundenen Site, kombiniert sie mit dem ProductRoute.slug des Produkts und baut daraus den absoluten Google-Produktlink. Ein Produkt kann deshalb in Site A, Site B und Site C unterschiedliche Links haben. Wenn für die gebundene Site keine eindeutige veröffentlichte Produktdetail-Route existiert, blockiert Workspace den Feed-Eintrag statt einen Pfad zu raten.

Das Google-image_link stammt aus derselben öffentlichen Medienprojektion wie die Public Storefront. Workspace bevorzugt das Bild mit dem im Binding konfigurierten Medienzweck. Fehlt dieses Zweckbild, verwendet Workspace das öffentliche primäre Produktbild und zeigt eine nicht blockierende Warnung an. Nur wenn kein freigegebenes öffentliches Bild existiert, blockiert Workspace den Feed-Eintrag.

Der Adapter bildet nur explizit unterstützte Felder auf Google Merchant ab, zum Beispiel Titel, Beschreibung, Link, Bild, Preis, Verfügbarkeit, Marke und Versandgewicht. Frei definierbare PIM-Attribute werden nicht automatisch als Google-Felder durchgereicht. Google-spezifische Felder wie googleProductCategory, productTypes, gtin, mpn, identifierExists oder customLabel0 bis customLabel4 benötigen eine bewusste Mapping-Regel, bevor Workspace sie an Google sendet.

Wenn ein früher synchronisiertes Produkt später nicht mehr gelistet, veröffentlicht oder readiness-fähig ist, löscht der nächste passende Product-Channel-Sync den zugehörigen Google ProductInput. Workspace nutzt dabei vorhandene Google-Referenzen, auch wenn der lokale Item-State inzwischen blocked, failed oder skipped ist. Ein Full-Sync prüft alle zuvor übertragenen und noch nicht entfernten Items des Bindings. Ein Varianten-Sync entfernt nur zuvor übertragene Items innerhalb des angeforderten Varianten-Scopes.

Admin-Oberfläche verwenden

Öffnen Sie Handel > Stammdaten > Profile & Kanäle > Produktkanäle. Die Seite zeigt oben den Google-Merchant-Wizard und darunter die Binding-Liste.

Der Wizard führt Sie durch vier Schritte:

1. Voraussetzungen prüft, ob eine Google-Merchant-Provider-Connection vorhanden ist und ob die benötigten Product-Channel-Rechte verfügbar sind. Wenn keine Verbindung existiert, öffnen Sie von dort die zentrale Provider-Connections-Verwaltung.
2. Binding verbindet die Provider-Connection mit Website, Vertriebskanal, Merchant-Konto-ID, Inhaltssprache, Feed-Label und Zielland.
3. Readiness ruft den Binding-Readiness-Check auf. Die Oberfläche zeigt nur i18n-gemappte reasonKey- und detailKeys-Werte.
4. Sync startet den ersten Product-Channel-Sync, wenn die Readiness nicht blockiert und product_channel_bindings:sync vorhanden ist.

Öffnen Sie ein vorhandenes Binding aus der Liste, um Details zu bearbeiten. Der Tab Betrieb zeigt die aktuelle Readiness, die neuesten lokalen Sync-Läufe und die neuesten lokalen Item-States. Diese Sicht liest nur tenant-gebundene Workspace-Daten; Google-Approval-Status und Product-Issues aus Google Merchant Center sind nicht Bestandteil dieser Oberfläche.

Senden Sie das Binding über die Product-Channel-Bindings-API:

POST /api/v1/commerce/config/product-channel-bindings
Content-Type: application/json

{
  "siteId": "00000000-0000-0000-0000-000000000000",
  "salesChannelId": "00000000-0000-0000-0000-000000000000",
  "provider": "google_merchant_center",
  "credentialId": "00000000-0000-0000-0000-000000000000",
  "externalAccountId": "123456789",
  "displayName": "Google Merchant Center DE",
  "imagePurposeKey": "google_merchant",
  "contentLanguage": "de",
  "feedLabel": "DE",
  "targetCountry": "DE",
  "isActive": true
}

Die Antwort enthält die id des Bindings. Verwenden Sie diese ID in den folgenden Readiness- und Sync-Aufrufen als {bindingId}.

Readiness prüfen

Prüfen Sie die Readiness, bevor Sie einen Sync starten:

GET /api/v1/commerce/config/product-channel-bindings/{bindingId}/readiness

Die Antwort zeigt, ob das Binding ready, warning oder blocked ist. Workspace liefert stabile Schlüssel wie reasonKey, ownerArea und providerRequirementRef. Die Antwort enthält keine Google-Rohtexte, keine SQL-Details und keine geheimen Credential-Werte.

Readiness schützt vor unnötigen Provider-Aufrufen. Wenn die Binding-Readiness blockiert ist, startet Workspace keine externen Google-Aufrufe und legt keinen Google-Submit an.

Auch bei einem Google-Provider-Konfigurationsfinding wertet Workspace lokale Produktdaten, Feed- und Medienchecks aus. Die Antwort trennt lokale Produktdaten-Findings von Google-Provider-Konfigurationsfindings, damit Sie Produkt- und Medienkorrekturen unabhängig vom Google-Zugriff prüfen können.

Produktblocker stoppen nur die betroffenen physischen Items. Workspace markiert diese Items als blocked und sendet publish-fähige Produkte weiter, wenn das Binding selbst bereit ist. Nicht-physische Varianten behandelt Workspace als ausgeschlossen. Wenn sie früher bereits an Google Merchant gesendet wurden und eine lokale Provider-Referenz besitzen, entfernt der nächste erfolgreiche Sync sie über den Provider-Delete-Pfad.

Mit nucli prüfen

nucli führt kein OAuth-Onboarding aus. Nutzen Sie nucli api nur für sichere Betriebsprüfung und API-Inspektion:

nucli --tenant <tenant> api GET /api/v1/provider-connections --redact --save provider-connections.json
nucli --tenant <tenant> api POST /api/v1/provider-connections/<credentialId>/test --summary
nucli --tenant <tenant> api POST /api/v1/commerce/config/product-channel-bindings --input product-channel-binding-google-merchant.json --summary
nucli --tenant <tenant> api GET /api/v1/commerce/config/product-channel-bindings/<bindingId>/readiness --summary

Verwenden Sie --redact oder --summary, wenn Sie Ausgaben in Tickets oder Betriebsprotokolle übernehmen. Dokumentieren Sie Tenant, Binding-ID, Credential-ID, Merchant Center Account ID und Testergebnis, aber keine Secrets, Tokens oder OAuth-Codes.

Wenn Sie den Sync über nucli api starten, senden Sie einen expliziten JSON-Body:

printf '{}' | nucli --tenant <tenant> api POST /api/v1/commerce/config/product-channel-bindings/<bindingId>/sync --input - --summary

Sync starten

Starten Sie den Sync erst, wenn die Binding-Readiness nicht blockiert:

POST /api/v1/commerce/config/product-channel-bindings/{bindingId}/sync

Optional können Sie einzelne Varianten übertragen:

{
  "variantIds": ["00000000-0000-0000-0000-000000000000"]
}

Ohne variantIds verarbeitet Workspace die aktuell öffentlichen Produkte des Bindings. Der Taskstream-Job enthält nur Tenant-ID, Binding-ID und optionale Variant-IDs. Er enthält keine Tokens, Merchant Account ID oder Produktpayloads.

Lokale Sync-Läufe und Item-States prüfen

Die Admin-Oberfläche zeigt lokale Betriebsdaten, die Workspace nach einem Sync gespeichert hat. Diese Daten sind tenant-scoped und geben keine Credential- Secrets, Token, Payload-Hashes, Google-Rohpayloads oder internen SQL-Details aus.

Nutzen Sie die API, wenn Sie dieselben Daten in einem Betriebsrunbook prüfen:

GET /api/v1/commerce/config/product-channel-bindings/{bindingId}/sync-runs
GET /api/v1/commerce/config/product-channel-bindings/{bindingId}/item-states

Für Sync-Läufe benötigen Sie product_channel_sync_runs:read. Für Item-States benötigen Sie product_channel_item_states:read. Fremde oder nicht zugängliche Bindings antworten wie nicht vorhandene Bindings mit 404.

Erfolg prüfen

Der Sync-Start ist erfolgreich, wenn die API-Antwort jobId, bindingId und status enthält. Prüfen Sie danach den Taskstream-Job.

Ein erfolgreicher Job bedeutet:

• Workspace konnte das Binding tenant-sicher laden.
• Workspace konnte das OAuth-Credential verwenden.
• Workspace konnte eine Google-API-Datenquelle finden oder anlegen.
• Workspace konnte ProductInputs an Google senden.
• Blockierte Items wurden nicht an Google übertragen.
• Nicht mehr exportfähige Items mit Provider-Referenz wurden aus Google Merchant entfernt und lokal als removed markiert.

Google verarbeitet ProductInputs anschließend asynchron. Ein erfolgreicher Insert bedeutet nicht, dass Google das Produkt genehmigt oder öffentlich anzeigt. Prüfen Sie Genehmigungen, Richtlinienhinweise und Produktstatus in Google Merchant Center.

Häufige Fehlerbilder

Nächste Schritte

• Prüfen Sie Provider-Credentials in Provider-Verbindungen einrichten.
• Nutzen Sie nucli für redigierte Betriebsprüfungen in nucli.
• Richten Sie Search-Console-Daten separat über Google Search Console einrichten ein, wenn Sie Suchmetriken importieren möchten.