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


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:

https://app.billbee.io//swagger/ui/index#!/Orders/OrderApi_GetList 

{
  "Paging": {
    "Page": 0,  // (integer, optional)
    "TotalPages": 0,    // (integer, optional)
    "TotalRows": 0,    // (integer, optional)
    "PageSize": 0    // (integer, optional)
  },
  "ErrorMessage": "string",
  "ErrorCode": 0,
  "Data": [
    {
      "RebateDifference": 0,    // (number, optional, read only)
      "ShippingIds": [  // (Array[Billbee.Interfaces.BillbeeAPI.Model.Shipment], optional): The shipments of the order
        {
          "ShippingId": "string",    // (string, optional): The id of this shipment
          "Shipper": "string",    // (string, optional): The name of the shipping provider
          "Created": "2019-06-17T12:56:46.258Z"    // (string, optional): The creation date
        }
      ],
      "AcceptLossOfReturnRight": true,  // (boolean, optional): Customer accepts loss due to withdrawal
      "Id": "string",   // (string, optional): Id of the order in the external system (marketplace)
      "OrderNumber": "string",   // (string, optional): Order number of the order in the external system (marketplace)
      "State": 1,   // (integer, optional): The current state of the order = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16']integerEnum:1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
      "VatMode": 0,   // (integer, optional): The vat mode of the order = ['0', '1', '2', '3', '4', '5']integerEnum:0, 1, 2, 3, 4, 5
      "CreatedAt": "2019-06-17T12:56:46.258Z",   // (string, optional): The date on which the order was created
      "ShippedAt": "2019-06-17T12:56:46.258Z",   // (string, optional): The date on which the order was shipped
      "ConfirmedAt": "2019-06-17T12:56:46.258Z",   // (string, optional): The date on which the order was confirmed
      "PayedAt": "2019-06-17T12:56:46.258Z",   // (string, optional): The date on which the order was paid
      "SellerComment": "string",   // (string, optional): An internal seller comment
      "Comments": [ // (Array[Billbee.Interfaces.Order.Comment], optional): All messages / comments of the order
        {
          "FromCustomer": true,    // (boolean, optional)
          "Text": "string",    // (string, optional)
          "Name": "string",    // (string, optional)
          "Created": "2019-06-17T12:56:46.258Z",    // (string, optional)
          "Id": 0    // (integer, optional)
        }
      ],
      "InvoiceNumberPrefix": "string",   // (string, optional): The prefix of the invoice number
      "InvoiceNumberPostfix": "string",   // (string, optional): The postfix of the invoice number
      "InvoiceNumber": 0,   // (integer, optional): The invoice number
      "InvoiceDate": "2019-06-17T12:56:46.258Z",   // (string, optional): The date on which the invoice was created
      "InvoiceAddress": {   // (Billbee.Interfaces.Order.Address, optional): The billing address
        "Company": "string",    // (string, optional): The company name
        "Street": "string",    // (string, optional): The street excl. the housenumber
        "HouseNumber": "string",    // (string, optional): The house number
        "Line2": "string",    // (string, optional): The second address line
        "Line3": "string",    // (string, optional): The third address line
        "City": "string",    // (string, optional): The city
        "Zip": "string",    // (string, optional): The postal code
        "State": "string",    // (string, optional): The name of the state
        "Country": "string",    // (string, optional): The name of the country
        "CountryISO2": "string",    // (string, optional): The 2-letter country code
        "FirstName": "string",    // (string, optional): The first name
        "LastName": "string",    //(string, optional): The last name
        "Id": "string",    // (string, optional): The id of the address in the external system
        "BillbeeId": 0,    // (integer, optional): The Billbee internal ID of the address record
        "Phone": "string",    // (string, optional): The phone number
        "Email": "string",    //(string, optional): The email address
        "Comment": "string",    // (string, optional): A internal comment to this address
        "NameAddition": "string",    // (string, optional): A addition to the address (e.g. Apartment 2, Back door)
        "Salutation": 0,    // (integer, optional): The salutation = ['0', '1', '2', '3', '4']integerEnum:0, 1, 2, 3, 4
        "Title": "string"    // (string, optional): An internal identifier for this address
      },
      "ShippingAddress": {  // (Billbee.Interfaces.Order.Address, optional): The delivery address
        "Company": "string",    // (string, optional): The company name
        "Street": "string",    // (string, optional): The street excl. the housenumber
        "HouseNumber": "string",    // (string, optional): The house number
        "Line2": "string",    // (string, optional): The second address line
        "Line3": "string",    // (string, optional): The third address line
        "City": "string",    // (string, optional): The city
        "Zip": "string",    // (string, optional): The postal code
        "State": "string",    // (string, optional): The name of the state
        "Country": "string",    // (string, optional): The name of the country
        "CountryISO2": "string",    // (string, optional): The 2-letter country code
        "FirstName": "string",    // (string, optional): The first name
        "LastName": "string",    //(string, optional): The last name
        "Id": "string",    // (string, optional): The id of the address in the external system
        "BillbeeId": 0,    // (integer, optional): The Billbee internal ID of the address record
        "Phone": "string",    // (string, optional): The phone number
        "Email": "string",    //(string, optional): The email address
        "Comment": "string",    // (string, optional): A internal comment to this address
        "NameAddition": "string",    // (string, optional): A addition to the address (e.g. Apartment 2, Back door)
        "Salutation": 0,    // (integer, optional): The salutation = ['0', '1', '2', '3', '4']integerEnum:0, 1, 2, 3, 4
        "Title": "string"    // (string, optional): An internal identifier for this address
      },
      "PaymentMethod": 1,   // (integer, optional): The payment method = ['1', '2', '3', '4', '6', '19', '20', '21', '22', '23', '24', '25', '26', '27', '28', '29', '30', '31', '32', '33', '34', '35', '36', '37', '38', '39', '40', '41', '42', '43', '44', '45', '46', '47', '48', '49', '50', '51', '52', '53', '54', '55', '56', '57', '58', '59', '60', '61', '62', '63', '64', '65', '66', '67', '68', '69', '70', '71', '72', '73', '74', '75', '76', '77', '78', '79', '80', '81', '82', '83', '84', '85', '86', '87', '88', '89', '90', '91', '92', '93', '94', '95', '96', '97', '98', '99', '100', '101', '102']integerEnum:1, 2, 3, 4, 6, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102
      "ShippingCost": 0,    // (number, optional): The shipping cost
      "TotalCost": 0,    // (number, optional): The total cost excluding shipping cost
      "AdjustmentCost": 0,    // (number, optional)
      "AdjustmentReason": "string",    // (string, optional)
      "OrderItems": [   // (Array[Billbee.Interfaces.BillbeeAPI.Model.OrderItem], optional): The list of items purchased like shirt, pant, toys etc
        {
          "BillbeeId": 0,    // (integer, optional): The billbee id of this item
          "TransactionId": "string",    // (string, optional): Id of the individual transaction. Only required by Ebay to detect aggregated orders
          "Product": {    // (Billbee.Interfaces.BillbeeAPI.Model.SoldProduct, optional): The sold product
            "OldId": "string",
            "Id": "string",
            "Title": "string",
            "Weight": 0,
            "SKU": "string",
            "SkuOrId": "string",
            "IsDigital": true,
            "Images": [
              {
                "Url": "string",
                "IsDefaultImage": true,
                "Position": 0,
                "ExternalId": "string"
              }
            ],
            "EAN": "string",
            "PlatformData": "string",
            "TARICCode": "string",
            "CountryOfOrigin": "string",
            "BillbeeId": 0
          },
          "Quantity": 0,    // (number, optional): The sold quantity
          "TotalPrice": 0,    // (number, optional): The total price (unit price * quantity)
          "TaxAmount": 0,    // (number, optional): The tax amount in the total price
          "TaxIndex": 0,    // (integer, optional): The tax index.
          "Discount": 0,    // (number, optional): Sets the discount in percent
          "Attributes": [    // (Array[Billbee.Interfaces.BillbeeAPI.Model.OrderItemAttribute], optional): A list of product attributes for this position
            {
              "Id": "string",
              "Name": "string",
              "Value": "string",
              "Price": 0
            }
          ],
          "GetPriceFromArticleIfAny": true,    // (boolean, optional): If true, the price will be overwritten by the known article price in billbee if available
          "IsCoupon": true,    // (boolean, optional): Determines if it is a coupon, which is interpreted as tax-free payment
          "ShippingProfileId": "string",    // (string, optional): Determines if it is a coupon, which is interpreted as tax-free payment
          "DontAdjustStock": true,    // (boolean, optional): If true, the import of this order won't adjust the stock level at billbee.
          "UnrebatedTotalPrice": 0,    // (number, optional): Is just used for the billbee api
          "SerialNumber": "string"    // (string, optional): Contains the used serial number
        }
      ],
      "Currency": "string",    // (string, optional): The three letter currency code.
      "Seller": {    // (Billbee.Interfaces.BillbeeAPI.Model.OrderUser, optional)
        "Platform": "string",
        "BillbeeShopName": "string",
        "BillbeeShopId": 0,
        "Id": "string",
        "Nick": "string",
        "FirstName": "string",
        "LastName": "string",
        "FullName": "string",
        "Email": "string"
      },
      "Buyer": {    // (Billbee.Interfaces.BillbeeAPI.Model.OrderUser, optional)
        "Platform": "string",    // (string, optional): The name of the platform from which this customer originated
        "BillbeeShopName": "string",    // (string, optional): The name of shop connection in Billbee
        "BillbeeShopId": 0,    // (integer, optional): The Billbee internal id of the shop connection
        "Id": "string",    // (string, optional): The Billbee internal id of this customer
        "Nick": "string",    // (string, optional): The nick name (if available) from the original system
        "FirstName": "string",    // (string, optional): The first name of this customer
        "LastName": "string",    // (string, optional): The last name of this customer
        "FullName": "string",    // (string, optional, read only): The full name ("firstname lastname") of this customer
        "Email": "string"    // (string, optional): The email address of this customer
      },
      "UpdatedAt": "2019-06-17T12:56:46.258Z",    // (string, optional): The date on which the order was last updated
      "TaxRate1": 0,    // (number, optional): The regular tax rate
      "TaxRate2": 0,    // (number, optional): The reduced tax rate
      "BillBeeOrderId": 0,    // (integer, optional): The Order.Id from the Billbee database
      "BillBeeParentOrderId": 0,    // (integer, optional): The Id of the parent order in the Billbee database
      "VatId": "string",    // (string, optional): The customers vat id
      "Tags": [    // (Array[string], optional): The Tags of the order
        "string"
      ],
      "ShipWeightKg": 0,    // (number, optional): The total weight of the shipment(s)
      "LanguageCode": "string",    // (string, optional): The two-letter language code of the customer
      "PaidAmount": 0,    // (number, optional)
      "ShippingProfileId": "string",    // (string, optional): Internal Id for the shipping profile for that order
      "ShippingProviderId": 0,    // (integer, optional): Internal Id for the used shipping provider
      "ShippingProviderProductId": 0,    // (integer, optional): Internal Id for the used shipping product
      "ShippingProviderName": "string",    // (string, optional): The Name for of used shipping provider
      "ShippingProviderProductName": "string",    // (string, optional): The Name of the used shipping product
      "ShippingProfileName": "string",    // (string, optional): Display Name of Shipping profile, if available
      "PaymentInstruction": "string",    // (string, optional): A textfield optionaly filled with a payment instruction text for printout on the invoice (z.B. Ebay Kauf auf Rechnung)
      "IsCancelationFor": "string",    // (string, optional): An optional Order Id (externalid) for an order if this is a cancel order (shopify only at the moment)
      "PaymentTransactionId": "string",    // (string, optional): The id of the payment transaction. For example the transaction id of PayPal payment
      "DistributionCenter": "string",    // (string, optional): An optional code for the distribution center delivering this order
      "DeliverySourceCountryCode": "string",    // (string, optional): An optional Country ISO2 Code of the country where order is shipped from (FBA)
      "CustomInvoiceNote": "string",    // (string, optional): An optional multiline text which is printed on the invoice
      "CustomerNumber": "string",    // (string, optional): The customer number (not to be confused with the id of the customer)
      "PaymentReference": "string",    // (string, optional): A payment reference
      "ShippingServices": [    // (Array[Billbee.Interfaces.Shipping.ProductService], optional): Additional services for the shipment
        {
          "DisplayName": "string",    // (string, optional, read only)
          "DisplayValue": "string",    // (string, optional, read only)
          "RequiresUserInput": true,    // (boolean, optional, read only)
          "ServiceName": "string",    // (string, optional, read only)
          "typeName": "string",    // (string, optional, read only)
          "PossibleValueLists": [    // (Array[System.Collections.Generic.KeyValuePair[System.String,System.Collections.Generic.List[System.Collections.Generic.KeyValuePair[System.Int32,System.String]]]], optional, read only)
            {
              "key": "string",
              "value": [
                {
                  "key": 0,
                  "value": "string"
                }
              ]
            }
          ]
        }
      ],
      "Customer": {    // (Billbee.Interfaces.BillbeeAPI.Model.CustomerApiModel, optional): The Customer object connected with the order
        "Id": 0,    // (integer, optional)
        "Name": "string",    // (string, optional)
        "Email": "string",    // (string, optional)
        "Tel1": "string",    // (string, optional)
        "Tel2": "string",    // (string, optional)
        "Number": 0,    // (integer, optional)
        "PriceGroupId": 0,    // (integer, optional)
        "LanguageId": 0,    // (integer, optional)
        "VatId": "string",    // (string, optional)
        "Type": 0    // (integer, optional): Customer Type
      }
    }
  ]
}


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.

customer_id

Id des Kunden. 0 bedeutet, der Kunde hat über einen Gastzugang bestellt und keine ID erhalten. Ist keine Kunden Id vorhanden, kann auch null übergeben werden

vat_idUmsatzsteueridentifikationsnummer
vat_modeUmsatzsteuermodus
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.


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”
    }
]