Presse
myfactory Online-Hilfe

Inhalt

So binden Sie die Shipcloud-Versandschnittstelle korrekt an die myfactory an

In diesem How-To-Kapitel erklären wir Ihnen Schritt für Schritt, wie Sie die einheitliche Versandschnittstelle Shipcloud mit dem myfactory-System verzahnen können. Hierzu zeigen wir Ihnen, wie Sie die grundlegende Konfiguration für die Shipcloud-Anbindung mithilfe eines API-Schlüssels vornehmen, die benötigten Versandtemplates einrichten und die Versandarten korrekt mit dem Verpackungsdialog der Belegerfassung verknüpfen.

So konfigurieren Sie die myfactory für die Anbindung der Shipcloud-Schnittstelle
So legen Sie Shipcloud-Versandtemplates an
So verknüpfen Sie die myfactory-Versandarten mit den Shipcloud-Services
So erzeugen Sie Shipcloud-Paketscheine


shipcloud API

Die Shipcloud-API ist eine einheitliche REST-Versandschnittstelle, die Unterstützung für mehrere Versanddienstleister bietet. Standardmäßig lassen sich DHL, DPD, UPS und GLS mit einer einzigen Schnittstelle an die myfactory anbinden. Abhängig von Ihrem individuellen Bedarf können Sie natürlich auch eigene Tarifmodelle mit alternativen Anbietern wie Hermes und Deutsche Post auswählen und anbinden. Weitere Informationen erhalten Sie auf der Shipcloud-Homepage.

In diesem Shipcloud-Konfigurationsdialog nehmen Sie nun die grundlegenden Einstellungen für die korrekte Funktionsweise der Shipcloud-API vor. Dieser ist derzeit in drei aufklappbare Bereiche unterteilt. Von Bedeutung sind dabei insbesondere der oberste Bereich zum Anmelden an und Verbinden mit der Schnittstelle sowie der unterste Bereich zum Konfigurieren der Trackingstatus-Updates.

Shipcloud-API 0

shipcloud Login

In diesem Bereich können Sie sich mit der Shipcloud-API verbinden und die verfügbaren Versanddienstleister samt der von diesen angebotenen Versandprodukte in die myfactory einlesen.

Während die im Eingabefeld "Name" eingetragene Zeichenkette fest hinterlegt ist, ist die nebenstehende Bezeichnung frei wählbar. Das zentrale Element in diesem Bereich ist jedoch der API-Schlüssel, der in das zugehörige Eingabefeld "API-Key" einzutragen ist.

Um diesen zu erhalten, müssen Sie sich zunächst auf der Shipcloud-Website unter shipcloud.io für einen Live-Account registrieren. Möchten Sie die Versandschnittstelle erst einmal testen, können Sie sich auch für einen kostenlosen Entwickler-Account mit angebotenem Sandbox-Modus (Developer Plan) entscheiden. Dazu rufen Sie bitte die Website developers.shipcloud.io auf und führen gemäß den dort vorgegebenen Schritten die Registrierung durch.

Shipcloud-API 1

Nach der erfolgten Registrierung erhalten Sie über Ihren Account auf dem Shipcloud-Webportal automatisch den für die Schnittstellenanbindung notwendigen API-Schlüssel. Zu diesem gelangen Sie, indem Sie im rechten oberen Bereich des Portals auf das "Zahnrad"-Icon mit Ihrer dort angezeigten Anmelde-E-Mail-Adresse klicken und im sich dann aufklappenden Menü den Eintrag "API-Schlüssel" auswählen.

Shipcloud-API 2

Als zahlender Kunde stehen Ihnen anschließend sowohl der reguläre API-Key für den Live-Betrieb als auch der zum Testen nötige API-Schlüssel für die Sandbox zur Verfügung. Voraussetzung für den Erhalt eines Live-API-Schlüssels ist das Hinterlegen einer Rechnungsadresse im Shipcloud-System. Im kostenfreien Sandbox-Modus lässt sich nur der entsprechende Sandbox-API-Schlüssel nutzen. Kopieren Sie sich den für Ihre jeweiligen Zwecke benötigten API-Key im Anschluss in die Zwischenablage und von dort in das API-Key-Feld im Shipcloud-Login-Bereich der myfactory.

