Einleitung

Dieses Dokument beschreibt eine Programmierschnittstelle zum Übertragen von Bestell-, Kundenund

Produktdaten zwischen einem Webshop / Marktplatz und der Multichannel Verkäufersoftware

www.billbee.io

Dieses Dokument ist nur für die interne Verwendung vorgesehen, um ein Shopsystem an Billbee

anzubinden und darf nicht ohne Genehmigung der Billbee GmbH weitergegeben oder veröffentlicht

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

Die Authentifizierung und Autorisierung erfolgt über zwei Mechanismen:


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:

CodeBeschreibung
200Ok: Der Request wurde erfolgreich verarbeitet
404Not Found: Die angeforderte Resource existiert nicht (z.B. ungültige Bestell Id)
401Unauthorized: Authentifizierung ist fehlgeschlagen / falsches Passwort, Key ungültig
403Forbidden: Erfolgreich authentifiziert, aber keine Zugriffsberechtigung
400Bad 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


Methoden

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:

NameBeispielBeschreibung
ActionGetOrdersSpezifiziert die Aktion Bestellabruf
Key123456abcdefVerschlüsseltes Sicherheitstoken
StartDate2013-11-28

Startdatum, ab dem neue und geänderte Bestellungen zurückgeliefert werden sollen

Page1Seite des Datenabrufs
PageSize100Anzahl 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:

NameBeschreibung
order_idInterne Id der Bestellung.
order_number

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

vat_idUmsatzsteueridentifikationsnummer
payment_methodZahlart - 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


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_priceProdukt Einzelpreis – alle Preise werden brutto angegeben
skuEigene Artikelnummer, falls vorhanden. Sonst null
tax_rateDer 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_dateOptional, das Zahldatum
ship_dateOptional, das Versanddatum
order_products[n].tax_rate
Optional, der Steuersatz, z.B. 19.00 für 19%


Statuswerte bei Billbee:

StatusBeschreibung
1Bestellt
2Bestätigt
3Bezahlt
4Versendet
5Reklamiert
6Gelöscht
7Abgeschlossen
8Storniert
9Archiviert
10Bewertet
111. Mahnung
122. Mahnung
13Gepackt
14Angeboten
15Ü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:

NameBeispielBeschreibung
ActionAckOrderUrl Parameter: Spezifiziert die Aktion Bestätigung
Key123456abcdefUrl Parameter: Verschlüsseltes Sicherheitstoken
OrderId987654321Body 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:

NameBeispielBeschreibung
ActionGetOrderSpezifiziert die Aktion Bestellabruf
Key123456abcdefVerschlüsseltes Sicherheitstoken
OrderId987654321Interne 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:

NameBeispielBeschreibung
ActionSetOrderStateUrl Parameter: Spezifiziert die Aktion Statusänderung
Key123456abcdefUrl Parameter: Verschlüsseltes Sicherheitstoken
OrderId987654321

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

werden soll

NewStateId3

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

versendet, 7 für abgeschlossen)

CommentEin 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:

NameBeispielBeschreibung
ActionGetProductUrl Parameter: Spezifiziert die Aktion Produkt abrufen
Key123456abcdefUrl Parameter: Verschlüsseltes Sicherheitstoken
ProductId1234Url 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:

NameBeispielBeschreibung
ActionGetProductsSpezifiziert die Aktion Produktabruf
Key123456abcdefVerschlüsseltes Sicherheitstoken
Page1Seite des Datenabrufs
PageSize100Anzahl 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


Parameter:

NameBeispielBeschreibung
ActionSetStockUrl Parameter: Spezifiziert die Aktion Bestandsänderung
Key123456abcdefUrl Parameter: Verschlüsseltes Sicherheitstoken
ProductId987654321

Body Parameter: Id des Produktes, dessen Lagerbestand

geändert werden soll

AvailableStock3Body 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


Parameter:

NameBeispielBeschreibung
ActionGetShippingProfilesUrl Parameter: Spezifiziert die Aktion Bestandsänderung
Key123456abcdefUrl Parameter: Verschlüsseltes Sicherheitstoken


Response

Der Shopserver muss mit HTTP 200 antworten, und gibt eine Liste mit Versandprofiles zurück. Ein

Versandprofile besteht aus einer ID und einem Anzeigenamen Die ID kann alphanumerisch sein (String):

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