JSON-Schnittstelle - WEBSALE Dokumentation

Manche Angaben passen in kein Feld der Warenwirtschaft: technische Datenblätter zu einem Produkt, Versandlaufzeiten je Postleitzahl, ein Menübaum, die Antwort eines Zahlungsanbieters. Die JSON-Schnittstelle bringt solche Daten an beliebige Stellen im Template, und zwar so, dass sie sich dort wie Shopdaten verwenden lassen. Typische Anwendungen:

zusätzliche Produktinformationen, Bilder und technische Parameter
Sendungsverfolgung im Kundenkonto
ein vollständiges Hauptmenü samt Untermenüs
Topseller-Strukturen und Cross-Links für Kategorien oder Produkte
Postleitzahlenlisten mit Versandlaufzeiten und europaweite Feiertage für die Lieferzeitberechnung
Bewertungen von Drittanbietern
Inhalte aus einem Redaktionssystem

Die Richtung stimmt dabei in beide Wege: Der Shop kann JSON-Daten nicht nur lesen, sondern auch selbst erzeugen und verändern, um sie per AJAX, JavaScript oder E-Mail weiterzugeben. Für den Versand an fremde Systeme eignet sich ASSE.

Woher die Daten kommen

Typ	Herkunft	Freischaltung nötig
`global`	Datei im Wurzelverzeichnis des JSON-FTP-Zugangs, gilt für alle Subshops	ja
`subshop`	Datei im Subshop-Verzeichnis desselben FTP-Zugangs	ja
`userdir`	Datei im Verzeichnis `benutzer` des gewöhnlichen Shop-FTP-Zugangs	ja
`intern`	Daten, die der Shop selbst oder ein fremdes System im Moment des Aufrufs liefert	nein

Freischaltung und FTP-Zugang

Lassen Sie die JSON-Schnittstelle für Ihren Shop freischalten. Sie bekommen dafür einen eigenen FTP-Zugang mit Server, Benutzername und Passwort. Wollen Sie ausschließlich mit internen Daten arbeiten, also mit Antworten fremder Systeme, brauchen Sie weder Freischaltung noch eigenen FTP-Zugang.

Die Ordnerstruktur

Im Wurzelverzeichnis liegen die Dateien, die für alle Shops und Subshops gelten. Soll ein Subshop eigene Dateien bekommen, legen Sie ein Verzeichnis mit der Subshop-ID an und legen die Dateien dort ab. Der Dateiname muss in allen Subshop-Verzeichnissen derselbe sein. Welche Datei geladen wird, entscheidet der Subshop, in dem der Besucher gerade ist. Weitere Unterverzeichnisse dürfen Sie frei anlegen.

Legen Sie nicht mehr als 500 JSON-Dateien in ein Verzeichnis. Darüber leidet die Geschwindigkeit. Teilen Sie die Dateien stattdessen auf Unterverzeichnisse auf.

Anforderungen an die Dateien

Anforderung	Grund
genau ein JSON-Objekt oder genau ein Array von Objekten je Datei	mehr kann die Schnittstelle nicht laden
UTF-8-codiert	andere Codierungen werden nicht gelesen
Namen ohne Punkt, ohne eckige, runde und geschweifte Klammern, ohne Dollarzeichen und Tilde	diese Zeichen haben im Zugriffspfad und in der Tag-Sprache eine eigene Bedeutung

{
   "Name": "Wert",
   "Name(2.0)": "Wert (2.0)"
}

Der zweite Name ist ungültig, weil er Klammern und einen Punkt enthält. Richtig:

{
   "Name": "Wert",
   "Name2": "Wert (2.0)"
}

Ein Tag darf höchstens 128 Zeichen lang sein, und der Zugriffspfad steht im Tag. Halten Sie die Namen deshalb kurz und die Hierarchien flach. Bei tief verschachtelten Daten mit langen Namen stoßen Sie an diese Grenze.

Die beiden Tag-Familien