Nach dem Eintragen des korrekten API-Keys können Sie mit den Shipcloud Services einmalig die benötigten Grunddaten per Klick auf die entsprechende [ Herunterladen ]-Schaltfläche downloaden. Damit integrieren Sie die abhängig von API-Key und Tarifmodell verfügbaren Versandanbieter sowie deren individuelle Versandservices automatisch in die myfactory-Oberfläche. Als weitere Parameter werden mit den Shipcloud Services z.B. auch dienstleisterspezifische Pakettypen und Versandlabelformate für die PDF-Paketscheine (z.B. ups_express_1200 -- zpl2_4x6in_203dpi) in das System eingelesen.

Labelformate für PDF-Paketscheine konfigurieren

Aktuell kann die Darstellung der PDF-Paketscheinlabels (hier: primär A5/A6) ausschließlich innerhalb der Shipcloud-Oberfläche konfiguriert werden. Dazu navigieren Sie in Ihrem Shipcloud-Account bitte zum Menü "Einstellungen" und klicken dort den Menüpunkt "Label konfigurieren" an. In einer Matrix können Sie diese Versandmarken dort pro Versanddienstleister und Versandservice anpassen.

Shipcloud-API 3

Wie oben bereits angerissen, hängen die integrierbaren Services auch immer vom jeweiligen API-Key ab, für den Sie registriert und freigeschaltet sind. Verwenden Sie den Sandbox-Modus, so stehen Ihnen standardmäßig z.B. die Versanddienstleister DHL, DPD, UPS und GLS einschließlich ihrer Versandprodukte zur Verfügung.

shipcloud Allgemeine Einstellungen

In diesem Bereich können Sie einen maximal 35 Zeichen umfassenden Referenztext für Paketscheine an die Shipcloud-Schnittstelle übergeben, welcher dann anstelle des Belegreferenztextes übermittelt wird. Dies ermöglicht die Ausgabe variabler Beleginformationen mithilfe der folgenden Platzhalter:

$OrderNumber$: Belegnummer
$CustomerNumber$: Kundennummer
$ReferenceText$: Individueller Referenztext für Paketscheine

shipcloud Trackingstatus

Shipcloud benötigt die Angabe einer von außen erreichbaren SSL-Webseite, an die die Schnittstelle automatisch getriggerte Trackingstatus-Updates in Form von Push-Benachrichtigungen übermitteln kann.

In diesem Bereich können Sie eine entsprechende URL konfigurieren und diese für einen sogenannten Webhook registrieren. Mit der Webhook-Registrierung werden sämtliche Änderungen bezüglich des Shipcloud-Trackingstatus automatisiert über die angegebene Webhook-URL an die myfactory übermittelt.

In Ihrem Shipcloud-Account (unter "Einstellungen / Webhooks / Abonnierte Events") wird diese Webhook-Adresse nach der myfactory-Registrierung ebenfalls hinterlegt. Dies ermöglicht es Ihnen, die Tracking-Ereignisse bei Bedarf an dieser Stelle noch granularer einzustellen bzw. anzupassen. Falls Sie in Ihrem Shipcloud-System also nicht gezielt ein Event per Checkbox aktivieren (z.B. "Paket zugestellt" / "shipment.tracking.delivered"), dann werden pauschal alle Tracking-spezifischen Ereignisse (Tracking*) per Webhook getriggert und an die in der myfactory angegebene URL übertragen, sobald ein Trackingstatus-Update im Shipcloud-System vorliegt.

Shipcloud-API 4

Hintergrund: Was ist ein Webhook?

Anders als bei API-Aufrufen müssen bei dem Einsatz von Webhooks nicht permanent Abfragen im Hintergrund ablaufen, welche womöglich nicht einmal neue Daten liefern. Webhooks haben vielmehr den Vorteil, dass sie automatisch auf bestimmte definierte Ereignisse reagieren, d.h. wenn ein Ereignis auf dem einen Server auftritt, dann soll dies automatisch ein Ereignis auf einem anderen Server auslösen ("Wenn Ereignis X auftritt, dann schicke Daten an mf-schneider/myfactory62/Services/shipcloud.aspx.?foobar-daten").

Bezogen auf die myfactory bedeutet dies, dass Sie in Ihrem Shipcloud-Account z.B. bestimmte Events wie "In Zustellung" ("shipment.tracking.out_for_delivery") anhaken können, damit solche Änderungen des Trackingstatus automatisch als Push-Benachrichtigung per Webhook an die hinterlegte URL übermittelt werden. Diese Updates werden dann von der myfactory abgefragt, im System gespeichert und dort innerhalb der Spalte "Trackingstatus" im Dialog "Datenübertragung" der Versandschnittstelle angezeigt (funktioniert aktuell ausschließlich im Live-Modus).

So ermöglichen Sie es sich und Ihren Anwendern, per Push-Benachrichtigung stets über den aktuellen Versandstatus informiert zu sein.


Zum Anfang

Shipcloud Versandvorlagen

Nachdem Sie in der Versandschnittstellenkonfiguration den API-Schlüssel eingegeben und die verfügbaren Grunddaten (Shipcloud Services) - unter anderem Versandservices, Pakettypen, Versandlabelformate - zu jedem Versanddienstleister heruntergeladen haben, können Sie nun Ihre für die Paketabwicklung benötigten Shipcloud-Versandvorlagen erstellen. Diese dienen der Konfiguration und Zuordnung der Versandservices zu einer Versandart. Dementsprechend sind sie nach ihrer Einrichtung auch pro Versandart im Versandartenstamm zu hinterlegen. Mit Ausnahme von DPD muss für jeden Versanddienstleister ein solches Versandtemplate angelegt werden.

Shipcloud-API 5

Versandvorlage

Tragen Sie hier den internen Namen für Ihr Versandtemplate ein. Dieses Kürzel kann nach Speichern des Datensatzes nicht mehr geändert werden.

Bezeichnung

Hier können Sie einen individuellen und sinnigen Namen für Ihr Versandtemplate hinterlegen.

Inaktiv

Wenn Sie hier das "Inaktiv"-Kennzeichen setzen, dann wird die betreffende Versandvorlage ausgeblendet und es kann standardmäßig nicht mehr verwendet werden.

Drucker

Hinterlegen Sie hier den exakten Namen Ihres Netzwerk-Druckers, so wird diesem über den im Hintergrund laufenden Serverdruck-Dienst ein XML-basierter Druckauftrag gesendet und der PDF-Paketschein direkt bei dessen Erstellung in der Verkaufsbelegerfassung ausgedruckt. Unterstützt werden alle über Ihr Netzwerk erreichbaren Drucker sowie Etikettendrucker.

Versanddienstleister

Mit dieser Dropdown-Liste geben Sie an, welcher Versanddienst Ihrem Versandtemplate zugrunde liegen soll (z.B. DHL, DPD, GLS oder UPS). Die hier verfügbaren Versanddienstleister sind jene, die Sie im Konfigurationsdialog zusammen mit anderen Shipcloud-Parametern wie den unten auswählbaren Versandservices oder den Pakettypen als Shipcloud Services in die myfactory eingelesen haben (siehe auch Hilfekapitel Shipcloud-API).

Welche Versanddienstleister Ihnen in dieser Auswahlbox zur Verfügung stehen, ist stets abhängig von Ihrem hinterlegten API-Schlüssel. Dieser wiederum hängt von dem von Ihnen gewählten Tarifmodell und den mit Shipcloud getroffenen Vereinbarungen ab.

Service

Hier sehen Sie alle Versandservices, die von dem oben ausgewählten Versanddienstleister angeboten und abhängig von diesem hier angezeigt werden. Ein Versandservice ist eine anbieterabhängige Dienstleistung wie z.B. "UPS Express 12:00" oder "DHL Warenpost".

Pakettyp

In diesem Bereich können Sie die versanddienstleisterspezifischen und von Ihrem API-Key abhängigen Pakettypen auswählen, die mit dem Herunterladen der Shipcloud Services ebenfalls in die myfactory übertragen werden. Die Auswahlbox listet dabei alle zum jeweiligen Versanddienstleister und Versandservice gehörigen Paketarten auf.

