Produktdokumente

Zu einem BC-Artikel lassen sich typisierte Produktdokumente pflegen – Datenblatt, Handbuch, Konformitätserklärung, Sicherheitsdatenblatt, Broschüre u. a. Der Shopware 6 Connector lädt diese Dokumente in die shop-eigene Media hoch und verlinkt sie über Custom Fields am Produkt. Der Kunde findet die Downloads öffentlich auf der Produktseite.

Zentral im Hub gepflegt

Die Dokumente liegen zentral im merchantCENTRAL Hub je BC-Artikel (ALN MC Product Document) und stehen damit allen Marktplatz-Connectoren zur Verfügung – nicht nur Shopware. Der Connector überträgt sie in den Shop.

Seite öffnen

Produktdokumente werden am BC-Artikel gepflegt (Hub-Funktion „Produktdokumente").
Die Übertragung erfolgt beim Artikel-Upload in den Shop; der Ablage-Status je Shop wird intern in Shopware 6 Product Document Media geführt.

Ansehen und Öffnen

Auf der Artikelkarte zeigt die Gruppe Produktdokumente zuerst eine Galerie: je Dokument eine Kachel mit Dateityp, Titel, Dokumentart, Sprache, Dateiname und Ablageort. Ein Klick auf die Kachel öffnet das Dokument – eine Datei im Medienspeicher oder hinter einer externen URL im Browser, eine in Business Central gespeicherte Datei als Download. Darunter steht die Liste Dokumente bearbeiten für Art, Sprache, Reihenfolge und Dateien.

Dieselbe Galerie öffnet die Aktion Produktdokumente-Vorschau auf der Artikelkarte – und in Connectoren, die Dokumente zählen (etwa Icecat), der Klick auf die Zahl.

In den Listen (Artikelkarte und globale Liste Produktdokumente) öffnet ein Klick auf Öffnen oder den Dateinamen das Dokument ebenfalls; die Aktion Dokument öffnen steht an erster Stelle. In der Kachelansicht der globalen Liste zeigt jede Kachel Artikelnr., Dokumentart, Titel, Quelle und Dateiname.

Quellen

Jede Dokumentzeile hat eine Quelle – in allen Fällen landet die Datei am Ende in der Shop-Media (keine toten Links, CDN/Caching des Shops inklusive):

Quelle	Ablage
BC-Artikel-Anhang	Standard-Anhänge (Document Attachment) am Artikel
Hub-Datei	Medienfeld direkt an der Dokumentzeile im Hub – in der BC-Datenbank
Medienspeicher	Azure-Medienspeicher des Kunden, dieselbe Ablage wie die Produktbilder; die Zeile hält nur die öffentliche URL
Externe URL	nur der Link (Hersteller-PDF); Shopware holt die Datei selbst (Upload-from-URL)

Wohin heruntergeladene Dateien gehen

„Hub-Datei" und „Medienspeicher" setzt nicht der Anwender, sondern der Hub selbst – immer dann, wenn eine Datei tatsächlich in den Hub gelangt: über Datei hochladen, über Datei von URL abrufen oder über einen Connector wie Icecat, der sie beim Anreichern holt. Wohin sie geht, steuert Dokumentenspeicher in der merchantCENTRAL-Einrichtung:

Einstellung	Wirkung
Business Central (Standard)	Die Datei liegt im Medienfeld der Dokumentzeile. Ohne weitere Einrichtung nutzbar, zählt aber auf das Datenbankkontingent der Umgebung – bei einem großen Artikelstamm mit Datenblättern der relevante Posten.
Medienspeicher	Die Datei liegt im Azure-Speicherkonto des Kunden, in der Datenbank bleibt nur die URL. Setzt einen eingerichteten Medienspeicher voraus.

Fallback statt Datenverlust

Ist der Medienspeicher nicht eingerichtet oder schlägt der Upload fehl, wird die Datei in Business Central gespeichert statt verworfen. Der Sammelabruf nennt solche Fälle in der Ergebnismeldung, der Einzelabruf als Hinweis – sonst würde nie auffallen, dass die Dateien entgegen der Einstellung in der Datenbank landen.

Der Medienspeicher ist öffentlich

Es ist derselbe CDN-Container wie für die Produktbilder: Wer die URL kennt, kann die Datei ohne Anmeldung abrufen. Für Datenblätter, Handbücher und Prospekte ist genau das der Zweck – für vertrauliche Dokumente ist es der falsche Ort. Solche Dokumente gehören mit Business Central als Dokumentenspeicher in die Datenbank.

Wird eine Dokumentzeile gelöscht, entfernt der Hub die Datei im Medienspeicher mit – ebenso beim Löschen des Artikels, dessen Dokumente dabei mit aufgeräumt werden. Ein Löschen, das den Tabellentrigger übergeht (Massenlöschung per DeleteAll(false) aus fremdem Code), lässt die Datei dagegen stehen.

Die Ablage im Container ist documents/{Mandant}/{Artikelnr.}/{Zeilennr.}.{Endung}. Das Mandantensegment ist wichtig: Tragen Sie in zwei Mandanten dasselbe Speicherkonto und denselben Container ein, bleiben die Dateien trotzdem getrennt.

Einstellungen (Setup / je Shop)

Feld	Wo	Beschreibung
Produktdokumente synchronisieren	Shop (Override)	Ob Produktdokumente beim Artikel-Push in diesen Shop hochgeladen werden (Default / Yes / No).
Feldname Produktdokumente	Setup / Shop	Technisches Shopware-Custom-Field, das die Dokumentliste als JSON-Text erhält (Feldtyp Text – die Shopware-Administration bietet keinen JSON-Feldtyp an; das Theme dekodiert den Text). Standard `ad_documents` – auf das Custom Field des Ziel-Themes einstellen.
Feldname Datenblatt-URL	Setup / Shop	Custom Field für die primäre Datenblatt-URL. Standard `ad_datasheet_url`.
Dokumente in den Shop hochladen	Setup / Shop (Override)	Separater Schalter: lädt gebuchte Rechnungen/Gutschriften als PDF an die Shop-Bestellung (nicht an das Produkt).

Nur geänderte Dokumente

Unveränderte Dokumente werden beim erneuten Upload übersprungen (Zeitstempel-Abgleich je Shop). Ein neueres Dokument im Hub löst automatisch einen erneuten Upload aus.

Ablauf

Am BC-Artikel die Produktdokumente pflegen (Quelle je Zeile wählen).
Im Shop-Setup das passende Custom Field (Theme) unter Product Documents Field Name hinterlegen.
Je Shop Produktdokumente synchronisieren auf Default oder Yes lassen.
Artikel hochladen – die Dokumente werden in die Shop-Media geladen und am Produkt verlinkt.
Im Storefront/Theme die Dokumente an der Produktseite anzeigen (Theme-abhängig).

Datenformat (für Theme-Entwickler)

Das Custom Field enthält die Dokumentliste als JSON-Text, ein Array von Objekten:

[
  {
    "type": "manual",
    "typeLabel": "Handbuch",
    "title": "Bedienungsanleitung",
    "url": "https://shop.example.com/media/…/bedienungsanleitung.pdf",
    "mediaId": "018f36cd6a1e7c9b…",
    "position": 1
  }
]

Schlüssel	Bedeutung
`type`	Stabiler, sprachunabhängiger Typ-Schlüssel – das Theme gruppiert und übersetzt darüber (Snippets). Werte: `datasheet`, `manual`, `certificate`, `safety_data_sheet`, `brochure`, `other`. Unbekannte künftige Typen kommen als `other`.
`typeLabel`	Typ-Bezeichnung in der BC-Sitzungssprache – lesbarer Fallback für Themes ohne eigene Snippets.
`title`	Dokumenttitel (leer gepflegt → Typ-Bezeichnung).
`url`	Öffentliche Media-URL der Datei im Shop.
`mediaId`	UUID der Media-Entität im Shop.
`position`	Sortierung aus der BC-Dokumentliste.

Das zweite Feld (Datasheet URL Field Name, Standard ad_datasheet_url) enthält als einfachen Text die URL des ersten Datenblatts – für Themes, die nur einen prominenten Datenblatt-Link zeigen.