Daten mit externen Systemen austauschen

Neben den Inhalten, die von außen in den Shop kommen, gibt es den umgekehrten Weg und einen Sonderfall dazwischen. Diese Seite behandelt beide Richtungen und das Format, in dem Zahlen die Systemgrenze überqueren sollten.

Aufgabe	Werkzeug	Wartet der Shop?
Daten an ein fremdes System senden	ASSE	nein
Produktdaten von einem fremden System holen	RPDE	ja
Preise und Mengen maschinenlesbar ausgeben	technische Tags	entfällt

Daten senden: ASSE

Asynchronous-Server-Side-Events, kurz ASSE, übermittelt beliebige Daten aus dem Shop per HTTPS an fremde Systeme. Das Format ist frei, üblich sind JSON und XML. Typische Einsätze sind Bestelldaten, Newsletter-Anmeldungen und Tracking-Ereignisse. Entscheidend ist das Wort asynchron: Die Daten gehen vom Shop-Server zum Empfänger, nicht über den Browser des Besuchers. Der Seitenaufbau wartet nicht auf die Antwort. Antwortet die Gegenstelle gar nicht, merkt der Besucher davon nichts.

Eigenschaft	Möglichkeiten
Ziel	eine oder mehrere Adressen, ausschließlich über HTTPS
Übertragungsart	POST, GET oder PUT
Datenformat	frei, üblich sind JSON und XML
Zusätzliche Angaben	eigener Parametername und zusätzliche Angaben im HTTP-Header
Fehlerbehandlung	mehrere Zustellversuche, dazu eine Zeitspanne für die Antwort

Fehler bei der Übermittlung sind weder im Shop noch im Online-Servicebereich sichtbar, gerade weil die Übertragung asynchron läuft. Scheitern alle Zustellversuche, landen die Daten in einem Fehlerverzeichnis, und die WEBSALE-Systemüberwachung meldet sich bei Ihrem Shop-Administrator.

Schritt 1: Freischaltung

ASSE muss freigeschaltet werden, global oder je Subshop. Wenden Sie sich an Ihren WEBSALE Ansprechpartner.

Schritt 2: Die Übertragung konfigurieren

Jede Übertragung bekommt einen eigenen <+Entry> im Abschnitt <ASSE> der shop.config.

<ASSE>
   <+Entry>
      ID              = shopconfirm
      Endpoint        = https://api.shop.de/shop-certification/v2/order/log
      Type            = POST
      ContentType     = application/json
      ServiceCategory = OrderNotification
   </+Entry>
</ASSE>

Parameter	Bedeutung
`ID`	eindeutige Bezeichnung, mit der die Übertragung im Template ausgelöst wird
`Endpoint`	Adresse des Empfängers, WEBSALE-Tags sind hier erlaubt
`Type`	`POST`, `GET` oder `PUT`
`ContentType`	Format der gesendeten Daten, beispielsweise `application/json`
`ServiceCategory`	`Tracking` oder `OrderNotification`, dahinter stehen die von WEBSALE vorgegebenen Werte für Zeitspanne und Zustellversuche

Den Wert für ContentType bestimmt der Empfänger. Tragen Sie genau das ein, was dessen Dokumentation verlangt.

Wann eine Zustellung als erfolgreich gilt

Ohne weitere Angabe gilt jede Antwort als Erfolg. Über <DefinitionOfOK> legen Sie fest, was wirklich zählt. Mehrere Bedingungen werden mit UND verknüpft, es müssen also alle erfüllt sein.

<ASSE>
   <+Entry>
      ...
      <DefinitionOfOK>
         <+ConditionGroup>
            <+Condition>
               Proof        = HTTP-StatusCode
               DataSelector =
               Type         = value
               Value        = 200
            </+Condition>
         </+ConditionGroup>
      </DefinitionOfOK>
   </+Entry>
</ASSE>

Wert für `Proof`	Geprüft wird
`HTTP-StatusCode`	der Statuscode der Antwort, beispielsweise `200`
`ContentType`	das Format der Antwort
`ResponsePlain`	der Antworttext selbst, beispielsweise `OK`
`ResponseJSON`	ob die Antwort überhaupt als JSON lesbar ist
`ResponseJSONData`	ein bestimmtes Datenfeld der Antwort, ausgewählt über `DataSelector`

Ist die Bedingung erfüllt, gilt die Zustellung als erledigt und es folgen keine weiteren Versuche.

Zusätzliche Angaben im HTTP-Header

<ASSE>
   <+Entry>
      ...
      <AdditionalHeaders>
         <+HttpHeader>
            Name  =
            Value =
         </+HttpHeader>
      </AdditionalHeaders>
   </+Entry>
</ASSE>

Referenz: Abschnitt ASSE

