Anbindung der Web-to-print Editoren an Fremdsysteme

Durch die Kombination der brandbox REST-Schnittstelle und der w2p-Editoren ist es möglich einen w2p-Editor aus einem Fremdsystem (bspw. einem eigenen Shop) zu öffnen, dem Anwender alle Möglichkeiten eines unterstützten Editors zu bieten und diesen nach Abschluss seiner Gestaltung wieder in das Fremdsystem zurückzubringen.

Aufbau des Plugins

Die Erweiterung ist mit den Editoren Strict, Nested, Mail, XLSX, Upload, H5E und StrictH5E kompatibel. Wird einer dieser Editoren für ein Fremdsystem geöffnet, wird dem Anwender nach der Gestaltung nur die Möglichkeit geboten den gestalteten Artikel in den Warenkorb zu legen. Die Aktion den gestalteten Artikel in den Warenkorb aufzunehmen wird hierbei durch eine Rückleitung des Anwenders in das Fremdsystem ersetzt. Andere, normalerweise verfügbare Aktionen (bspw. den gestalten Artikel in eine Merkliste aufzunehmen) entfallen hierbei.

Ein über diesen Weg gestalteter Artikel unterliegt ggf. der sog. Garbage Collection und kann daher nach einer definierten Zeit eventuell nicht mehr vorhanden sein.

Konfiguration

Die Verwendung dieser Schnittstelle setzt einsatzbereite REST- und oAuth2-Server voraus.

Damit ein Fremdsystem eine w2p-Editoren URL anfordern kann, muss der verwendete Rest-User eine Rolle mit dem Schema "W2p Editoren" haben.

Artikel

Es können nur w2p-Editoren-URLs für Artikel angefragt werden, welche über eine SKU verfügen.

Es wird bei Anforderung einer URL für einen Editor immer die erste Artikelvorlage des entsprechenden Artikels genutzt.

Account für Schnittstellen-Authentifizierung

Ein Fremdsystem kann nur dann eine Editoren-URL für einen Artikel anfordern, wenn dieses bei brandbox authentifiziert ist. Hierzu wird ein Anwender benötigt welcher über entsprechende Zugriffsrechte verfügt. Folgende Schemas werden empfohlen:

W2p Editoren (W2pEditorDefaultScheme)
W2p Editoren Persönliche Daten (W2pEditorTokenScheme)
Shop alle Artikel und Gruppen (FullCatalogueScheme)
Shop alle Vorlagen (FullTemplateScheme)

Um die Schnittstelle auf einzelne Artikel und Vorlagen einzuschränken, können auch eigene Schemas definiert werden.

Verwendung

Schritt 1: Authentifizierung des Fremdsystems bei brandbox

Weitere Informationen in entsprechender Dokumentation.

Schritt 2: Anfordern einer Editoren-URL für einen Artikel

Die Kommunikation mit brandbox findet bei dieser Anfrage über ein POST-HTTP-Request statt.

URL	`https://[brandbox System-URL]/rest/v4/request/editor/base/getEditorUrl`
Method	`POST`
Header	`content-type`	`form-data`, `x-www-form-urlencoded`, etc.
Header	`authorization`	Durch Authentifizierung bereitgestellter Access-Token
Body	`sku`	Eindeutige SKU des gewünschten Artikels
	`returnUrl`	Vollständige URL an die nach Abschluss der Gestaltung im Editor zurückgekehrt werden soll
	`sessionArticleID`	Dieser Parameter ist optional und darf nur mit einer gültigen Session-Artikel-ID genutzt werden. Die eindeutige Session-Artikel-ID welche bereits in einem Editor benutzt wurde. Somit kann eine bereits vorgenommene Gestaltung erneut aufgerufen werden.

Als Antwort sendet brandbox entweder eine entsprechende Fehlermeldung im Fehlerfall oder die Editoren-URL für den geforderten Artikel. Gibt es keinen Fehler kann die Editoren-URL aus der body-Eigenschaft der JSON-Antwort gelesen werden.

Eine Antwort über die REST-Schnittstelle von brandbox wird in einem entsprechende Antwortformat als JSON geliefert.

Schritt 3: Anwender zu brandbox Editor führen

Die in Schritt 2 gelieferte URL muss genutzt werden um den Anwender in brandbox zu führen. brandbox erzeugt nun selbständig eine entsprechende Gastsession für den Anwender und stellt den angeforderten Editor für die jeweiligen Artikel bereit.

Die gelieferte URL darf nicht verändert und/oder erweitert werden. Über die returnUrl können zusätzliche Informationen für das Fremdsystem hinterlegt werden.

Schritt 4: Zurückkehrenden Anwender empfangen

Hat der Anwender seine Gestaltung und Datenpflege im Editor abgeschlossen und möchte den Artikel in seinen Warenkorb aufnehmen, wird dieser an die im returnUrl-Parameter bereitgestellt URL weitergeleitet.

