Best Practice - Nutzung der Billbee-API durch Fulfillmentdienstleister
Mit der Billbee-API steht dir eine leistungsstarke Schnittstelle zur Verfügung, um den Datenaustausch vollständig zu automatisieren. Damit am Ende des Prozesses die Sendungsdaten korrekt in deinem Billbee-Account hinterlegt sind und vollständig zum Shop / Marktplatz übertragen werden können, gibt es ein paar Dinge zu beachten. Im Folgenden erklären wir dir und deinem Fulfillmentdienstleister, wie ihr hier gemeinsam den besten Workflow für euch finden könnt.
In diesem Artikel
Abruf von Bestellungen über die API
Dein Fulfillmentdienstleister kann Bestellungen über die Billbee-API aus Billbee abrufen.
Aufgrund von bspw. API-Limits ist es nicht sinnvoll, permanent alle Bestellungen abzurufen, um festzustellen, welche Bestellungen neu sind. Hier sollte man sich nur auf neue Bestellungen beschränken.
Für den Abruf neuer Bestellungen gibt es verschiedene Mögichkeiten:
Abruf über Webhook
Über einen Webhook (create.order) kannst du explizit neue Bestellungen abrufen. Dieser Webhook kann über die API mittels des Endpunkts /api/v1/webhooks angelegt werden. Dadurch werden die Daten der Bestellung im Payload übermittelt.
Abruf mittels Tag einschränken
Du kannst in deinem Billbee-Account deine Bestellungen mit einem Tag markieren. Zusammen mit deinem Fulfillmentdienstleister könnt ihr dann besprechen, welchen Tag eine Bestellung haben muss, damit sie von eurem Fulfillment abgerufen wird. Beispielhaft kann ein Tag "Fulfillment" sein.
Diese Tags kannst du mithilfe von Regeln in Billbee automatisiert setzen lassen, mittels der Regelaktion "Tag zu der Bestellung hinzufügen".
Nachdem die Bestellung abgerufen wurde, sollte das Tag durch den Fulfiller entfernt und/oder ein neues Tag (zum Beispiel „Fulfillment_abgerufen„) hinzugefügt werden. Das geschieht über den Endpunkt /api/v1/orders/{id}/tags.
Außerdem könnte der Status auf „Im Fulfillment“ geändert werden.
Endpunkt: /api/v1/orders/{id}/orderstate
Dein Fulfillmentdienstleister ruft jetzt regelmäßig – zum Beispiel alle 4 Stunden - alle Bestellungen aus den letzten 7 Tagen ab, die den von dir vergebenen Tag haben, und setzt ggf. den Sttaus "Im Fulfillment".
Beispielcall: {{baseUrl}}/api/v1/orders?minOrderDate=2024-07-21&tag=Fullfillment
Sendungsdaten hinterlegen
Sendungsdaten werden immer gemeinsam mit dem Status "Versendet" zum Shop / Marktplatz übertragen. Daher ist es wichtig, dass die Sendungsdaten in der Bestellung hinterlegt sind, bevor sich der Status auf "Versendet" ändert.
Tipp: Wie genau Sendungsdaten an Shops / Marktplätze übermittelt werden und was dabei zu beachten ist, erklären wir dir genauer in unserem Hilfeartikel "Best Practice - Sendungsdaten aus Billbee an Shops / Marktplätze übermitteln"
Damit die Sendungsdaten korrekt zu den jeweiligen Shops / Marktplätzen übermittelt werden können, ist es notwendig, dass in deinem Billbee-Account alle Versandprodukte konfiguriert sind. Wie du hierbei vorgehst, erklären wir dir in folgenden Hilfeartikeln:
Dies kommt zum Tragen, wenn dein Fulfillment Versandlabels direkt in deinem Billbee-Account erstellt.
Diese Option muss genutzt werden, wenn dein Fulfillment Versandlabels außerhalb von Billbee erzeugt und die Sendungsdaten an deinen Billbee-Account überträgt.
Die IDs der in deinem Billbee-Account vorhandenen Versandanbindungen können über die API abgerufen werden:
https://app.billbee.io//swagger/ui/index#/Shipments/Shipment_GetShippingCarrier
https://app.billbee.io//swagger/ui/index#/Shipments/Shipment_GetShippingproviders
Es gibt zwei Möglichkeiten, wie dein Fulfillmentdienstleister bestenfalls die Sendungsdaten in deinen Bestellungen hinterlegen kann:
Erstellung von Versandlabels mittels Versandanbindung in Billbee
Dein Fulfillment kann Versandlabels direkt in deinem Billbee-Account erstellen lassen. Dafür ist folgender Call notwendig:
Endpunkt: https://app.billbee.io//swagger/ui/index#/Shipments/Shipment_ShipWithLabel
{
"OrderId": 0,
"ProviderId": 0,
"ProductId": 0,
"ChangeStateToSend": true,
"PrinterName": "string",
"WeightInGram": 0,
"ShipDate": "2024-07-29T08:05:23.712Z",
"ClientReference": "string",
"Dimension": {
"length": 0,
"width": 0,
"height": 0
}
}
OrderId: BillbeeID der Bestellung
ProviderId: ShippingProviderID für den in Billbee angelegten Versanddienstleister (bspw. DHL)
ProductId: ShippingProviderProductID für die in Billbee angelegten Versandprodukte (bspw. DHL Paket)
ChangeStateToSend: Wenn „true“ wird der Status der Bestellung auf „versendet“ geändert.
PrinterName: wird nicht genutzt
WeightInGram: Gewicht der Sendung (in Gramm)
ClientReference: Referenz, die an den Versandanbieter übertragen wird. (bspw. Bestellnummer oder SKU der verpackten Produkte)
Dimension: Abmessungen – werden an den Versandanbieter übertragen.
Übermittlung von extern erstellten Sendungsdaten
Erstellt dein Fulfillmentdienstleister Versandlabels außerhalb von Billbee, kann er zur Vollständigkeit des Prozesses, die Sendungsdaten in den Bestellungen deines Billbee-Accounts hinterlegen:
Endpunkt:
https://app.billbee.io//swagger/ui/index#/Orders/OrderApi_AddShipment
{
"ShippingId": "string",
"OrderId": "string",
"Comment": "string",
"ShippingProviderId": 0,
"ShippingProviderProductId": 0,
"CarrierId": 0,
"ShipmentType": 0
}
ShippingId: Sendungsnummer
OrderId: OrderId (Auftragsnummer) des Versanddienstleisters
ShippingProviderId: in Billbee angelegter Versanddienstleister (bspw. DHL)
ShippingProviderProductId: in Billbee angelegte Versandprodukte (bspw. DHL Paket)
ShipmentType: 0 kennzeichnet eine „normale“ Sendung, 1 kennzeichnet eine Retoure
Wichtig: Die OrderId ist NICHT die OrderId der Bestellung, sondern die OrderId (Auftragsnummer) des Versanddienstleisters. Bei DHL ist sie z.B. identisch mit der Sendungsnummer, bei anderen Versendern sind sie meist verschieden.
Wenn eine falsche „OrderId“ gesetzt wird, funktioniert unter Umständen das Tracking nicht korrekt. Außerdem überprüfen manche Marktplätze bei der Übertragung der Sendungsdaten, ob die Daten das erwartete Format haben.