Präfix	Bedeutung	Tag-in-Tag
`EJD-`	External JSON Data	möglich
`EJD-DA-`	External JSON Data Direct Access, Zugriff über Pfad und ID	bei den meisten nicht möglich

Die Tags funktionieren auf allen Templates. Eine Anpassung der shop.config ist nicht nötig.

Daten laden

Geladen wird mit EJD-LoadData(). Das Tag nimmt drei Angaben: den Typ, den Pfad und eine Kennung.

<!-- global: aus dem Wurzelverzeichnis -->
~EJD-LoadData(global,file.json,jdat)~

<!-- global aus einem Unterverzeichnis -->
~EJD-LoadData(global,verzeichnis1/verzeichnis2/file.json,jdat)~

<!-- subshop: aus dem Verzeichnis des aktuellen Subshops -->
~EJD-LoadData(subshop,file.json,jdat)~

<!-- userdir: aus dem Verzeichnis "benutzer" des Shop-FTP-Zugangs -->
~EJD-LoadData(userdir,navigation/grafiken/json/file.json,jdat)~

Die Kennung im dritten Feld vergeben Sie frei. Alle folgenden Tags greifen darüber auf die geladenen Daten zu. In einem Template lassen sich mehrere Dateien parallel laden, jede mit einer eigenen Kennung.

Höchstens 100 JSON-Dateien lassen sich gleichzeitig laden.

Referenz: EJD-LoadData()

Prüfen, ob die Daten angekommen sind

~EJD-LoadData(global,file.json,jdat)~

{EJD-DataOK(jdat)}
   JSON-Daten sind geladen.
{/EJD-DataOK(jdat)}

{!EJD-DataOK(jdat)}
   JSON-Daten konnten nicht geladen werden. Fehlercode: ~EJD-DataOK(jdat)~
{/!EJD-DataOK(jdat)}

Das negative Tag gibt als Einzel-Tag den Fehlercode aus. Damit lässt sich unterscheiden, ob die Datei fehlt oder ob sie kein gültiges JSON enthält. Referenz: EJD-DataOK()

Auf Werte zugreifen

Ein Wert wird über seinen Zugriffspfad angesprochen. Dieser entsteht aus den Namen der Ebenen, verbunden durch Punkte. Elemente eines Arrays bekommen ihren Index in eckigen Klammern, gezählt ab null. Für das oberste Element steht ein leerer Pfad oder _root_. Die folgenden Beispiele arbeiten mit dieser Datei:

{
   "Produktname": "Sportlicher Sneaker",
   "Produktnummer": "A-1234",
   "AdditionalInfo":
   {
      "Beschreibung": "Moderne Schuhe für jeden Anlass",
      "lieferbar": true,
      "Crosslinks": [ "A-5678", "B-9876", "C-2323" ],
      "Lagerbestand": 42,
      "Preis": 59.95
   }
}

Gesuchter Wert	Zugriffspfad
`A-1234`	`Produktnummer`
`Moderne Schuhe für jeden Anlass`	`AdditionalInfo.Beschreibung`
`B-9876`	`AdditionalInfo.Crosslinks[1]`

Im Template:

~EJD-LoadData(subshop,$PR-Number$.json,jdat)~

{EJD-DataOK(jdat)}
   Produktnummer: ~EJD-DA-Value(Produktnummer,jdat)~<br>
   Beschreibung: ~EJD-DA-Value(AdditionalInfo.Beschreibung,jdat)~<br>
   Zweiter Crosslink: ~EJD-DA-Value(AdditionalInfo.Crosslinks[1],jdat)~
{/EJD-DataOK(jdat)}

Produktnummer: A-1234
Beschreibung: Moderne Schuhe für jeden Anlass
Zweiter Crosslink: B-9876

Der Dateiname darf selbst aus einem Tag kommen. Im Beispiel wird je Produkt die Datei mit der Produktnummer im Namen geladen. Referenz: EJD-DA-Value()

