Externe Produktklassifikationen zuordnen

Diese Referenz richtet sich an Integratoren, die Produkte für unterschiedliche Plattformen klassifizieren. Shopnavigation und externe Klassifikation werden getrennt gepflegt. Ein Produkt kann deshalb in einem B2C-Shop unter „Freizeit“, im B2B-Shop unter „Arbeitsausstattung“ und bei einer Plattform unter deren eigener Kategorie erscheinen. Lokale Kategorien und öffentliche URLs ändern sich durch einen Taxonomieimport nicht.

Der Vertrag umfasst manuelle normalisierte Importe, Zuordnungsregeln, Vorschläge, ausdrückliche Bestätigung und lokale Anforderungsprüfung. Er veröffentlicht keine Produkte auf Amazon, Google oder Kaufland und synchronisiert deren Taxonomien nicht automatisch.

Revision importieren

Ein Import pinnt Plattformprofil, Markt und Version. Unterstützte Profile:

Bereiten Sie die externe Quelle als normalisiertes JSON vor:

{
  "schemaVersion": "1",
  "profile": "google_product_category",
  "market": "DE",
  "version": "2026-10",
  "nodes": [
    {
      "externalId": "example-category",
      "label": "Beispielkategorie",
      "requirements": [
        {"key": "color", "type": "string", "required": true, "enum": ["blue"]}
      ]
    }
  ]
}

Die Beispiel-ID und Anforderungen dienen nur der Formaterklärung; übernehmen Sie die tatsächlichen Werte aus Ihrer Plattformquelle. Optional beschreibt parentExternalId die externe Hierarchie. requirements muss sämtliche anwendbaren Anforderungen des ausgewählten Knotens enthalten; Elternwerte werden nicht automatisch geerbt. Übernehmen Sie auch geerbte Anforderungen in das normalisierte Dokument und benennen Sie nicht unterstützte Bedingungen, verschachtelte Schemata, entfernte Referenzen oder Plattformregeln als Lücke. Der Import akzeptiert höchstens 10.000 Knoten und lädt keine entfernten Schemata nach. Unbekannte JSON-Felder werden abgelehnt.

nucli --tenant <tenant> pim taxonomies import --input taxonomy.json --json

Eine identische Wiederholung desselben Imports ist idempotent. Anderer Inhalt unter derselben Kombination aus Profil, Markt und Version ist ein Konflikt; verwenden Sie dafür eine neue Version. Importierte Revisionen bleiben unveränderlich. Eine externe ID ist keine lokale Kategorie-UUID.

Vorschläge und Bestätigung

Pflegen Sie Regeln über die Ressource integrations-external-mapping-rules. Der Metadatenvertrag beschreibt die schreibbaren Felder:

nucli --tenant <tenant> resources meta integrations-external-mapping-rules

Eine Regel bindet Vertriebskanal, Revision und externe Ziel-ID. Ihre Prädikate prüfen interne Familienkategorien oder Produktattribute mit equals, in oder exists; alle Prädikate müssen passen. Variantenattribute überschreiben gleichnamige Familienattribute. Ein Vorschlag nennt Regel, Revision und Begründung. Widersprüchliche Zielvorschläge verlangen eine ausdrückliche Auswahl.

nucli --tenant <tenant> pim taxonomies propose --publication <publication-uuid> --json
nucli --tenant <tenant> pim taxonomies confirm --publication <publication-uuid> --revision <revision-uuid> --external-id <platform-id> --json
nucli --tenant <tenant> pim taxonomies check --publication <publication-uuid> --json

Bestätigen Sie nur an einer veränderbaren Variantenveröffentlichung im Zustand draft oder rejected. --rule <rule-uuid> dokumentiert bei Bedarf die Herkunft der Auswahl. Die Bestätigung pinnt die Revision. Neue Importe oder Regeln und erneute Vorschläge überschreiben keine bestätigte Auswahl. Unvollständige Produktdaten können weiter bearbeitet werden; Bestätigung und Anforderungsprüfung sind getrennte Schritte. Die Auswahl gilt je Veröffentlichung, Profil und Markt; mehrere Amazon-Klassifikationen sowie Google- und Kaufland-Ziele können nebeneinander bestehen.

Die HTTP-Verträge liegen unter /api/v1:

Interne Kategorien für Regeln auswählen

Die private, authentisierte Auswahlliste verwendet GET /api/v1/pim/categories?treePurpose=internal. Sie enthält nur Kategorien in lebenden internen Bäumen desselben Mandanten. Ungebundene Kategorien, gelöschte Knoten und fremde Mandanten erscheinen nicht. Zusätzliches treeId schränkt die Liste weiter ein. Der optionale salesChannelId-Filter wählt zugelassene Shopbäume; zusammen mit treePurpose=internal ergibt sich deshalb eine leere Schnittmenge. Die private Liste wird nicht aus der Storefront aufgerufen.

Für source=internal_category prüfen equals und in direkte Familienzuordnungen. Shopkategorien und implizite Ahnen oder Nachfahren zählen nicht mit. Kategorie-IDs werden als UUID-Identität verglichen; Großbuchstaben und eine 32-stellige Hexschreibweise passen auf dieselbe UUID. Bei source=attribute unterscheidet die Prüfung dagegen Groß- und Kleinschreibung in Schlüsseln und Stringwerten. Externe IDs werden ebenfalls nicht normalisiert.

Anforderungen prüfen

Die Anforderungsprüfung auf dem Server unterstützt string, number, integer, boolean, Pflichtwerte, Enumerationen sowie minItems und maxItems. Über HTTP und NuCLI werden numerische JSON-Werte exakt verglichen, auch wenn eine Ganzzahl nicht mehr exakt in float64 darstellbar wäre. Die Zahlen-Tokens sind auf 256 Zeichen begrenzt; wissenschaftliche Exponenten liegen zwischen -308 und 308. Numerische Regelwerte und importierte Enumerationen außerhalb dieser Grenzen werden abgelehnt. Bei Produktwerten außerhalb der unterstützten Grenzen meldet die lokale Prüfung einen Typfehler und bestätigt keine Bereitschaft. Nicht unterstützte Anforderungen werden über unsupportedFeatures ausdrücklich benannt, beispielsweise conditionalRequired. Solche Lücken verhindern ready=true; sie werden nicht stillschweigend als erfüllt gewertet.

Ohne bestätigte Auswahl liefert die Prüfung checks: []; das ist kein Bereitschaftsnachweis. Ein positives lokales Ergebnis bedeutet nur, dass die unterstützten importierten Anforderungen erfüllt sind. Es bestätigt weder die vollständige Plattformkonformität noch eine erfolgreiche Übertragung. Prüfen Sie weiterhin den jeweiligen Plattformvertrag und den späteren Connector.

Zahlen in Admin-Formularen bearbeiten

Die Admin-Formulare für Regel-Literale und den nodes-Import prüfen Zahlen vor dem Schreiben. Nach dem Einlesen und erneuten Serialisieren muss eine eingegebene JSON-Zahl denselben mathematischen Wert haben. Rundung, nicht endliche Werte und Ganzzahlen außerhalb des sicheren JavaScript-Bereichs werden mit einem Hinweis auf die Editorgrenze und NuCLI abgewiesen. Gleichwertige Schreibweisen mit Exponenten oder nachgestellten Nullen sind möglich, wenn diese Prüfung besteht.

Beispielsweise lässt sich 9007199254740993 über das Admin-Formular nicht als Zahl speichern. Verwenden Sie für solche exakten Zahlenwerte die ursprüngliche JSON-Datei mit NuCLI oder den HTTP-Vertrag innerhalb der oben genannten Servergrenzen. Der Werttyp muss weiterhin zur Anforderung passen.

Die Formularprüfung bezieht sich auf eingegebene JSON-Tokens und den Schreibvorgang. Hat der Browser einen Wert aus einer Serverantwort bereits als JavaScript-Zahl eingelesen, kann verlorene Genauigkeit dadurch weder nachgewiesen noch wiederhergestellt werden. Für solche bereits eingelesenen Werte gibt es keine Exaktheitszusage der Admin-Oberfläche.

Prüfung

Vergleichen Sie nach dem Import Profil, Markt, Version und externe IDs mit der Quelle. Prüfen Sie für eine Veröffentlichung passende und widersprüchliche Regeln, fehlende Pflichtwerte und eine nicht unterstützte Anforderung. Die gewählte Revision muss nach einem weiteren Import unverändert bleiben. Shopnavigation und Kategorieadressen müssen ebenfalls unverändert bleiben.