brandbox startet einen POST-HTTP-Request durch den Anwender an die in returnUrl definierte URL und sendet den POST-Parameter sessionArticleID mit der eindeutigen ID der Gestaltung des Anwenders mit. Die gelieferte ID muss im Fremdsystem entsprechend für den Anwender gespeichert werden.

Beispiel

Mithilfe des kostenlosen Tools Postman (https://www.screencast.com/t/sOLSb6HfW19) kann dieses Szenario durchgespielt werden.

Das hier genutzte Beispiel ist eine Kombination aus zwei Szenarien für die REST-Schnittstelle. Zum einen wird ein Editor über die Schnittstelle angefragt und zum anderen eine Bestellung daraus erzeugt.

Postman

{
  "info": {
    "_postman_id": "5d765220-96a6-4a6b-a22a-a1309485599a",
    "name": "W2P Editoren für Fremdsysteme",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Request Access Token",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "a3be4ff2-f37c-48dc-aefa-c132816d3db6",
            "exec": [
              "pm.globals.set('BRANDBOX_ACCESS_TOKEN', pm.response.json().body.access_token);"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "POST",
        "header": [],
        "body": {
          "mode": "formdata",
          "formdata": [
            {
              "key": "grant_type",
              "value": "password",
              "type": "text"
            },
            {
              "key": "client_id",
              "value": "{{BRANDBOX_CLIENT_ID}}",
              "type": "text"
            },
            {
              "key": "client_secret",
              "value": "{{BRANDBOX_CLIENT_SECRET}}",
              "type": "text"
            },
            {
              "key": "username",
              "value": "{{BRANDBOX_USERNAME}}",
              "type": "text"
            },
            {
              "key": "password",
              "value": "{{BRANDBOX_PASSWORD}}",
              "type": "text"
            }
          ]
        },
        "url": {
          "raw": "https://{{BRANDBOX_URL}}/rest/v4/accessToken",
          "protocol": "https",
          "host": [
            "{{BRANDBOX_URL}}"
          ],
          "path": [
            "rest",
            "v3",
            "accessToken"
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get Editor URL",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "{{BRANDBOX_ACCESS_TOKEN}}",
            "type": "text"
          }
        ],
        "body": {
          "mode": "formdata",
          "formdata": [
            {
              "key": "sku",
              "value": "EDIT-STRICT-001",
              "type": "text"
            },
            {
              "key": "returnUrl",
              "value": "https://www.shopware.com/de/",
              "type": "text"
            }
          ]
        },
        "url": {
          "raw": "https://{{BRANDBOX_URL}}/rest/v4/request/editor/base/getEditorUrl",
          "protocol": "https",
          "host": [
            "{{BRANDBOX_URL}}"
          ],
          "path": [
            "rest",
            "v3",
            "request",
            "editor",
            "base",
            "getEditorUrl",
            ""
          ]
        }
      },
      "response": []
    },
    {
      "name": "Generate Order",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "13e70225-76b0-46ec-a427-00c0c64b082b",
            "exec": [
              "pm.globals.set('BRANDBOX_ORDER_ID', pm.response.json().body.order);"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "type": "text",
            "value": "{{BRANDBOX_ACCESS_TOKEN}}"
          }
        ],
        "body": {
          "mode": "formdata",
          "formdata": [
            {
              "key": "delivery[salutation]",
              "value": "Herr",
              "type": "text"
            },
            {
              "key": "delivery[firstname]",
              "value": "Max",
              "type": "text"
            },
            {
              "key": "delivery[lastname]",
              "value": "Mustermann",
              "type": "text"
            },
            {
              "key": "delivery[company]",
              "value": "Konmedia GmbH",
              "type": "text"
            },
            {
              "key": "delivery[street]",
              "value": "Gartenstraße",
              "type": "text"
            },
			{
			  "key": "delivery[houseNumber]", 
			  "value": "Gartenstraße", 
              "type": "text" 
			},
            {
              "key": "delivery[city]",
              "value": "Bühl",
              "type": "text"
            },
            {
              "key": "delivery[postcode]",
              "value": "77815",
              "type": "text"
            },
            {
              "key": "delivery[country]",
              "value": "DE",
              "type": "text"
            },
            {
              "key": "delivery[preferred]",
              "value": "0",
              "type": "text"
            },
            {
              "key": "invoice[salutation]",
              "value": "Frau",
              "type": "text"
            },
            {
              "key": "invoice[firstname]",
              "value": "Maria",
              "type": "text"
            },
            {
              "key": "invoice[lastname]",
              "value": "Musterfrau",
              "type": "text"
            },
            {
              "key": "invoice[company]",
              "value": "Konmedia GmbH",
              "type": "text"
            },
            {
              "key": "invoice[street]",
              "value": "Gartenstraße",
              "type": "text"
            },
			{
			  "key": "invoice[houseNumber]", 
			  "value": "10", 
			  "type": "text"
			},
            {
              "key": "invoice[city]",
              "value": "Bühl",
              "type": "text"
            },
            {
              "key": "invoice[postcode]",
              "value": "77815",
              "type": "text"
            },
            {
              "key": "invoice[country]",
              "value": "DE",
              "type": "text"
            },
            {
              "key": "note",
              "value": "Dies ist eine Notiz dieser Bestellung",
              "type": "text"
            },
            {
              "key": "phone",
              "value": "07223 95166 0",
              "type": "text"
            },
            {
              "key": "fax",
              "value": "07223 95166 20",
              "type": "text"
            },
            {
              "key": "vatno",
              "value": "",
              "type": "text"
            },
            {
              "key": "articles[0]",
              "value": "1",
              "type": "text"
            },
			{
			  "key": "quantities[0]", 
			  "value": "1", 
			  "type": "text"
			}
          ]
        },
        "url": {
          "raw": "https://{{BRANDBOX_URL}}/rest/v4/request/shop/order/create",
          "protocol": "https",
          "host": [
            "{{BRANDBOX_URL}}"
          ],
          "path": [
            "rest",
            "v3",
            "request",
            "shop",
            "order",
            "create",
            ""
          ]
        }
      },
      "response": []
    },
    {
      "name": "Generate Print Files",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "be7a087d-8ba8-4115-8e72-3b13ab03d44d",
            "exec": [
              "var path = '';",
              "",
              "for(var id in pm.response.json().body.files) {",
              "    if(pm.response.json().body.files.hasOwnProperty(id)) {",
              "        path = pm.response.json().body.files[id];",
              "        break;",
              "    }",
              "}",
              "",
              "pm.globals.set('BRANDBOX_FIRST_PRINT_PRINT_FILE', path);"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "type": "text",
            "value": "{{BRANDBOX_ACCESS_TOKEN}}"
          }
        ],
        "body": {
          "mode": "formdata",
          "formdata": [
            {
              "key": "orderID",
              "value": "{{BRANDBOX_ORDER_ID}}",
              "type": "text"
            },
            {
              "key": "force",
              "value": "0",
              "type": "text"
            }
          ]
        },
        "url": {
          "raw": "https://{{BRANDBOX_URL}}/rest/v4/request/shop/order/createOrderPrintFiles",
          "protocol": "https",
          "host": [
            "{{BRANDBOX_URL}}"
          ],
          "path": [
            "rest",
            "v3",
            "request",
            "shop",
            "order",
            "createOrderPrintFiles",
            ""
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get First Print File",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "type": "text",
            "value": "{{BRANDBOX_ACCESS_TOKEN}}"
          }
        ],
        "url": {
          "raw": "https://{{BRANDBOX_URL}}/rest/v4/request/security/download/download/?downloadFile={{BRANDBOX_FIRST_PRINT_PRINT_FILE}}&encrypted=1",
          "protocol": "https",
          "host": [
            "{{BRANDBOX_URL}}"
          ],
          "path": [
            "rest",
            "v3",
            "request",
            "security",
            "download",
            "download",
            ""
          ],
          "query": [
            {
              "key": "downloadFile",
              "value": "{{BRANDBOX_FIRST_PRINT_PRINT_FILE}}"
            },
            {
              "key": "encrypted",
              "value": "1"
            }
          ]
        }
      },
      "response": []
    }
  ],
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "id": "3e81acde-0200-4acc-a6d9-52a3a70a0ee2",
        "type": "text/javascript",
        "exec": [
          ""
        ]
      }
    },
    {
      "listen": "test",
      "script": {
        "id": "2ae9c70d-d0ff-4383-ab63-90eff6874f0a",
        "type": "text/javascript",
        "exec": [
          ""
        ]
      }
    }
  ],
  "variable": [
    {
      "id": "ee358d4f-0f96-44e1-984a-41fc37f13bd8",
      "key": "BRANDBOX_URL",
      "value": "demo-v54.stage.brandbox.de",
      "type": "string"
    },
    {
      "id": "be3defc9-daa0-43a0-ab90-52d28972cc3a",
      "key": "BRANDBOX_CLIENT_ID",
      "value": "1",
      "type": "string"
    },
    {
      "id": "c2964250-7d64-4e75-90d1-93843f2f41d0",
      "key": "BRANDBOX_CLIENT_SECRET",
      "value": "secret",
      "type": "string"
    },
    {
      "id": "d914b739-d746-4b85-b9d8-62c8cac1f9e8",
      "key": "BRANDBOX_USERNAME",
      "value": "",
      "type": "string"
    },
    {
      "id": "87fa701f-aacc-4353-8e0c-ccf6bb8cbae8",
      "key": "BRANDBOX_PASSWORD",
      "value": "",
      "type": "string"
    }
  ]
}