Die Kennung einmal setzen

Wird auf dem Template nur eine Datei verwendet, erspart EJD-SetUseID() die Wiederholung der Kennung in jedem Tag.

~EJD-LoadData(subshop,file.json,jdat)~

{EJD-DataOK(jdat)}
   ~EJD-SetUseID(jdat)~
   Beschreibung: ~EJD-DA-Value(AdditionalInfo.Beschreibung)~
{/EJD-DataOK(jdat)}

EJD-DataOK() braucht die Kennung weiterhin. Für dieses eine Tag greift die Voreinstellung nicht.

Referenz: EJD-SetUseID()

Werte in anderen Tags weiterverwenden

Die EJD-DA--Tags tragen ihre Angaben in Klammern und lassen sich deshalb nicht einfach in andere Tags schachteln. Der Shop merkt sich aber jeden Wert und jeden Namen, den ein solches Tag anfasst. Über EJD-LastValueAccessed und EJD-LastNameAccessed kommen Sie an das zuletzt Angefasste heran, und dieses lässt sich wie jeder andere Wert weiterverwenden.

~EJD-LoadData(subshop,$PR-Number$.json,jdat)~

{EJD-DataOK(jdat)}
   ~EJD-SetUseID(jdat)~

   Beschreibung: ~EJD-DA-Value(AdditionalInfo.Beschreibung)~<br>

   <!-- gibt die Anzahl aus und merkt sie zugleich -->
   Anzahl der Crosslinks: ~EJD-DA-ArrayElements(AdditionalInfo.Crosslinks)~<br>

   <!-- die gemerkte Anzahl wird zur Anzahl der Schleifendurchläufe -->
   ~DC-ZeroLoop1_set($EJD-LastValueAccessed$)~
   {@DC-ZeroLoop1}
      Crosslink #~DC-ZeroLoop1_position~: ~EJD-DA-Value(AdditionalInfo.Crosslinks[$DC-ZeroLoop1_position$])~<br>
   {/@DC-ZeroLoop1}

{/EJD-DataOK(jdat)}

Beschreibung: Moderne Schuhe für jeden Anlass
Anzahl der Crosslinks: 3
Crosslink #1: A-5678
Crosslink #2: B-9876
Crosslink #3: C-2323

Soll ein Wert gemerkt, aber nicht ausgegeben werden, gibt es dafür eigene Tags:

Tag	Merkt sich
`EJD-DA-TouchValue()`	den Wert
`EJD-DA-TouchName()`	den Namen
`EJD-DA-TouchArrayElements()`	die Anzahl der Array-Elemente

Der Zugriffspfad lässt sich auch in einem freien Platzhalter zusammenbauen, wenn der Index aus einer Schleife kommt:

~DC-FP1_set(AdditionalInfo.Crosslinks[)~
~DC-FP1_append($DC-ZeroLoop1_position$)~
~DC-FP1_append(])~
~EJD-DA-Value($DC-FP1$)~

Referenz: EJD-DA-ArrayElements() · EJD-LastValueAccessed · EJD-LastNameAccessed · EJD-DA-TouchName() · EJD-DA-TouchValue() · EJD-DA-TouchArrayElements() · DC-ZeroLoop1…3 · DC-ZeroLoop1…3_set() · DC-ZeroLoop1…3_position

Nachkommastellen festlegen

~EJD-SetRealOutputFormat(4)~
Preis: ~EJD-DA-Value(AdditionalInfo.Preis)~

Preis: 59.9500

Referenz: EJD-SetRealOutputFormat()

Elemente prüfen

Die Art eines Wertes lässt sich abfragen. Dabei wird der Wert zugleich gemerkt.

{EJD-DA-IsTrue(AdditionalInfo.lieferbar,jdat)}
   Das Produkt ist lieferbar.
{/EJD-DA-IsTrue(AdditionalInfo.lieferbar,jdat)}

