Billbee API zur Anbindung von 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. In der Regel agiert Billbee dabei 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:

Code Beschreibung
200 Ok: Der Request wurde erfolgreich verarbeitet
404 Not Found: Die angeforderte Resource existiert nicht (z.B. ungültige Bestell Id)
401 Unauthorized: Authentifizierung ist fehlgeschlagen / falsches Passwort, Key ungültig
403 Forbidden: Erfolgreich authentifiziert, aber keine Zugriffsberechtigung
400 Bad Request: Der Request ist in einem ungültigen Format / Parameter fehlen
500 Internal Server Error: Bei der Verarbeitung ist ein unerwarteter Fehler aufgetreten
Testen

Um die Implementierung testen zu können, gibt es diese Seite in der Billbee Anwendung: https://app.billbee.io/app/dev/testshopapi

Dort können alle relevanten Methoden in der eigenen Implementierung aufgerufen werden. Einzige Voraussetzung ist, dass der Testserver im Internet erreichbar ist.

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

Parameter:
Name Beispiel Beschreibung
Action GetOrders Spezifiziert die Aktion Bestellabruf
Key 123456abcdef Verschlüsseltes Sicherheitstoken
StartDate 2013-11-28 Startdatum, ab dem neue und geänderte Bestellungen zurückgeliefert werden sollen
Page 1 Seite des Datenabrufs
PageSize 100 Anzahl der maximal zurückzugebenden Datensätze
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",
                          "payment_transaction_id": "PAY-1234545"
                        }
                      ]
                    }

Hinweise zu einzelnen Feldern:

Name Beschreibung
order_id Interne Id der Bestellung.
order_number

Evtl. abweichende Anzeigebezeichnung der Bestellnummer. Sonst kann der Wert auch der order_id entsprechen.

vat_id Umsatzsteueridentifikationsnummer
payment_method Zahlart - gültige Werte sind:
  • Bankueberweisung = 1,
  • Nachnahme = 2,
  • PayPal = 3,
  • Barzahlung = 4,
  • Gutschein = 6,
  • Sofortüberweisung = 19,
  • MoneyOrder = 20,
  • Check = 21,
  • Andere = 22,
  • Lastschrift = 23,
  • Moneybookers = 24,
  • KLARNA = 25,
  • Rechnung = 26,
  • Moneybookers_Kreditkarte = 27,
  • Moneybookers_Lastschrift = 28,
  • BILLPAY_Rechnung = 29,
  • BILLPAY_Lastschrift = 30,
  • Kreditkarte = 31,
  • Maestro = 32,
  • iDEAL = 33,
  • EPS = 34,
  • P24 = 35,
  • ClickAndBuy = 36,
  • GiroPay = 37,
  • Novalnet_Lastschrift = 38,
  • KLARNA_PartPayment = 39,
  • iPayment_CC = 40,
  • Billsafe = 41,
  • Testbestellung = 42,
  • WireCard_Kreditkarte = 43,
  • AmazonPayments = 44,
  • Secupay_Kreditkarte = 45,
  • Secupay_Lastschrift = 46,
  • WireCard_Lastschrift = 47,
  • EC = 48
  • Paymill_Kreditkarte = 49,
  • Novalnet_Kreditkarte = 50,
  • Novalnet_Rechnung = 51,
  • Novalnet_PayPal = 52,
  • Paymill = 53,
  • Rechnung_PayPal = 54,
  • Selekkt = 55,
  • Avocadostore = 56,
  • DirectCheckout = 57,
  • Rakuten = 58,
  • Vorkasse = 59,
  • Kommissionsabrechnung = 60,
  • Amazon_Marketplace = 61,
  • Amazon_Payments_Advanced = 62,
  • Stripe = 63,
  • BILLPAY_PayLater = 64,
  • PostFinance = 65,
  • iZettle = 66,
  • SumUp = 67,
  • payleven = 68,
  • atalanda = 69,
  • Saferpay_Kreditkarte = 70,
  • WireCard_PayPal = 71,
  • Micropayment = 72,
  • Ratenkauf = 73,
  • Wayfair = 74, // baranski
  • MangoPay_PayPal = 75,
  • MangoPay_Sofortueberweisung = 76,
  • MangoPay_Kreditkarte = 77,
  • MangoPay_iDeal = 78,
  • PayPal_Express = 79,
  • PayPal_Lastschrift = 80,
  • PayPal_Kreditkarte = 81,
  • Wish = 82,
  • Bancontact_Mister_Cash = 83,
  • Belfius_Direct_Net = 84,
  • KBC_CBC_Betaalknop = 85,
  • Novalnet_Przelewy24 = 86,
  • Novalnet_Vorkasse = 87,
  • Novalnet_Instantbank = 88,
  • Novalnet_IDEAL = 89,
  • Novalnet_EPS = 90,
  • Novalnet_GiroPay = 91,
  • Novalnet_Barzahlen = 92,
  • Real = 93,
  • Fruugo = 94,
  • Cdiscount = 95,
  • PayDirekt = 96,
  • EtsyPayments = 97,
  • KLARNA = 98,
  • limango = 99,
  • SantanderRatenkauf = 100,
  • SantanderRechnungskauf = 101,
  • Cashpresso = 102,
  • Tipser = 103,
  • Ebay = 104,
  • Mollie = 105,
  • MollieInvoice = 106,
  • MollieCreditCard = 107,
  • MollieSofort = 108,
  • MollieGiroPay = 109,
  • MollieMaestro = 110,
  • MollieKlarnaPayLater = 111,
  • MolliePayPal = 112,