Intern werden diese heruntergeladenen Pakettypen bei der Erstellung des Paketscheins im Verpackungsdialog mit den individuell zu definierenden myfactory-Verpackungstypen verknüpft.

Abweichender Absender

Mit dieser Option können Sie eine alternative Absenderadresse definieren, die dann priorisiert herangezogen wird. Ist hier keine abweichende Absenderadresse angegeben, so wird diese aus den Grundlagenoptionen ("Administration / Grundlagen / Register Allgemein") oder dem Betriebsstättenstamm ("Stammdaten / Grundlagen / Allgemein / Betriebsstätten / Register Adresse") herangezogen.

Zuständiger Mitarbeiter (Pflicht bei UPS)

In diesem Eingabefeld hinterlegen Sie für UPS-spezifische Versandprozesse bitte einen Mitarbeiter, der dem Versanddienstleister als Kontaktperson für die Paketabholung mitgeteilt wird.


Zum Anfang

myfactory-Versandarten mit den Shipcloud-Services verknüpfen

Im nächsten Schritt ordnen Sie die soeben erstellte Versandvorlage einer passenden Versandart zu und hinterlegen als Versandschnittstelle entsprechend "Shipcloud". Damit stellen Sie vor allem sicher, dass Sie im weiteren Verlauf die in die myfactory eingelesenen Shipcloud Services-Grunddaten für das Erzeugen von Shipcloud-Paketscheinen nutzen können. Außerdem hat dies den Vorteil, dass Sie diese beiden grundlegenden Informationen nur einmal pro Versandart hinterlegen, und nicht für jedes Paket einzeln im Verpackungsdialog eingeben müssen (siehe auch das folgende Unterkapitel).

Shipcloud-API 6

Shipcloud-Paketscheine erzeugen

Anders als bei der DPD-Versandschnittstelle lassen sich Paketscheine mit der Shipcloud API nur aus dem Verpackungsdialog in der Verkaufsbelegerfassung (oder Schnellerfassung) heraus erstellen.Verpackungsmaße (Länge x Breite x Höhe) und Verpackungsinformationen (z.B. zum Verpackungstyp) werden zwingend benötigt. Alternativ können Sie die Shipcloud-Paketscheine auch über die Versandschnittstelle im Dialog "Datenübertragung" erzeugen und hierüber direkt an Shipcloud übermitteln.

Für beide Generierungsarten gilt im Übrigen, dass stets eine mit der Shipcloud API verknüpfte Versandart in den Belegdetails eines Versandauftrags bzw. Lieferscheins hinterlegt sein muss (d.h. im Versandartenstamm ist als Versandschnittstelle für die jeweils gewünschte Versandart zwingend "shipcloud" auszuwählen). Andernfalls kann kein Paketschein über die Schnittstelle übertragen werden.

Shipcloud-API 7

Zum Anfang

Szenario 1: Paketscheine im Verpackungsdialog erstellen

Shipcloud-Paketscheine lassen sich sowohl über die Verkaufsbelegerfassung als auch über die Verkaufsschnellerfassung erstellen. In beiden Erfassungsdialogen klicken Sie zu diesem Zweck die [ Beleg ]-Schaltfläche an und wechseln im sich öffnenden Menü zum Menüpunkt "Verpackungsdialog".

Shipcloud-API 8

Daraufhin wird der Beleg-Einzelverpackungsdialog geöffnet. Nach dem Auswählen Ihres gewünschten Verpackungstyps legen Sie Ihr Augenmerk bitte zunächst auf den rechten oberen Dialogabschnitt mit der Überschrift "Verpackung Details".

Shipcloud-API 9

Haben Sie im Belegkopf (den Belegdetails) noch keine mit Shipcloud verknüpfte Versandart hinterlegt, so tragen Sie diese bitte noch in das Eingabefeld "Versandart der Verpackung" ein, um die restlichen Verpackungsdetails freizuschalten. Vergessen Sie nach Beendigung des Verpackungsdialogs jedoch nicht, die Versandart in den Belegdetails nachzutragen. Andernfalls wird der erzeugte Paketschein nicht über die Shipcloud-Schnittstelle übertragen.