Zur Verfügung stehen EJD-DA-IsTrue(), EJD-DA-IsFalse(), EJD-DA-IsNull(), EJD-DA-IsNumber(), EJD-DA-IsReal(), EJD-DA-IsString(), EJD-DA-IsObject() und EJD-DA-IsArray(). Ob ein Name überhaupt vorkommt, beantwortet ein eigenes Tag. Es merkt sich dabei den Namen.

{EJD-DA-NameExists(AdditionalInfo.Crosslinks,jdat)}
   Es gibt ein Element mit diesem Namen: ~EJD-LastNameAccessed~
{/EJD-DA-NameExists(AdditionalInfo.Crosslinks,jdat)}

Ausgegeben wird Crosslinks, also der letzte Teil des Pfades, nicht der ganze Pfad. Referenz: EJD-DA-IsTrue() · EJD-DA-IsFalse() · EJD-DA-IsNull() · EJD-DA-IsNumber() · EJD-DA-IsObject() · EJD-DA-IsReal() · EJD-DA-IsString() · EJD-DA-IsArray() · EJD-DA-NameExists()

Über Elemente laufen

Kennen Sie die Namen der Elemente nicht im Voraus, läuft EJD-ElementIterator() über sie hinweg. Als Schleife wiederholt das Tag den Code, als Einzel-Tag gibt es den Namen des aktuellen Elements aus.

{
   "Customer": "D200299",
   "Items": {
      "001119090": { "Sales CY": 11, "Sales PY": 174 },
      "001129090": { "Sales CY": 76, "Sales PY": 650 },
      "001169090": { "Sales CY": 5,  "Sales PY": 206, "OrderBacklog": 1 },
      "001189090": { "OrderBacklog": 1 }
   }
}

~EJD-LoadData(global,D200299.json,bezuege)~

{EJD-DataOK(bezuege)}
   ~EJD-SetUseID(bezuege)~

   {@EJD-ElementIterator(Items)}
      Artikel: ~EJD-ElementIterator~
      Letztes Jahr: ~EJD-DA-Value(Items.$EJD-ElementIterator$.Sales PY)~
      Dieses Jahr: ~EJD-DA-Value(Items.$EJD-ElementIterator$.Sales CY)~
      Auftragsbestand: ~EJD-DA-Value(Items.$EJD-ElementIterator$.OrderBacklog)~<br>
   {/@EJD-ElementIterator(Items)}

{/EJD-DataOK(bezuege)}

Artikel: 001119090 Letztes Jahr: 174 Dieses Jahr: 11 Auftragsbestand:
Artikel: 001129090 Letztes Jahr: 650 Dieses Jahr: 76 Auftragsbestand:
Artikel: 001169090 Letztes Jahr: 206 Dieses Jahr: 5 Auftragsbestand: 1
Artikel: 001189090 Letztes Jahr: Dieses Jahr: Auftragsbestand: 1

Fehlt ein Element, bleibt die Stelle leer, ohne Fehler. Wo das stört, prüfen Sie vorher mit EJD-DA-NameExists(). Referenz: EJD-ElementIterator()

Eigene JSON-Daten erzeugen

Der Shop kann JSON-Daten auch selbst aufbauen oder geladene Daten verändern und danach ausgeben. Drei Regeln gelten dabei:

Gibt es das Element unter dem angegebenen Pfad schon, wird es überschrieben.
Gibt es es noch nicht, wird es angelegt.
Je Aufruf lässt sich genau ein Element bearbeiten.

Einfache Werte

~EJD-CreateNewData(jdat)~

{EJD-DataOK(jdat)}
   ~EJD-DA-SetStringValue(testString,abc,jdat)~
   ~EJD-DA-SetNumberValue(testInteger,1,jdat)~
   ~EJD-DA-SetRealValue(testReal,1.23,jdat)~
   ~EJD-DA-SetToTrue(testTrue,jdat)~
   ~EJD-DA-SetToFalse(testFalse,jdat)~
   ~EJD-DA-SetToNull(testNull,jdat)~

   ~EJD-RawDataOutput(jdat)~
{/EJD-DataOK(jdat)}