Schritt 3: Zugangsdaten sicher ablegen

Gehört ein Schlüssel oder Passwort in die Daten, schreiben Sie es nicht ins Template. Im Abschnitt <FreeMessages-Txt> abgelegt, steht es nicht im Klartext in den Bearbeitungs-Templates auf dem Server.

<FreeMessages-Txt>
   MyApiKey = abcdef12345
</FreeMessages-Txt>

Im Template holen Sie den Wert über das zugehörige Tag, hier ~FMSG-MyApiKey~. Referenz: Abschnitt FreeMessages-Txt Wegweiser: Freie Standardtexte definieren

Schritt 4: Die Daten zusammenstellen und senden

Ausgelöst wird die Übertragung mit ASSE-Fire(). Das Tag nimmt zwei Angaben: die Kennung aus der Konfiguration und die zu sendenden Daten. Das folgende Beispiel stellt auf der Bestelleingangsbestätigung die Bestelldaten zusammen und sendet sie.

~DC-FPFireJSON_set({"apiKey": "$FMSG-MyApiKey$", "email": "$A-E-Mail$", )~
~DC-FPFireJSON_append("orderId": "$WS-OrderID$", "productItemIds": )~

{BASKET-PR-Data}
   ~DC-Int1_set(0)~
   ~DC-FPFireJSON_append([
      {@BASKET-PR-Data}
         $DC-Int1_add(1)${!DC-Int1(1)},{/!DC-Int1(1)}"$BASKET-PR-Number$"
      {/@BASKET-PR-Data}
   ]})~
{/BASKET-PR-Data}

~ASSE-Fire(shopconfirm,$WS-DisableXSSProtectionOnce$$DC-FPFireJSON$)~

Innerhalb eines Tag-Arguments werden andere Tags mit Dollar-Zeichen geschrieben, nicht mit Tilde. $FMSG-MyApiKey$ gehört also in den Aufbau der Daten, ~FMSG-MyApiKey~ würde dort nicht ersetzt.

Der Zähler in der Schleife setzt das Komma zwischen den Einträgen, aber nicht vor dem ersten. Heraus kommt:

{
   "apiKey": "abcdef12345",
   "email": "kunde@example.de",
   "orderId": "20250042",
   "productItemIds": ["4711", "4712"]
}

Statt die Daten mit DC-FPX_append zusammenzusetzen, lassen sie sich auch über die JSON-Schnittstelle erzeugen. Bei verschachtelten Daten ist das der übersichtlichere Weg.

Fehler beim Auslösen erkennen

Konfigurationsfehler beim Erzeugen des Ereignisses meldet ein eigenes Tag. Es gehört während der Einrichtung unter den Code, der die Übertragung auslöst.

{ASSE-LastErrorCode}
   Errorcode des aufgetretenen Fehlers: ~ASSE-LastErrorCode~
{/ASSE-LastErrorCode}

Zum Prüfen der gesendeten Daten eignen sich Dienste, die eine Adresse zum Empfangen bereitstellen und das Empfangene anzeigen, beispielsweise webhook.site. Die Antwort der echten Gegenstelle prüfen Sie mit einem Werkzeug wie reqbin.com. Referenz: ASSE-Fire() · ASSE-LastErrorCode · Frei verwendbare DesignControl-Tags DC-FPX · DC-FPX_set() · DC-FPX_append Anwendungsbeispiele: ASSE

Produktdaten holen: RPDE

RPDE steht für RemoteProductDataEnrichment. Damit fragt der Shop technische Produktdatenfelder während des Seitenaufbaus bei einem fremden System ab und verwendet sie sofort. Vorhandene Felder lassen sich dabei anreichern oder überschreiben. Die Daten liegen nicht bei WEBSALE, sondern kommen über eine gesicherte Verbindung von Server zu Server. Typische Fälle sind tagesaktuelle Preise oder Werte, die sich erst aus der Eingabe des Kunden ergeben.

Für RPDE gelten enge Grenzen:

Je angezeigter Seite ist genau eine Abfrage möglich, auch auf Suchergebnislisten.
Das Produkt muss vollständig aufgelöst sein, alle abhängigen Varianten müssen also gewählt sein.
Bei Set-Produkten steht die Funktion nur für das Oberprodukt zur Verfügung, und dieses muss in den Produktdaten entsprechend gekennzeichnet sein.
Zusammen mit dem Cookiewarenkorb oder dem Bestellgenerator ist RPDE nicht nutzbar.
Neben anderen externen Dienstleistern wie W2P kann die Funktion nicht gewährleistet werden.

Die Übergabe an das fremde System stellen Sie im Template frei zusammen. Die Antwort wird im JSON-Format erwartet und über die JSON-Schnittstelle gelesen.