Sofern Sie vor Bearbeitung des Verpackungsdialogs bereits eine Versandart im Belegkopf hinterlegt haben, so ist die Versandart der Verpackung in den Verpackungsdetails bereits vorbelegt und die übrigen Verpackungsdetails schon zur weiteren Bearbeitung freigeschaltet.

Shipcloud-API 10

Nach dem Eintragen der Verpackungsversandart können Sie sich über die Schaltfläche [ Preisvorschlag (netto) ] noch einen "Kostenvoranschlag" für Ihr zu versendendes Paket einholen.

Damit werden die bei der Versandart hinterlegte Versandvorlage, das Gewicht sowie die allgemeinen Verpackungsdaten zur Berechnung der geschätzten Nettokosten an Shipcloud übergeben. Der voraussichtliche Preis wird anschließend automatisch in das nebenstehende Feld geschrieben. Bitte beachten Sie, dass hierbei noch kein Paketschein erstellt wird. Die dem verwendeten Verpackungstyp zugeordneten Verpackungsmaße (Länge x Höhe x Breite) sollten ferner in ganzen cm angegeben werden.

Shipcloud-API 11

Im Anschluss haben Sie im unteren Dialogbereich die Möglichkeit, eine oder mehrerer Ihrer Belegpositionen Ihrem oben gewählten Verpackungstypen zuzuordnen. Dem in dem Feld "Gesamtgewicht in kg" vorbelegten Gewicht des jeweiligen Verpackungstypen wird in den Verpackungsdetails automatisch das Gesamtgewicht der unten selektierten Artikelpositionen hinzuaddiert und eingetragen.

Shipcloud-API 12

Nun haben Sie alle nötigen Einstellungen getroffen, um mit dem Erstellen des Paketscheins fortzufahren. Anders als bei der DPD-Schnittstelle ist es aktuell nicht möglich, einen oder mehrere Paketscheine für den gesamten Beleg zu erzeugen. Vielmehr lassen sich derzeit ausschließlich Paketscheine für einzelne Verpackungen generieren. Betätigen Sie daher bitte die entsprechende Schaltfläche zum Erstellen eines Verpackungspaketscheins.

Shipcloud-API 13

Ist dies geschehen, so wird automatisch das Feld "Paketversandnummer" mit der Trackingnummer für die Sendungsverfolgung eingetragen. Zudem wird das Versanddatum mit Uhrzeit in das entsprechende Feld der Verpackungsdetails geschrieben.

Shipcloud-API 14

Anschließend können Sie den Verpackungsdialog mit der [ Schließen ]-Schaltfläche verlassen und den erzeugten Paketschein im Bereich der Belegdokumente einsehen, herunterladen und bei einem dem Versandtemplate zugeordneten Druckernamen entsprechend auch ausdrucken.

Shipcloud-API 15

Shipcloud-API 16

Auch in der Shipcloud-Oberfläche können Sie erkennen, dass z.B. im Bereich des Dashboards ein Versandlabel (also ein Paketschein) übertragen wurde. Alternativ ist dies auch im Menüpunkt "Sendungen" nachverfolgbar.

Shipcloud-API 17

Öffnen Sie den Detailbereich eines übermittelten Paketscheins, so sehen Sie dort alle Einzelheiten zu dem zugehörigen Versandprozess, unter anderem auch die Trackingnummer.

Shipcloud-API 18

Im Dialog "Datenübertragung" (unter "Verkauf / Kommissionierung / Versandschnittstelle / Datenübertragung") können Sie unter "Versanddienstleister" nun auf die "Shipcloud API" filtern und anhand der neben der Spalte "Trackingnummer" befindlichen "Trackingstatus"-Spalte per Webhook ausgelöste Tracking-Ereignisse nachvollziehen (mehr dazu im folgenden Unterkapitel).

Zum Anfang

Szenario 2: Paketscheine in der Versandschnittstelle erzeugen