{ "testString": "abc", "testInteger": 1, "testReal": 1.23, "testTrue": true, "testFalse": false, "testNull": null }

Arrays

Ein leeres Array wird angelegt und dann Stelle für Stelle erweitert. Ob Sie abwechselnd erweitern und füllen oder erst alle Stellen anlegen und dann füllen, bleibt Ihnen überlassen.

~EJD-CreateNewData(jdat)~

{EJD-DataOK(jdat)}
   ~EJD-DA-SetToEmptyArray(Crosslinks,jdat)~
   ~EJD-DA-ArrayExtend(Crosslinks,jdat)~
   ~EJD-DA-SetStringValue(Crosslinks[0],A-12345,jdat)~
   ~EJD-DA-ArrayExtend(Crosslinks,jdat)~
   ~EJD-DA-SetStringValue(Crosslinks[1],A-2323,jdat)~

   ~EJD-RawDataOutput(jdat)~
{/EJD-DataOK(jdat)}

{ "Crosslinks": [ "A-12345", "A-2323" ] }

Soll das Array selbst die oberste Ebene sein, lautet der Pfad _root_.

~EJD-DA-SetToEmptyArray(_root_,jdat)~
~EJD-DA-ArrayExtend(_root_,jdat)~
~EJD-DA-SetStringValue(_root_[0],A-12345,jdat)~

[ "A-12345" ]

Ein Element entfernen:

~EJD-DA-DeleteElement(Crosslinks[1],jdat)~

Verschachtelte Daten

Jede Ebene wird zuerst als leeres Objekt angelegt, danach gefüllt.

~EJD-CreateNewData(jdat)~

{EJD-DataOK(jdat)}
   ~EJD-DA-SetToEmptyObject(Data,jdat)~
   ~EJD-DA-SetToEmptyObject(Data.Images,jdat)~
   ~EJD-DA-SetStringValue(Data.Images.Image small,img-5678.jpg,jdat)~
   ~EJD-DA-SetStringValue(Data.Images.Image big,img-1234.jpg,jdat)~

   ~EJD-DA-SetToEmptyArray(Data.Crosslinks,jdat)~
   ~EJD-DA-ArrayExtend(Data.Crosslinks,jdat)~
   ~EJD-DA-SetStringValue(Data.Crosslinks[0],A-2256,jdat)~

   ~EJD-RawDataOutput(jdat)~
{/EJD-DataOK(jdat)}

{ "Data": { "Images": { "Image small": "img-5678.jpg", "Image big": "img-1234.jpg" }, "Crosslinks": [ "A-2256" ] } }

Prüfen, ob die Änderung geklappt hat

{EJD-ModificationOK}
   JSON-Daten erfolgreich geändert.
{/EJD-ModificationOK}

{!EJD-ModificationOK}
   Fehler: ~EJD-ModificationOK~
{/!EJD-ModificationOK}

~EJD-ResetModificationOK~

Der Fehlerstand bleibt stehen, auch wenn eine spätere Änderung gelingt. Setzen Sie ihn deshalb mit EJD-ResetModificationOK zurück, sonst prüfen Sie ab der ersten fehlgeschlagenen Änderung immer denselben alten Fehler.

Referenz: EJD-CreateNewData() · EJD-DA-SetStringValue() · EJD-DA-SetNumberValue() · EJD-DA-SetRealValue() · EJD-DA-SetToTrue() · EJD-DA-SetToFalse() · EJD-DA-SetToNull() · EJD-DA-SetToEmptyArray() · EJD-DA-SetToEmptyObject() · EJD-DA-ArrayExtend() · EJD-DA-DeleteElement() · EJD-RawDataOutput() · EJD-ModificationOK · EJD-ResetModificationOK

