Anlegen einer Bestellung

Der hier beschriebene Ansatz ermöglicht es eine Bestellung via REST in brandbox anzulegen und entsprechende Session-Artikel mit dieser zu verknüpfen.

Dieser Anwendungsfall setzt Session-Artikel voraus. Diese werden unter anderem in Szenario #1 erzeugt und können mit dieser Vorgehensweise in eine Bestellung umgewandelt werden.

Aufbau des Plugins

Diese Erweiterung nutzt vorhandene Systemteile um eine Bestellung über REST zu erstellen und direkt Session-Artikel in diese Bestellung aufzunehmen.

Konfiguration

Damit auf die Schnittstelle zugegriffen werden kann, muss der Feature-Aufruf shop/order.create für den REST-Server freigegeben werden.

Verwendung

Schritt 1: Authentifizierung an der REST-Schnittstelle

Genauere Informationen können der entsprechenden Dokumentation entnommen werden.

Schritt 2: Übermitteln der Details der Bestellung

Nach einer erfolgreichen Authentifizierung können entsprechende Details einer Bestellung übermittelt werden.

Hierfür werden zwingend Session Artikel IDs benötigt. Diese werden bspw. von einem Editor mit einer Fremdsystem-Referenz übermittelt.

URL	`https://[brandbox System-URL]/rest/v4/request/shop/order/create/`
Method	`POST`
Header	`content-type`	`form-data`, `x-www-form-urlencoded`, etc.
Header	`authorization`	Durch Authentifizierung bereitgestellter Access-Token
Body	`delivery[salutation]`	Persönliche Anrede für Lieferadresse
	`delivery[firstname]`	Vorname für Lieferadresse
	`delivery[lastname]`	Nachname für Lieferadresse
	`delivery[company]`	Optionaler Firmenname für Lieferadresse
	`delivery[street]`	Straßenname für Lieferadresse
	`delivery[houseNumber]`	Hausnummer für Lieferadresse
	`delivery[city]`	Stadt- bzw. Ortsname für Lieferadresse
	`delivery[postcode]`	Postleitzahl für Lieferadresse
	`delivery[country]`	Land der Lieferadresse als ISO 639-1 Code (in Großbuchstaben, bspw. DE)
	`delivery[preferred]`	Bevorzugtes Lieferdatum als UNIX-Zeitstempel
	`invoice[salutation]`	Persönliche Anrede für Rechnungsadresse
	`invoice[firstname]`	Vorname für Rechnungsadresse
	`invoice[lastname]`	Nachname für Rechnungsadresse
	`invoice[company]`	Optionales Firmenname für Rechnungsadresse
	`invoice[street]`	Straßenname für Rechnungsadresse
	`invoice[houseNumber]`	Hausnummer für Rechnungsadresse
	`invoice[city]`	Stadt- bzw. Ortsname für Rechnungsadresse
	`invoice[postcode]`	Postleitzahl für Rechnungsadresse
	`invoice[country]`	Land der Rechnungsadresse als ISO 639-1 Code (in Großbuchstaben, bspw. DE)
	`note`	Optionale Notiz für Bestellung
	`phone`	Optionale Telefonnummer für Bestellung
	`fax`	Optionale Faxnummer für Bestellung
	`vatno`	Optionale Umsatzsteuernummer für Bestellung
	`articles[0]`	Alle Session Artikel IDs für diese Bestellung.
	`articles[1]`
	`articles[2]`
	`articles[3]`
	`articles[...]`
	`quantities[0]`	Die Bestellmengen für die im Parameter `articles[]` übergebenen Artikel. Der Index dieses Parameters ist hierbei analog zu dem Index in `articles[]`.
	`quantities[1]`
	`quantities[2]`
	`quantities[3]`
	`quantities[...]`

brandbox antwortet auf diese Anfrage entweder mit einer Fehlermeldung im Fehlerfall oder einem JSON-Objekt welches die übergebenen Parameter und die Eigenschaft order enthält. Darin ist die eindeutige ID dieser Bestellung enthalten.

Schritt 3 (Optional): Erstellen von Druckdaten einer Bestellung

Befinden sich Druckartikel in einer Bestellung, so können die Druckdaten für eine Bestellung über eine REST-Anfrage generiert werden.

URL	`https://[brandbox System-URL]/rest/v4/request/shop/order/createOrderPrintFiles/`
Method	`POST`
Header	`content-type`	`form-data`, `x-www-form-urlencoded`, etc.
Header	`authorization`	Durch Authentifizierung bereitgestellter Access-Token
Body	`orderID`	Eindeutige ID der Bestellung
Body	`force`	Ist dieser Parameter auf 1 gesetzt, so werden die Druckdaten erneut generiert.

brandbox antwortet auf diese Anfrage entweder mit einer Fehlermeldung im Fehlerfall oder einem JSON-Objekt welches die Eigenschaft files besitzt. Darin befinden sich alle Druckartikel. Als Index wird die entsprechende Session Artikel ID genutzt, als Wert ein Dateischlüssel.

Schritt 4 (Optional): Abrufen einer Druckdatei

Die in Schritt 3 erhalten Dateischlüssel können genutzt werden um die entsprechende Druckdatei abzurufen. Hierzu muss eine GET-Anfrage an brandbox gestellt werden.

URL	`https://[brandbox System-URL]/rest/v4/request/security/download/download/`
Method	`GET`
Header	`content-type`	`form-data`, `x-www-form-urlencoded`, etc.
Header	`authorization`	Durch Authentifizierung bereitgestellter Access-Token
Parameter	`downloadFile`	Der in Schritt 3 erhaltene Dateischlüssel
Parameter	`encrypted`	Dieser Parameter muss auf 1 gesetzt werden. Hierdurch wird angegeben, dass der genutzt Wert in `downloadFile` zunächst entschlüsselt werden muss.

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",
            "v4",
            "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",
            "v4",
            "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 10",
              "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 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"
            }
          ]
        },
        "url": {
          "raw": "https://{{BRANDBOX_URL}}/rest/v4/request/shop/order/create/",
          "protocol": "https",
          "host": [
            "{{BRANDBOX_URL}}"
          ],
          "path": [
            "rest",
            "v4",
            "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",
            "v4",
            "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",
            "v4",
            "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"
    }
  ]
}