Beispiel: Labelprint24

Labelprint24 druckt Verpackungen nach Maß. Der Kunde gibt Länge, Breite und Höhe ein, der Shop schickt diese Werte zusammen mit den Basisdaten des Produkts hin, und Labelprint24 prüft, ob sich das so fertigen lässt, und liefert Preis und Gewicht zurück. Beides landet in den Produktdaten. Ein Vertrag mit Labelprint24 ist Voraussetzung, und die Anbindung muss von WEBSALE eingerichtet werden.

Schritt 1: Produktdaten kennzeichnen

Die betroffenen Produkte werden in den Produktdaten gekennzeichnet.

Schritt 2: Fehlermeldung ergänzen

<NotifyMessages-Txt>
   ...
   RPDE_Labelprint-BasketError = Das Produkt konnte nicht in den Warenkorb gelegt werden. Bitte versuchen Sie es erneut oder kontaktieren Sie uns.
   ...
</NotifyMessages-Txt>

Schritt 3: Template zuweisen

<Templates>
   ...
   RPDE_Labelprint = extern_labelprint.json
   ...
</Templates>

Schritt 4: Das Übergabe-Template anlegen

Legen Sie das Template unter dem zugewiesenen Namen in Ihrem Template-Verzeichnis an.

{
   "action": "get_product_price",
   "token": "~WS-RPDE_Labelprint_token~",
   "language": "de-AT",
   "currency": "~WS-Currency~",
   "product": {
      "id": "~PR-Index~",
      "deeplink": "~PR-SetLink~",
      "height": ~PR-RPDE_Labelprint_height(1)~,
      "width": ~PR-RPDE_Labelprint_width(1)~,
      "length": ~PR-RPDE_Labelprint_length(1)~,
      "quantity": ~PR-Quantity~
   }
}

Welche Angaben das Template enthalten muss, bestimmt Labelprint24. Stimmen Sie den Inhalt dort ab, bevor Sie testen.

Schritt 5: Eingabefelder auf der Produktdetailansicht

RPDE: ~PR-RPDE~<br>
{PR-RPDE_Labelprint_width_input}
   Breite: <input type="text" name="~PR-RPDE_Labelprint_width_input~" value="~PR-RPDE_Labelprint_width(2)~" onBlur="SubmitSelection()">
   Länge:  <input type="text" name="~PR-RPDE_Labelprint_length_input~" value="~PR-RPDE_Labelprint_length(2)~" onBlur="SubmitSelection()">
   Höhe:   <input type="text" name="~PR-RPDE_Labelprint_height_input~" value="~PR-RPDE_Labelprint_height(2)~" onBlur="SubmitSelection()">

   {PR-RPDE_OK}Abfrage erfolgreich{/PR-RPDE_OK}
   {!PR-RPDE_OK}Abfrage nicht erfolgreich{/!PR-RPDE_OK}
{/PR-RPDE_Labelprint_width_input}

Empfehlenswert ist ein Nachladen per AJAX beim Verlassen des Feldes, wie im Beispiel über onBlur. Sonst erfährt der Kunde erst nach dem Absenden, ob seine Maße herstellbar sind. Länge, Breite und Höhe lassen sich nicht vorbelegen, und der Shop prüft sie serverseitig nicht. Die Prüfung übernimmt allein das fremde System.

Schritt 6: Anzeige im Warenkorb

RPDE: ~BASKET-PR-RPDE~<br>
{BASKET-PR-RPDE_Labelprint_width_input}
   Breite: ~BASKET-PR-RPDE_Labelprint_width~
   Länge:  ~BASKET-PR-RPDE_Labelprint_length~
   Höhe:   ~BASKET-PR-RPDE_Labelprint_height~
{/BASKET-PR-RPDE_Labelprint_width_input}

Fehler suchen

Meldungen der Schnittstelle geben Sie zu Prüfzwecken über MSG-InternalErrorMessage aus. Für den Blick auf die tatsächlich gesendeten und empfangenen Daten gibt es zwei weitere Tags. Referenz: MSG-InternalErrorMessage · PR-RPDE · PR-RPDE_OK · PR-RPDE_Data · BASKET-PR-RPDE_Data · WS-RPDE_DebugInfo_RequestData · WS-RPDE_DebugInfo_ResponseData Referenz: WS-RPDE_Labelprint_token · PR-RPDE_Labelprint_width · PR-RPDE_Labelprint_length · PR-RPDE_Labelprint_height

Preise maschinenlesbar übergeben

