myfactory Online-Hilfe
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.
Register "Shipcloud Einstellungen"
In diesem shipcloud-Konfigurationsdialog bzw. in dem Register "Shipcloud Einstellungen" 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 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.
Name / Bezeichnung
Während die im Eingabefeld "Name" eingetragene Zeichenkette fest hinterlegt ist, ist die nebenstehende Bezeichnung frei wählbar.
API-Key
Das zentrale Element in diesem shipcloud Login-Bereich ist der API-Schlüssel, der in das zugehörige Eingabefeld "API-Key" einzutragen ist.
So erhalten Sie den shipcloud API-Key
Um den API-Schlüssel zu erhalten, müssen Sie sich zunächst auf der shipcloud-Website unter shipcloud.com 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.
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.
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 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.
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 Eingabe des API-Keys bitte das Speichern nicht vergessen:
Bitte achten Sie darauf, dass Sie Ihren eingetragenen API-Schlüssel nach dem Hinterlegen auch abspeichern. Wenn Sie dies nicht tun, erhalten Sie bei dem Versuch, im nächsten Schritt die shipcloud Services (siehe nächster Abschnitt) herunterzuladen, eine (etwas kryptische) Fehlermeldung.
shipcloud Services
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.
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
Referenztext
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
Absenderadresse aus shipcloud verwenden
Ist diese Checkbox gesetzt, dann wird immer Ihre in der shipcloud-Oberfläche hinterlegte Versandadresse für Versandaufträge herangezogen. Ist diese Checkbox nicht gesetzt, dann wird standardmäßig eine im System vermerkte Versandadresse verwendet - primär die Adresse, die im Betriebsstättenstamm ("Stammdaten / Grundlagen / Allgemein / Betriebsstätten") oder in den Grundlagenoptionen unter "Administration / Grundlagen / Register Allgemein" hinterlegt ist (und sekundär der Abweichende Absender in den "shipcloud-Versandvorlagen").
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.
Webhook URL
In diesem Bereich können Sie eine entsprechende URL konfigurieren und diese für einen sogenannten Webhook mit dem hier befindlichen und entsprechend benannten Button 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.
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.
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.
Register "Shipcloud Zuordnung"
In diesem Register haben Sie die Möglichkeit, shipcloud-Adressfelder myfactory-Adresskennzeichen zuzuordnen, um fehlende Informationsfelder bzgl. der shipcloud-Adressen im myfactory-System hinterlegen zu können. Dazu definieren Sie zunächst bitte ein entsprechendes Kennzeichen im Kennzeichenstamm (unter "Stammdaten / Grundlagen / Allgemein / Kennzeichen"), markieren das neu angelegte Kennzeichen für die Verwendung mit Adressen und speichern es zum Schluss noch ab. Anschließend finden Sie es in der Dropdown-Liste dieses Registers und können das soeben definierte Kennzeichen für das Mapping auf ein hier hinterlegtes shipcloud-Feld auswählen.
Weitere Informationen zu diesem Thema: