Billbee API zur Anbindung eines eigenen Webshops

Dieses Dokument beschreibt eine Programmierschnittstelle zum Übertragen von Bestell-, Kunden- und Produktdaten zwischen einem Webshop / Marktplatz und der Multichannel Verkäufersoftware www.billbee.io. Die Schnittstelle darf nicht ohne Genehmigung der Billbee GmbH verwendet werden.

Datenformate und Protokoll

Die Übertragung zwischen Shop und Billbee erfolgt über das HTTP / HTTPS Protokoll. Die Daten selber werden im JSON Format übertragen. Für manche Implementationen ist es erforderlich, den Content Type "application/x-www-form-urlencoded" zu aktivieren, damit der Body verarbeitet werden kann. Grundsätzlich agiert Billbee dabei also als Client, der HTTPS Aufrufe an den Webserver des Shops sendet. Es gibt aber auch Ausnahmen, wo der Shop als Client agiert und Methoden des Billbee Webservers aufruft. 

Lesende Zugriffen werden per HTTP GET mit Parametern in der URL ausgeführt, schreibende Zugriffe werden per HTTP POST ausgeführt. Die URL, die beim Webshop aufgerufen wird, kann bei Billbee konfiguriert werden. An diese URL werden Parameter angehängt, die die Methode und weitere Parameter spezifizieren. Die Basisurl kann z.B. https://www.meinshop.de/billbee_api lauten. 

Die aufgerufene Methode wird in dem Parameter Action kodiert. Die konkrete URL zur Abfrage von neuen Bestellungen sieht dann z.B. so aus: https://www.meinshop.de/billbee_api?Action=GetOrders&Key=abf24b12c3b2a4e4b4dabbdd

SDK zur einfachen Integration

Für PHP bieten wir ein SDK an, mit welchen die Integration sehr einfach gestaltet ist. Du findest das Paket hier und kannst es mit composer einfach installieren: https://github.com/billbeeio/custom-shop-php-sdk.

Sicherung der Übertragung über HTTP Basic Authentification

Bei Billbee kann Benutzername und Passwort hinterlegt werden, die per HTTP Basic Auth an den Server gesendet und dort überprüft werden können. Die Überprüfung obliegt dem Shop und ist damit aus Sicht von Billbee nicht obligatorisch. 

Zusätzlich wird ein aktueller Zeitstempel zusammen mit einem API Key verschlüsselt und als Parameter Key an den Server übertragen, um Replay Attacken zu verhindern. Die Prüfung des korrekten Keys obliegt dem Shop und ist damit auch optional. 

Um eine sichere Übertragung zu gewährleisten, muss die Verbindung über HTTPS stattfinden. Auch das liegt in der Verantwortung des Shopbetreibers und ist technisch gesehen keine Voraussetzung für den Betrieb der Schnittstelle.

Der Parameter Key wird wie folgt berechnet (PHP Beispiel):

// Aktuelle Zeit als Unix Timestamp und davon die ersten 7 Ziffern

                    $unixtimestamp = substr(time(), 0, 7);

                    // API Passwort, kann beliebig festgelegt werden

                    $pwd = "APIKEY";

                    // strings werden UTF8 kodiert

                    // API Passwort wird mit Algorithmus SHA256 und dem Key Timestamp verschlüsselt

                    $hash = hash_hmac( "sha256", utf8_encode($pwd), utf8_encode($unixtimestamp));

                    // Das Ergebnis wird BASE64 kodiert

                    $bsec = base64_encode($hash);

                    // HTML spezifische Zeichen werden entfernt

                    $bsec = str_replace("=","",$bsec);

                    $bsec = str_replace("/","",$bsec);

                    $bsec = str_replace("+","",$bsec);

                    echo $bsec;

Rückgabecodes

Für die Rückmeldung von Erfolg oder Fehlern werden die HTTP Statuscodes verwendet:

Minimale Implementierung

Es müssen nicht alle Methoden implementiert werden, um eine funktionierende Datenübertragung zu etablieren. Dieses Kapitel beschreibt die notwendige Minimalkonfiguration.

• Sicherung der Übertragung ist optional
• Die Methode GetOrders muss implementiert werden

GetOrders - Abrufen von neuen und geänderten Bestellungen

Billbee ruft regelmäßig neue Bestellungen des Shops ab. Dazu muss der Shop die Methode GetOrders  implementieren. 

Dem Aufruf wird der Parameter StartDate im Format YYYY-MM-DD mitgeliefert. Der Shop soll nur die Bestellungen zurückliefern, die seit diesem Datum erstellt oder geändert wurden. 

Optional kann der Shop auch durch ein Flag eine Bestellung intern markieren, wenn sie bereits an Billbee übergeben wurde, um so die Datenmenge auf das Nötigste zu reduzieren. Dann ist es erforderlich, auch die Methode AckOrder zu implementieren, über die Billbee den korrekten Empfang einer Bestellung bestätigt. Die Methode muss Paging unterstützen, um auch größere Datenmengen übertragen zu können.

Request

URL: http://shop/billbee_api?Action=GetOrders&StartDate=2013-11 -28&Page=1&PageSize=100&Key=... Methode: GET

Response

Der Shopserver muss mit HTTP 200 antworten, wenn der Request in Ordnung ist und liefert neue und geänderte Bestellungen als JSON Objekt im folgenden Format:

{
                      "paging": {
                        "page": 1,
                        "totalCount": 1,
                        "totalPages": 1
                      },
                      "orders": [
                        {
                          "order_id": "Bestell Id",
                          "order_number": "Bestell Nummer",
                          "currency_code": "EUR",
                          "nick_name": "MaxMustermann",
                          "ship_cost": 2.99,
                          "invoice_address": {
                            "firstname": "Max",
                            "lastname": "Mustermann",
                            "street": "Musterstraße",
                            "housenumber": "1",
                            "address2": "Hinterm Haus",
                            "postcode": "12345",
                            "city": "Musterhausen",
                            "country_code": "DE",
                            "company": "Musterfirma",
                            "state": "NRW"
                          },
                          "delivery_address": {
                            "firstname": "Max",
                            "lastname": "Mustermann",
                            "street": "Musterstraße",
                            "housenumber": "1",
                            "address2": "Hinterm Haus",
                            "postcode": "12345",
                            "city": "Musterhausen",
                            "country_code": "DE",
                            "company": "Musterfirma",
                            "state": "NRW"
                          },
                          "order_date": "2019-08-20T08:24:00",
                          "email": "max@mustermann.tld",
                          "phone1": "0123 / 12345678",
                          "pay_date": "2019-08-20T08:24:00",
                          "ship_date": "2019-08-20T08:24:00",
                          "payment_method": 1,
                          "order_status_id": 1,
                          "order_products": [
                            {
                              "discount_percent": 0.00,
                              "quantity": 1.00,
                              "unit_price": 2.99,
                              "product_id": "123",
                              "name": "Test Artikel",
                              "sku": "A-123",
                              "tax_rate": 19.00,
                              "options": [
                                {
                                  "name": "Name der Option",
                                  "value": "Wert der Option"
                                }
                              ]
                            }
                          ],
                          "order_history": [
                            {
                              "date_added": "2019-08-20T08:24:00",
                              "name": "Änderungswunsch",
                              "comment": "Ich hätte den Artikel gerne in rot statt in blau",
                              "from_customer": true
                            }
                          ],
                          "seller_comment": "Stammkunde! -> Bevorzugt behandeln",
                          "shippingprofile_id": "flat_national",
                          "vat_id": "DE123456789"
                        }
                      ]
                    }

Hinweise zu einzelnen Feldern:

Statuswerte bei Billbee:

AckOrder

Mit AckOrder quittiert Billbee den Erhalt einer Bestellung. Das kann dazu genutzt werden, die Bestellung im Shop mit einem Flag zu versehen, so dass sie beim nächsten Bestellabruf nicht mehr ausgeliefert wird.

Request

URL: http://shop/billbee_api?Action=AckOrder&OrderId=987654321&Key= ... HTTP Methode: POST

Response

Der Shopserver muss mit HTTP 200 antworten, wenn der Request in Ordnung ist. Der Body kann leer bleiben.

GetOrder - Abrufen einer einzelnen Bestellung

Mit dieser Methode kann Billbee eine einzelne Bestellung abrufen.

Request

URL: http://shop/billbee_api?Action=GetOrder&OrderId=987654321&Key= ... Methode: GET

Response

Der Shopserver muss mit HTTP 200 antworten, wenn der Request in Ordnung ist und liefert die Bestellung als JSON Objekt im Format wie bei GetOrders  spezifiziert:

{
                        "order_id": 4, // internal order id
                        "order_number": "#10004", // display order number (can be the same as order_id)
                        …
                    }

TriggerShopSync

Diese Methode implementiert der Billbee Webservice und kann optional vom Shop aufgerufen werden, wenn neue Bestelldaten vorhanden sind, um einen sofortigen Abruf durch Billbee zu initiieren. Dazu ruft der Shop einfach diese URL per HTTP GET auf: https://app.billbee.io/Sync/TriggerShopSync/SHOPID. Wobei SHOPID durch die bei Billbee hinterlegte interne ID dieses Shops zu ersetzen ist. Die SHOPID kann bei Billbee ermittelt werden, indem man unter Einstellungen / Shops die Eigenschaften des Shops öffnet, oder sie wird auch bei jedem Aufruf von GetOrders im Parameter ShopId übermittelt.

SetOrderState

Ändert den Status einer Bestellung im Shopsystem. Diese Methode wird von Billbee für eine Bestellung aufgerufen, wenn sich der Status bei Billbee ändert und die Schnittstelle für die bidirektionale Datgenübertragung aktiviert ist.

Request

URL: http://shop/billbee_api?Action=SetOrderState&Key= ... HTTP Methode: POST

Response

Der Shopserver muss mit HTTP 200 antworten, wenn der Request in Ordnung ist. Der Body kann leer bleiben.

GetProduct

Ruft die Eigenschaften eines einzelnen Produktes ab. Diese Methode wird von Billbee immer dann aufgerufen, wenn ein Produkt zum ersten Mal verkauft wird, um z.B. Bilder einzulesen.

Request

URL: http://shop/billbee_api?Action=GetProduct&ProductId=1234&Key= ... HTTP Methode: GET

Response

Der Shopserver muss mit HTTP 200 antworten, wenn der Request in Ordnung ist. Der Body enthält die Daten des Produktes als JSON Objekt:

{
                        "id": 1234,
                        "description": "eine lange Beschreibung, kann auch HTML enthalten",
                        "shortdescription": "eine kurze Beschreibung, kann auch HTML enthalten",
                        "basic_attributes": "die wesentlichen Merkmale des Artikels",
                        "title": "Kurzer Produkt Titel",
                        "images": [
                            {
                                "url": "http://shop/bilder/1.jpg ",
                                "isDefault": true,
                                "position": 1
                            }
                        ],
                        "price": 9.90,
                        "quantity": 50, // available stock
                        "sku": "WB1234", // own article number
                        "weight": 0.5000, // optinoal weight in kg
                        "vat_rate": 19.0000,
                        "": "",
                    }

GetProducts

Ruft die Liste aller Produkte des Shops ab. Die Methode muss Paging unterstützen, um auch größere Datenmengen übertragen zu können.

Request

URL: http://shop/billbee_api?Action=Getproducts&Page=1&PageSize=100&Key= ... Methode: GET

Response

Der Shopserver muss mit HTTP 200 antworten, wenn der Request in Ordnung ist und liefert eine Liste aller Produkte JSON Objekt im folgenden Format:

{
                        paging: {
                            page: 1,
                            totalCount: 150,
                            totalPages: 2
                        },
                        products: [
                            {
                                ..
                            }
                        ]
                    }

SetStock

Ändert den Lagerbestand eines Produktes im Shopsystem. Diese Methode wird von Billbee aufgerufen, wenn sich der Lagerbestand bei Billbee z.B. durch einen Verkauf auf einem anderen Kanal ändert. Wichtig ist, dass bei einem Lagerbestand von 0 im Shop kein Verkauf mehr stattfinden kann.

Request

URL: http://shop/billbee_api?Action=SetStock&Key= ... HTTP Methode: POST

Response

Der Shopserver muss mit HTTP 200 antworten, wenn der Request in Ordnung ist. Der Body kann leer bleiben.

GetShippingProfiles

Ruft eine Liste mit allen Versandwegen des Shopsystems ab. Diese Methode wird von Billbee aufgerufen, damit ein Mapping von Versandwegen aus dem Shop zu Versandwegen in Billbee hergestellt werden kann.

Request

URL: http://shop/billbee_api?Action=GetShippingProfiles&Key= ... HTTP Methode: GET

Response

Der Shopserver muss mit HTTP 200 antworten, und gibt eine Liste mit Versandprofiles zurück. EinVersandprofile besteht aus einer ID und einem Anzeigenamen Die ID kann alphanumerisch sein (String):

[
                        {
                            Id: “SP1”,
                            Name: “DHL Paket”
                        },
                        {
                            Id: “SP2”,
                            Name: “Nachnahme”
                        }
                    ]