Preise, die im Shop stehen, sind für Menschen formatiert: mit Tausenderpunkt, Komma und Währungszeichen. Ein fremdes System kann damit nichts anfangen. Für die Übergabe gibt es deshalb zu allen Beträgen und Mengen ein technisches Gegenstück. Ohne zusätzliche Angabe werden diese Tags ohne Tausendertrennzeichen, mit Punkt als Dezimaltrenner und mit zwei Nachkommastellen ausgegeben.

Tag	Inhalt
`BASKET-PR-TechnicalPrice`	Preis je Produkt einer Warenkorbposition
`BASKET-PR-TechnicalSum`	Gesamtsumme einer Warenkorbposition
`BASKET-PR-TechnicalSetPrice`	Einzelpreis eines Sets im Warenkorb
`BASKET-PR-TechnicalSetSum`	Gesamtpreis eines Sets im Warenkorb
`BASKET-PR-TechnicalQuantity`	Menge einer Warenkorbposition
`BASKET-TechnicalValueOfGoods`	reiner Warenwert ohne Rabatte
`BASKET-TechnicalSubTotalSum`	Warenwert mit Rabatten, brutto oder netto wie im Shop definiert
`BASKET-TechnicalSubTotalGross`	Bruttowarenwert mit Rabatten, bei Nettopreisen
`BASKET-TechnicalSubTotalNet`	Nettowarenwert mit Rabatten, bei Bruttopreisen
`BASKET-TechnicalSubTotalVAT`	Mehrwertsteuer des Warenwerts
`BASKET-TechnicalDeliveryCost`	Versandkosten
`BASKET-TechnicalPaymentCost`	Gebühr der gewählten Zahlungsart
`BASKET-TechnicalOrderTotal`	Gesamtsumme

Das Format anpassen

Alle Tags nehmen bis zu drei durch Komma getrennte Angaben:

Stelle	Bedeutung	Vorgabe
1	Dezimaltrennzeichen	`.`
2	Anzahl der Nachkommastellen	`2`
3	Multiplikator	`1`

Bei einem Wert von 12,99 ergibt sich:

Schreibweise	Ergebnis
`~BASKET-TechnicalOrderTotal~`	`12.99`
`~BASKET-TechnicalOrderTotal(\,)~`	`12,99`
`~BASKET-TechnicalOrderTotal(#)~`	`12#99`
`~BASKET-TechnicalOrderTotal(,4)~`	`12.9900`
`~BASKET-TechnicalOrderTotal(,,2)~`	`25.98`
`~BASKET-TechnicalOrderTotal(,0,100)~`	`1299`
`~BASKET-TechnicalOrderTotal(\,,2,100)~`	`1299,00`

Ein Komma als Dezimaltrennzeichen muss als \, geschrieben werden. Unmaskiert trennt es die Angaben voneinander, und der Shop liest es als leere erste Angabe.

Eine leere Stelle bedeutet “Vorgabe beibehalten”. (,0,100) lässt also den Dezimaltrenner unverändert, setzt null Nachkommastellen und multipliziert mit 100. Das ist die übliche Form für Systeme, die Beträge in Cent erwarten. Wegweiser: Warenkorb anzeigen

​Daten senden: ASSE

​Schritt 1: Freischaltung

​Schritt 2: Die Übertragung konfigurieren

​Wann eine Zustellung als erfolgreich gilt

​Zusätzliche Angaben im HTTP-Header

​Schritt 3: Zugangsdaten sicher ablegen

​Schritt 4: Die Daten zusammenstellen und senden

​Fehler beim Auslösen erkennen

​Produktdaten holen: RPDE

​Beispiel: Labelprint24

​Schritt 1: Produktdaten kennzeichnen

​Schritt 2: Fehlermeldung ergänzen

​Schritt 3: Template zuweisen

​Schritt 4: Das Übergabe-Template anlegen

​Schritt 5: Eingabefelder auf der Produktdetailansicht

​Schritt 6: Anzeige im Warenkorb

​Fehler suchen

​Preise maschinenlesbar übergeben

​Das Format anpassen

​Verwandte Themen

Daten senden: ASSE

Schritt 1: Freischaltung

Schritt 2: Die Übertragung konfigurieren

Wann eine Zustellung als erfolgreich gilt

Zusätzliche Angaben im HTTP-Header

Schritt 3: Zugangsdaten sicher ablegen

Schritt 4: Die Daten zusammenstellen und senden

Fehler beim Auslösen erkennen

Produktdaten holen: RPDE

Beispiel: Labelprint24

Schritt 1: Produktdaten kennzeichnen

Schritt 2: Fehlermeldung ergänzen

Schritt 3: Template zuweisen

Schritt 4: Das Übergabe-Template anlegen

Schritt 5: Eingabefelder auf der Produktdetailansicht

Schritt 6: Anzeige im Warenkorb

Fehler suchen

Preise maschinenlesbar übergeben

Das Format anpassen

Verwandte Themen