Wenn die Paketdaten im Beleg hinterlegt sind, dann können Sie die Paketscheine auch direkt über den Dialog "Datenübertragung" der Versandschnittstelle an Shipcloud übertragen.

Zu den im Lieferschein zu hinterlegenden Paketdaten zählen insbesondere die Shipcloud-kompatible Versandart im Belegkopf sowie der im Verpackungsdialog gewählte Verpackungstyp. Haben Sie Letzteren im Verpackungsdialog ausgewählt und zugeordnet, so klicken Sie anstelle der Schaltfläche [ Verpackungspaketschein ] einfach auf [ Schließen ].

Nun sehen Sie im Dialog "Datenübertragung" im Bereich "Versandschnittstelle" sämtlich erstellte Paketscheine. Über die Auswahlbox "Anzeige" können Sie sich aus Gründen der Übersichtlichkeit nur die "Nicht übergebenen" Paketscheine anzeigen lassen.

Die einer Versandart und einem Verpackungstyp zugeordneten Paketscheine sind dann zur Übermittlung an Shipcloud bereit. Für den Schnittstellentransfer haken Sie bitte die die Checkbox in der Splte "Übergeben" an und klicken anschließend auf die [ Übertragen ]-Schaltfläche in der rechten unteren Button-Leiste.

Shipcloud-API 19

Nach Betätigen dieser Schaltfläche gelangen Sie automatisch in den Dialog "Versandprotokoll", den Sie auch jederzeit manuell über den Menüpfad "Verkauf / Kommissionierung / Versandschnittstelle / Verdsandprotokoll" erreichen können.

Hier können Sie sämtliche Informationen zu der Übertragung des Paketscheins noch einmal nachvollziehen. In dem Screenshot-Beispiel war die Erstellung und Übermittlung des Paketscheins erfolgreich, wie sich anhand der "Message"-Spalte feststellen lässt. Außerdem ist hier erkennbar, dass eine Trackingnummer erzeugt wurde.

Shipcloud-API 20

Wechseln Sie anschließend zurück in den Dialog "Datenübertragung", so werden Sie feststellen, dass Trackingnummer dort ebenfalls automatisch in die zugehörige Spalte eingetragen wurde.

Auf Basis dieser Trackingnummer wird der Trackingstatus dann per Webhook aktualisiert. Bitte beachten Sie diesbezüglich, dass der Trackingstatus sich in der Shipcloud-API ausschließlich via Webhook abrufen lässt. Das heißt, ein manueller Abruf über die Schaltfläche [ Trackingstatus ] in der rechten unteren Toolbar bzw. Buttonleiste ist anders als bei DPD dann nicht möglich. Dies hat jedoch den Vorteil, dass der Trackingstatus stets automatisch (und anhand der günstigsten Tarifvariante) aktualisiert wird.

Ähnlich wie bei DPD können Sie sich per Rechtsklick auch die "Tracking-Detailinfos" über den gleichnamigen Kontextmenüeintrag einholen, um sich genauere Informationen zum Zustellstatus eines Pakets anzeigen zu lassen (z.B. wann wo ein Paket angekommen ist).

Shipcloud-API 21

Nur serielle Übertragung von Paketscheinen über die Schnittstelle möglich:

Aktuell ist es nicht möglich, mehrere Paketscheine in einer Mehrfachauswahl zu selektieren und parallel an Shipcloud zu übertragen. Diese können nach jetzigem Stand immer nur einzeln (d.h. hintereinander) übermittelt werden.

Auf diese Weise erzeugte Paketscheine sind dann ebenfalls im Dashboard (oder unter "Sendungen“; siehe folgende Screenshots) einsehbar.

Shipcloud-API 22

Shipcloud-API 23

Zum Anfang

© myfactory International GmbH 2021. Alle Rechte vorbehalten.

Über uns

myfactory ist die webbasierte Business Software für KMU in den Bereichen ERP, CRM, PPS, MIS, Portal, Shop, Groupware und Finanzbuchhaltung.

Kontakt

Agnes-Pockels-Bogen 1
D-80992 München

21.01.2022
11.05.2021
06.05.2021
04.05.2021
27.04.2021