Daten aus fremden Systemen verarbeiten

Antworten von Zahlungsanbietern, Versanddienstleistern oder vom Shopsystem selbst liegen nicht als Datei vor. Sie kommen im Moment des Aufrufs an und heißen deshalb intern. Bei Dateien wissen Sie, was drinsteht, weil Sie sie selbst hochgeladen haben. Bei internen Daten ist das oft nicht der Fall. EJD-RawDataOutput() gibt deshalb alles aus, was angekommen ist. Das ist der schnellste Weg herauszufinden, womit Sie es zu tun haben.

Schritt 1: Die Daten in die Schnittstelle setzen

<!-- Antwort auf "getOrderDetails" bei Kauf auf Rechnung über PayPal Checkout -->
~EJD-SetRawDataInput($PPC-OrderDetailsRawResponse$)~

<!-- Antwort mit dem Zahlungstoken von Paymorrow -->
~EJD-SetRawDataInput($PAYMORROW-JSONResponseGetPaymentToken$)~

<!-- Antwort der Sendungsverfolgung -->
~EJD-SetRawDataInput($SHIPTRACK-JSONResult$)~

Welche Bezeichnung für Ihren Fall gilt, erfahren Sie vom jeweiligen Dienstleister oder von WEBSALE. Kommen die Daten hexcodiert an, verwenden Sie stattdessen EJD-SetRawDataHexCodedInput().

Schritt 2: Laden und Kennung vergeben

~EJD-SetRawDataInput($XYZ-technischeBezeichnung-JSON$)~

~EJD-LoadData(intern,rawdatainput,jdat)~

~EJD-RawDataOutput(jdat)~

Der zweite Parameter ist bei internen Daten keine Pfadangabe, sondern eine technische Bezeichnung, die vom Anwendungsfall abhängt.

Einige interne Daten kommen direkt vom Shopsystem und brauchen Schritt 1 nicht. Die hreflang-Angaben beispielsweise lassen sich unmittelbar laden:

~EJD-LoadData(intern,hreflang-prod-$PR-ProdIndex$,href)~
~EJD-RawDataOutput(href)~

Alles Weitere, also das Prüfen, der Zugriff auf einzelne Werte und die Ausgabe, läuft wie bei Dateien. Referenz: EJD-SetRawDataInput() · EJD-SetRawDataHexCodedInput() Wegweiser: hreflang-Attribut

​Woher die Daten kommen

​Freischaltung und FTP-Zugang

​Die Ordnerstruktur

​Anforderungen an die Dateien

​Die beiden Tag-Familien

​Daten laden

​Prüfen, ob die Daten angekommen sind

​Auf Werte zugreifen

​Die Kennung einmal setzen

​Werte in anderen Tags weiterverwenden

​Nachkommastellen festlegen

​Elemente prüfen

​Über Elemente laufen

​Eigene JSON-Daten erzeugen

​Einfache Werte

​Arrays

​Verschachtelte Daten

​Prüfen, ob die Änderung geklappt hat

​Daten aus fremden Systemen verarbeiten

​Schritt 1: Die Daten in die Schnittstelle setzen

​Schritt 2: Laden und Kennung vergeben

​Verwandte Themen

Woher die Daten kommen

Freischaltung und FTP-Zugang

Die Ordnerstruktur

Anforderungen an die Dateien

Die beiden Tag-Familien

Daten laden

Prüfen, ob die Daten angekommen sind

Auf Werte zugreifen

Die Kennung einmal setzen

Werte in anderen Tags weiterverwenden

Nachkommastellen festlegen

Elemente prüfen

Über Elemente laufen

Eigene JSON-Daten erzeugen

Einfache Werte

Arrays

Verschachtelte Daten

Prüfen, ob die Änderung geklappt hat

Daten aus fremden Systemen verarbeiten

Schritt 1: Die Daten in die Schnittstelle setzen

Schritt 2: Laden und Kennung vergeben

Verwandte Themen