Versandoptionen, Provider, Artikel-/Shop-Zuordnung und DHL Label-Erstellung im Manager.
Versandmethoden steuern, welche Lieferarten im Shop-Checkout angeboten werden und welche Versandkosten auf eine Bestellung kommen. In simplebis werden sie als Versandoptionen in den Manager-Einstellungen gepflegt und anschließend bei Artikeln pro Shop ausgewählt.
Eine Versandoption ist dabei ein wiederverwendbares Regelset. Sie enthält eine oder mehrere Länderregeln und darunter die auswählbaren Optionen, zum Beispiel Abholung, DHL, UPS oder Hermes. Im Checkout wird pro benötigter Versandgruppe eine Option ausgewählt. Die Auswahl wird in der Bestellung gespeichert und kann später für Versandkosten, Steuern und die DHL Label-Erstellung verwendet werden.
Die zentrale Pflege befindet sich im simplebis-manager unter Einstellungen > Versandoptionen. Dort zeigt die Tabelle alle Versandoptionen der aktuellen Umgebung. Über Hinzufügen wird eine neue Versandoption angelegt; durch Öffnen eines Eintrags wird sie bearbeitet.
In einer Versandoption werden zuerst Name und Regeln gepflegt. Der Name sollte so gewählt sein, dass klar ist, wofür die Option gedacht ist, zum Beispiel Standardversand Deutschland, Abholung und DHL oder Internationaler Versand.
Eine Versandoption besteht aus Regeln. Jede Regel kann einem Land zugeordnet werden. Aktuell wird die passende Regel anhand des Lieferlands beziehungsweise Rechnungslands im Checkout gesucht. Wenn für das Land keine passende Regel gefunden wird, kann für den Artikel keine Versandoption ermittelt werden.
Innerhalb einer Regel werden die eigentlichen Optionen gepflegt. Jede Option hat mindestens einen Provider. Zusätzlich können Preis, Steuer und Aktiv-Status gepflegt werden. Preis und Steuer werden in die Bestellung übernommen, wenn der Kunde diese Option auswählt.
Für DHL-Optionen erscheinen weitere Felder: DHL Billing Number Key, DHL Produkt, DHL Label-Format, Standardgewicht in Gramm sowie optional Länge, Breite und Höhe. Diese Werte dienen als Vorgaben für die spätere Label-Erstellung aus der Bestellung.
| Provider | Funktion im Checkout | Weitere Funktion im Manager |
|---|---|---|
pickup / Abholung | Bietet Abholung als Lieferart an. | Keine automatische Label-Erstellung. |
dhl / DHL | Bietet DHL als Lieferart an und speichert die Auswahl an der Bestellung. | Kann mit der DHL Parcel DE Integration Versandlabels und Lieferscheine erzeugen. |
ups / UPS | Bietet UPS als Lieferart mit Preis und Steuer an. | Aktuell keine integrierte Label-Erstellung in simplebis. |
hermes / Hermes | Bietet Hermes als Lieferart mit Preis und Steuer an. | Aktuell keine integrierte Label-Erstellung in simplebis. |
Die Provider ups und hermes sind damit vor allem Checkout-Optionen. Eine technische Schnittstelle zum Erstellen von Versandlabels ist derzeit nur für DHL Parcel DE umgesetzt.
Versandoptionen greifen erst, wenn sie an Artikeln verwendet werden. Bei Artikeln wird im Preis-/Shop-Bereich pro Shop eine Versandoption ausgewählt. Dadurch kann derselbe Artikel in unterschiedlichen Shops unterschiedliche Versandregeln verwenden.
Shops können Lieferoptionen außerdem komplett deaktivieren. In der Shop-Konfiguration gibt es dafür die Einstellung Lieferoptionen in diesem Shop deaktivieren. Ist sie aktiv, wird für Artikel in diesem Shop keine Versandoption berechnet.
Im Checkout sammelt simplebis alle benötigten Versandgruppen aus den Artikeln im Warenkorb. Für jede Gruppe muss der Kunde eine Option wählen, bevor die Zahlung fortgesetzt werden kann. Die ausgewählten Versandkosten werden zur Bestellung addiert und die gewählten Provider werden an den Bestellpositionen gespeichert.
Die DHL-Anbindung wird unter Einstellungen > Integrationen > DHL Parcel DE gepflegt. Dort werden Verbindung, Standardwerte, Absender und Billing Numbers konfiguriert.
Im Bereich Verbindung werden diese Daten gepflegt:
Aktiv: aktiviert die DHL Integration für die Umgebung.Modus: Sandbox für Tests oder Production für den Live-Betrieb.Lieferschein-Typ: Dokumenttyp, der beim Erstellen eines DHL Labels als Lieferschein erzeugt werden soll, standardmäßig deliverynote.client_id und client_secret: API-Key und API-Secret aus der DHL Developer App. Der API-Key der DHL App wird in simplebis als client_id eingetragen; das API-Secret der DHL App wird als client_secret eingetragen.username und password: Zugangsdaten des DHL Geschäftskundenportal-Benutzers, idealerweise eines Systembenutzers.Verbindung testen: prüft, ob mit den gespeicherten Daten ein DHL Access Token und ein API-Aufruf möglich sind.Im Bereich Defaults werden das Standard-Label-Format, die Absenderquelle und optional eine ShipperRef gepflegt. Als Absenderquelle kann die Umgebung beziehungsweise der Standort verwendet werden, oder eine eigene Absenderadresse. Wenn eine ShipperRef verwendet wird, muss die zugehörige Absenderreferenz im Post & DHL Geschäftskundenportal existieren.
Im Bereich Billing Numbers werden die abrechnungsrelevanten DHL-Nummern hinterlegt. Jede Billing Number erhält einen internen Key, ein lesbares Label, die eigentliche Billing Number, ein Standardprodukt und optional die Markierung als Standard. Der Key kann in einer DHL-Versandoption als DHL Billing Number Key eingetragen werden, damit diese Versandoption gezielt ein bestimmtes Billing-Profil nutzt. Details zu ShipperRef und Billing Number werden im folgenden Abschnitt beschrieben.
Für die simplebis-Verbindung werden zwei Arten von Daten benötigt: die API-Daten aus dem DHL Developer Portal und die Geschäftskunden-Zugangsdaten aus dem Post & DHL Geschäftskundenportal.
Die Developer-App wird im DHL API Developer Portal erstellt. Dort muss die API DHL Parcel DE Shipping (Post & Parcel Germany) zur App hinzugefügt beziehungsweise über Get Access angefragt werden. Aus dieser App kommen client_id und client_secret für simplebis. Die API-Seite beschreibt auch Sandbox, Production, verfügbare Produkte, Label-Formate und die benötigte Freigabe für den Produktivbetrieb: DHL Parcel DE Shipping API.
Die Anmeldung und App-Verwaltung läuft über das DHL API Developer Portal. Eine DHL-Hilfeseite beschreibt, wie Apps im Developer Portal erstellt oder bearbeitet werden: How to create an App?.
Für die Authentifizierung nutzt DHL ein OAuth-Verfahren mit client_id, client_secret, username und password. Die technische Authentifizierungsseite ist hier dokumentiert: Authentication API (Post & Parcel Germany).
Der username und das password kommen aus dem Post & DHL Geschäftskundenportal: geschaeftskunden.dhl.de. Für produktive Integrationen empfiehlt DHL einen Systembenutzer, weil dieser für Schnittstellen vorgesehen ist und nicht für den normalen Login in die Oberfläche genutzt wird.
Die Billing Number besteht aus EKP, DHL-Produkt beziehungsweise Vertragsverfahren und Vertragsbeteiligung. Sie muss ohne Leerzeichen oder Sonderzeichen in simplebis eingetragen werden. Welche Billing Numbers, Produkte und Rechte verfügbar sind, richtet sich nach dem DHL-Geschäftskundenvertrag und den im Geschäftskundenportal freigegebenen Benutzerrechten.
Für produktive DHL Labels müssen neben den API-Zugangsdaten auch Absender und Abrechnung sauber eingerichtet sein. In simplebis betrifft das vor allem ShipperRef und Billing Numbers.
ShipperRef ist optional. Es ist eine Absenderreferenz aus dem Post & DHL Geschäftskundenportal. Sie wird dort unter Parcel & goods > Ship > Address book > Sender angelegt. Wenn in simplebis eine ShipperRef eingetragen ist, sendet simplebis diese Referenz an DHL und DHL verwendet die im Geschäftskundenportal hinterlegte Absenderadresse. In diesem Fall müssen die Absenderdetails nicht in jedem Label-Aufruf vollständig mitgegeben werden. Wenn die Referenz falsch geschrieben ist oder im DHL Portal nicht existiert, lehnt DHL den Label-Aufruf mit einem Fehler ab.
Ohne ShipperRef verwendet simplebis die konfigurierte Absenderquelle aus der DHL Integration. Das kann die Umgebung beziehungsweise der Standort sein oder eine eigene Absenderadresse im Bereich Defaults. Eine ShipperRef ist deshalb vor allem sinnvoll, wenn Absenderadressen zentral im DHL Geschäftskundenportal gepflegt werden sollen oder wenn DHL-seitig mehrere geprüfte Absenderreferenzen existieren.
Die Billing Number ist für DHL Labels erforderlich. Sie ist die Abrechnungsnummer eines konkreten DHL Vertragsprodukts und besteht aus EKP, Vertragsverfahren beziehungsweise Produkt und Vertragsbeteiligung. DHL beschreibt sie als 14-stellige Zeichenfolge. In simplebis wird sie ohne Leerzeichen oder Sonderzeichen eingetragen. Aus dem Aufbau 1234567890 53 01 wird also 12345678905301.
Die nötigen Bestandteile kommen aus dem DHL Geschäftskundenvertrag und dem Post & DHL Geschäftskundenportal. Die EKP ist die zehnstellige Kundennummer. Das Vertragsverfahren gehört zum DHL Produkt, zum Beispiel Paket, Paket International oder Kleinpaket. Die Vertragsbeteiligung unterscheidet Varianten, Standorte, Konditionen oder weitere vertragliche Zuordnungen. Wenn unklar ist, welche Billing Number verwendet werden soll, muss dies im Geschäftskundenportal, in den Versand-/Benutzergruppenrechten oder mit dem DHL Ansprechpartner geprüft werden.
In simplebis wird jede Billing Number unter Einstellungen > Integrationen > DHL Parcel DE im Bereich Billing Numbers angelegt. Der interne Key ist frei wählbar, sollte aber stabil und sprechend sein, zum Beispiel paket_de, paket_international oder kleinpaket. Das Label ist die lesbare Bezeichnung im Manager. In Billing Number wird die 14-stellige DHL Nummer eingetragen. Das Produkt sollte zur Billing Number passen, zum Beispiel V01PAK, V53WPAK, V62KP oder V66WPI. Eine Billing Number kann als Standard markiert werden.
Wenn eine bestimmte Versandoption gezielt eine Billing Number nutzen soll, wird deren interner Key in der Versandoption im Feld DHL Billing Number Key eingetragen. Bleibt das Feld leer, verwendet simplebis das Standard-Billing-Profil aus der DHL Integration.
Wichtig ist, dass DHL Produkt, Billing Number und Rechte des verwendeten Geschäftskundenportal-Benutzers zusammenpassen. Der Benutzer muss die Funktion Ship und die jeweilige Billing Number verwenden dürfen. DHL prüft diese Kombination bei der Label-Erstellung; wenn etwas nicht zusammenpasst, wird kein Label erzeugt.
Die DHL App wird im DHL API Developer Portal eingerichtet. Dafür wird zuerst ein Developer-Portal-Account benötigt. Anschließend wird auf der API-Seite DHL Parcel DE Shipping (Post & Parcel Germany) der Button Get Access verwendet oder die API in einer bestehenden App ergänzt. Alternativ kann über das Profilmenü eine App erstellt oder bearbeitet werden; im App-Dialog wird die passende API über Select API hinzugefügt.
Für Tests wird zunächst der Sandbox-Zugriff der API in die App aufgenommen. Aus der App kommen der API-Key und das API-Secret. Der API-Key ist die client_id in simplebis, das API-Secret ist das client_secret in simplebis. Für den Live-Betrieb muss zusätzlich der Production-Zugriff für dieselbe API beantragt beziehungsweise freigegeben werden. Die Produktion wird bei DHL manuell freigegeben und setzt einen passenden DHL Geschäftskundenvertrag voraus. Neu erzeugte API-Keys können laut DHL erst verzögert aktiv werden, teilweise erst zum nächsten Aktivierungszeitpunkt.
Als API-Scope beziehungsweise API-Produkt benötigt simplebis nur DHL Parcel DE Shipping (Post & Parcel Germany). Dieser Zugriff deckt die Erstellung von Sendungen, die Rückgabe von Versandlabels und die für simplebis benötigten Label-Daten ab. Die Authentication API (Post & Parcel Germany) muss nicht separat als eigener Scope beantragt werden; DHL schaltet sie automatisch mit frei, sobald die App Zugriff auf die Parcel DE Shipping API hat.
Weitere DHL APIs wie DHL Parcel DE Returns, DHL Parcel DE Private Shipping, Tracking-APIs oder andere DHL Express/eCommerce APIs werden für den aktuellen simplebis-Workflow zur Erstellung von DHL Labels aus Bestellungen nicht benötigt. Sie sollten nur ergänzt werden, wenn später zusätzliche Funktionen wie Retourenlabels oder separate Tracking-Abfragen umgesetzt werden.
Unabhängig vom Developer-Portal-Zugriff muss im Post & DHL Geschäftskundenportal ein Benutzer mit passenden Rechten vorhanden sein. Für Schnittstellen empfiehlt DHL einen Systembenutzer. Dieser Benutzer muss die Funktion Ship und die verwendeten Billing Numbers beziehungsweise Benutzergruppenrechte nutzen dürfen, weil DHL Produkt, Billing Number und Benutzerberechtigung bei der Label-Erstellung gemeinsam prüft.
DHL Labels werden in der Bestelldetailansicht erstellt. Der Button DHL Label erstellen erscheint, wenn die DHL Integration aktiv ist und die Bestellung noch offene Artikelpositionen hat, deren gewählter Versandprovider dhl ist.
Beim Öffnen des Dialogs schlägt simplebis die noch offenen Mengen je Position vor. Danach werden Gewicht, Billing Number, Produkt, Label-Format und optional Paketmaße geprüft beziehungsweise angepasst. Das Gewicht ist verpflichtend, weil DHL es für die Label-Erstellung benötigt.
Beim Erstellen ruft simplebis die DHL Shipping API auf, speichert das zurückgelieferte Versandlabel als PDF, übernimmt Sendungsnummer und Trackingnummer in die Bestellung und erzeugt zusätzlich einen Lieferschein mit dem konfigurierten Dokumenttyp. In der Bestellung erscheint anschließend der Bereich Sendungen; dort können Label und Lieferschein geöffnet werden.
Wenn die DHL API ein Label erzeugt, der Lieferschein aber nicht erstellt werden kann, wird die Sendung als prüfbedürftig markiert. Wenn kein Label erzeugt werden konnte, wird die Sendung als fehlgeschlagen gespeichert und die Fehlermeldung bleibt an der Sendung nachvollziehbar.
Vor dem Live-Betrieb sollte die Integration zuerst im Sandbox-Modus getestet werden. Danach wird im DHL Developer Portal die Production-Nutzung beantragt beziehungsweise freigegeben. Neu erzeugte API-Keys können laut DHL erst verzögert aktiv werden; bei frisch angelegten Keys sollte deshalb Wartezeit eingeplant werden.
Die in Versandoptionen gepflegten DHL-Produkte müssen zur verwendeten Billing Number passen. Wenn Produkt, Billing Number oder Benutzerrechte nicht zusammenpassen, lehnt DHL die Label-Erstellung ab. Typische Produkte in simplebis sind V01PAK für DHL Paket, V53WPAK für DHL Paket International, V62KP für DHL Kleinpaket und V66WPI für Warenpost International.
Label-Formate sollten nicht nachträglich skaliert werden, weil DHL die maschinelle Lesbarkeit voraussetzt. Wenn ein Druckerformat fest im Geschäftskundenportal hinterlegt ist, kann es als Standard dienen; simplebis kann beim Label-Aufruf aber auch ein explizites Label-Format mitsenden.