Externe Datenquellen für Listen

Mit diesem Add-On können Auswahllisten in der Personalisierung automatisch mit Inhalten aus einer externen Schnittstelle (z. B. REST-API) gefüllt werden. Das ermöglicht dynamische, aktuelle Daten z. B. für Marken, Firmenstandorte oder Ansprechpartner – ohne manuelle Pflege der Listeneinträge.

Hinweis zur Vorschauerzeugung

Wenn dieses Add-On verwendet wird, sollte die automatische Vorschauerzeugung bei Listenauswahl deaktiviert werden (zu finden unter:
„Verwaltung » Shops » Softproof“), um Ladeprobleme oder ungewollte Vorschauinhalte zu vermeiden.

Einrichtung & Konfiguration

Eine neue externe Datenquelle wird wie folgt konfiguriert:

Einstellung	Beschreibung

Einstellung	Beschreibung
Bezeichnung	Interner Name der Datenquelle
Basis-Endpunkt	Grund-URL der externen Schnittstelle (z. B. `https://api.example.com/`)
Authorisierungs-Parameter	Name des HTTP-Headers für den Zugriff (z. B. `api-key`)
Authorisierungs-Key	Der tatsächliche Zugangsschlüssel / Token
Caching-Dauer	Dauer (in Sekunden), wie lange die Daten im Zwischenspeicher gehalten werden (0 = kein Cache)

Sobald eine Datenquelle gespeichert ist, erscheint sie in der Übersicht und kann dort jederzeit bearbeitet oder gelöscht werden.

Automatische Endpunkt-Zuweisung (Standardschema)

Die Datenquelle verwendet in der Standardkonfiguration ein fest definiertes Schemasystem, bei dem die wichtigsten Endpunkte automatisch verfügbar sind. Diese enthalten bereits vorkonfigurierte Felder, Bezeichnungen und Abhängigkeiten.

Für individuelle Erweiterungen (z. B. zusätzliche Endpunkte oder spezielle Rückgabeformate) kann der Support kontaktiert werden.

Nutzung in der Personalisierung

In der Druckvorlagenerstellung kann ein Feld (z. B. eine Dropdown-Auswahl) mit einer externen Datenquelle verbunden werden.

Dazu werden zwei Angaben benötigt:

Die Bezeichnung der Datenquelle
Der gewünschte Endpunkt-Name

Alle über die Schnittstelle gelieferten Daten stehen innerhalb der Personalisierung als Variable zur Verfügung (z. B. {$nameShort}, {$personalNumber}).

Beispiel: Rückgabewerte der Schnittstelle

Endpunkt brand

{
  "_embedded": {
    "brand": [
      {
        "id": 123,
        "name": "Lead Print",
        "nameShort": "lp",
        "matchCode": "LP"
      }
    ]
  }
}

Endpunkt companyCode

{
  "_embedded": {
    "companyCode": [
      {
        "companyCode": "0100",
        "name1": "Mustermann KG",
        "city": "Willich"
      }
    ]
  }
}

Endpunkt person

{
  "_embedded": {
    "person": [
      {
        "personalNumber": "12345",
        "firstname": "Max",
        "name": "Mustermann"
      }
    ]
  }
}

Übersicht der verfügbaren Endpunkte (Standardschema)

ID	Beschreibung der Auswahl	Abhängigkeit	Typische Werte/Beispiele

ID	Beschreibung der Auswahl	Abhängigkeit	Typische Werte/Beispiele
`brand`	Marken	–	Lead Print, Be.Beyond GmbH & Co. KG
`companyCode`	Unternehmenskennungen der Marke	`brand`	Mustermann KG, Example GmbH
`locationTypes`	Art des Standorts	`brand`	Haupthaus, Niederlassung, Ausstellung
`logicalLocation`	Konkrete Standorte mit Adresse & Zeiten	`companyCode`, `locationTypes`	Filiale Köln, Ausstellung München
`person`	Ansprechpartner je nach Standort oder Firma	`logicalLocation`	Max Mustermann, Sarah Beispiel
`responsibilities`	Rollen oder Zuständigkeiten	–	Vertrieb, Buchhaltung, Standortleitung
`personByResponsibility`	Personen mit einer bestimmten Rolle	`responsibilities`	Filialleiter Max, Buchhalterin Anna
`bankAccount`	Bankverbindungen zur Firma	`companyCode`	Sparkasse – Konto 1, Volksbank – Konto 2

Abhängigkeiten im Ablauf (Einfach erklärt)

Marke auswählen → zeigt passende Firmen
Firma wählen → zeigt zugehörige Standorte
Standorttyp wählen → filtert nach Art (z. B. ABEX oder Ausstellung)
Standort wählen → zeigt zugehörige Mitarbeitende
Person wählen → optional: speichert Werte für die Personalisierung
Rolle wählen → zeigt Personen mit genau dieser Zuständigkeit
Bankkonto wählen → zeigt Zahlungsdaten der Firma

Nutzung in Druckvorlagen

Wird in einer Druckvorlage ein Endpunkt verwendet, können die enthaltenen Daten als Variable direkt im Layout eingebunden werden:

Beispiel: {$name} → zeigt den Nachnamen einer ausgewählten Person
Beispiel: {$address.street} → zeigt die Straße eines gewählten Standorts