Alles andere wird auf die Zahlart „Andere“ gemappt.

order_status_id Der aktuelle Status der Bestellung. Entweder es werden direkt die Billbee Status IDs verwendet (Siehe unten).
unit_price Produkt Einzelpreis – alle Preise werden brutto angegeben
sku Eigene Artikelnummer, falls vorhanden. Sonst null
tax_rate Der Umsatzsteuersatz, zu dem das Produkt versteuert wird.
order_history Hier können Kommentare zu einer Bestellung übertragen werden. Das Feld name legt fest, wer der Absender der Nachricht ist.
shippingprofile_id Optional die ID eines Versandprofiles, das auf ein Billbee Versandprodukt gemappt werden kann.
pay_date Optional, das Zahldatum
ship_date Optional, das Versanddatum
order_products[n].tax_rate
Optional, der Steuersatz, z.B. 19.00 für 19%

Statuswerte bei Billbee:

Status Beschreibung
1 Bestellt
2 Bestätigt
3 Bezahlt
4 Versendet
5 Reklamiert
6 Gelöscht
7 Abgeschlossen
8 Storniert
9 Archiviert
10 Bewertet
11 1. Mahnung
12 2. Mahnung
13 Gepackt
14 Angeboten
15 Zahlungserinnerung
16 Übergeben an externes Fulfillment

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

Parameter:
Name Beispiel Beschreibung
Action AckOrder Url Parameter: Spezifiziert die Aktion Bestätigung
Key 123456abcdef Url Parameter: Verschlüsseltes Sicherheitstoken
OrderId 987654321 Body Parameter: Id der Bestellung, die eingelesen wurde
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

Parameter:
Name Beispiel Beschreibung
Action GetOrder Spezifiziert die Aktion Bestellabruf
Key 123456abcdef Verschlüsseltes Sicherheitstoken
OrderId 987654321 Interne Id der Bestellung, die abgerufen werden soll
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

Parameter:
Name Beispiel Beschreibung
Action SetOrderState Url Parameter: Spezifiziert die Aktion Statusänderung
Key 123456abcdef Url Parameter: Verschlüsseltes Sicherheitstoken
OrderId 987654321

Body Parameter: Id der Bestellung, deren Status geändert werden soll

NewStateId 3

Body Parameter: Neue Status Id (z.B. 3 für bezahlt, 4 für

versendet, 7 für abgeschlossen)

Comment Ein Text

Body Parameter: Optionaler Text, der an den Kunden

gesendet bzw. in der Bestellhistorie gespeichert werden

soll

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

Parameter:
Name Beispiel Beschreibung
Action GetProduct Url Parameter: Spezifiziert die Aktion Produkt abrufen
Key 123456abcdef Url Parameter: Verschlüsseltes Sicherheitstoken
ProductId 1234 Url Parameter: Interne Id des Produktes
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

Parameter:
Name Beispiel Beschreibung
Action GetProducts Spezifiziert die Aktion Produktabruf
Key 123456abcdef Verschlüsseltes Sicherheitstoken
Page 1 Seite des Datenabrufs
PageSize 100 Anzahl der maximal zurückzugebenden Datensätze
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

Name Beispiel Beschreibung
Action SetStock Url Parameter: Spezifiziert die Aktion Bestandsänderung
Key 123456abcdef Url Parameter: Verschlüsseltes Sicherheitstoken
ProductId 987654321 Body Parameter: Id des Produktes, dessen Lagerbestand geändert werden soll
AvailableStock 3 Body Parameter: Neuer Wert für den Lagerbestand
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

Name Beispiel Beschreibung
Action GetShippingProfiles Url Parameter: Spezifiziert die Aktion Bestandsänderung
Key 123456abcdef Url Parameter: Verschlüsseltes Sicherheitstoken
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”
                        }
                    ]
War dieser Artikel hilfreich? Vielen Dank für dein Feedback Bei der Übermittlung deines Feedback gab es Probleme, bitte probiere es erneut.