Dies ist eine alte Version des Dokuments!
Lokaler Simulator und empfohlenes Vorgehen bei der Anbindung
Für die Entwicklung einer Anbindung an SLON EIC steht ein lokaler Simulator zur Verfügung. Damit kann ein externes System die komplette Schnittstelle durchlaufen, ohne dass ein installierter SLON EIC, Zugangsdaten zur SLON Plattform oder eine Verbindung zur SLON Plattform notwendig sind.
Dieser Artikel beschreibt den Simulator und das von SLON empfohlene dreistufige Vorgehen bei der Anbindung eines ERP-Systems. Den Ablauf der Transportbeauftragung selbst finden Sie unter Transportbeauftragung über SLON EIC.
WICHTIG – Simulation
Der Simulator arbeitet ausschließlich mit angenommenen Daten. Preise, Transportnummern, Etiketten, Lieferscheine und Referenzdaten sind erfunden und entsprechen nicht den Echtdaten auf der SLON Plattform. Der Simulator ist eine Entwicklungsumgebung und keine Abnahmeumgebung.Was der Simulator abbildet
Der Simulator bildet die Schnittstelle nicht nach, sondern verwendet dieselben Programmbausteine wie der echte SLON EIC. Simuliert wird ausschließlich das Verhalten der SLON Plattform dahinter.
| Bestandteil | Im Simulator |
|---|---|
| Endpunkte, Zugriffsschutz per Schlüssel, Fehlermeldungen | echt – identisch zum SLON EIC |
| Prüfung und Umsetzung der übergebenen Daten | echt – identisch zum SLON EIC |
| Format von Statusabfrage und Webhook | echt – identisch zum SLON EIC |
| Verhalten der SLON Plattform dahinter | simuliert |
Dadurch ist sichergestellt, dass eine gegen den Simulator entwickelte Anbindung denselben Vertrag verwendet wie eine Anbindung an den echten SLON EIC.
Empfohlenes Vorgehen in drei Phasen
SLON empfiehlt, die Anbindung eines ERP-Systems in drei aufeinander aufbauenden Phasen umzusetzen. Jede Phase setzt voraus, dass die vorhergehende erfolgreich abgeschlossen wurde.
Phase 1 – Prozess explorativ kennenlernen
┌─────────────┐ ┌────────────────────────────┐
│ Test-Client │ ───► │ Simulator │
└─────────────┘ │ angenommene Daten │
└────────────────────────────┘
Phase 2 – Anbindung programmieren und testen
┌─────────────┐ ┌────────────────────────────┐
│ ERP-System │ ───► │ Simulator │
└─────────────┘ │ angenommene Daten │
└────────────────────────────┘
Phase 3 – Abnahme gegen die SLON Plattform
┌─────────────┐ ┌───────────┐ ┌────────────────┐
│ ERP-System │ ───► │ SLON EIC │ ───► │ SLON Plattform │
└─────────────┘ └───────────┘ │ Echtdaten │
└────────────────┘
Phase 1: Prozess explorativ kennenlernen
Aufbau: Test-Client → Simulator
In der ersten Phase wird der gesamte Prozess mit dem Test-Client durchgespielt, noch ohne eine Zeile Programmcode im ERP-System. Ziel ist, den Ablauf und die ausgetauschten Daten zu verstehen.
- Starten Sie den Simulator.
- Starten Sie den Test-Client und richten Sie ihn auf die Adresse des Simulators.
- Durchlaufen Sie einen vollständigen Transportauftrag: Erfassung, Senden, Preisabfrage, Bestätigung, Statusverfolgung und Etikett-Download.
- Aktivieren Sie im Test-Client die Klartext-Ausgabe der Aufrufe, um Request und Response jedes Schritts nachzuvollziehen.
Hinweis
Der Test-Client ist von SLON EIC unabhängig und spricht denselben Vertrag wie ein externes System. Er eignet sich daher als Referenz-Beispiel für die eigene Anbindung. Weitere Informationen zum Test-Client finden Sie unter Transportbeauftragung über SLON EIC.Phase 2: Anbindung programmieren und testen
Aufbau: ERP-System → Simulator
In der zweiten Phase wird die Anbindung im ERP-System entwickelt und gegen den Simulator getestet. Da keine Verbindung zur SLON Plattform besteht, können Sie beliebig oft testen, ohne Transportaufträge auf der Plattform zu erzeugen.
- Richten Sie das ERP-System auf die Adresse des Simulators.
- Entwickeln und testen Sie den vollständigen Ablauf inklusive Bestätigung und Statusverfolgung.
- Testen Sie gezielt auch die Fehlerfälle (siehe Abschnitt „Fehlerfälle gezielt auslösen„).
Angenommene Daten
Alle Rückgaben des Simulators sind angenommene Werte. Insbesondere sind die zurückgegebenen Preise, Transportnummern und die IDs von Logistiknetzwerken, Lagereinheiten und Transportoptionen erfunden. Übernehmen Sie diese IDs niemals fest in Ihr ERP-System – die SLON Plattform vergibt andere. Fragen Sie die gültigen IDs immer über die entsprechenden Endpunkte ab.Phase 3: Abnahme gegen die SLON Plattform
Aufbau: ERP-System → SLON EIC → SLON Plattform
Erst wenn in Phase 2 alle Tests erfolgreich sind, erfolgt der Test gegen die echte Umgebung. Dazu wird der Simulator durch einen installierten SLON EIC mit Verbindung zur SLON Plattform ersetzt.
- Installieren und konfigurieren Sie SLON EIC mit den von SLON bereitgestellten Zugangsdaten.
- Richten Sie das ERP-System auf die Adresse des SLON EIC.
- Führen Sie einen vollständigen Abnahmelauf durch.
Phase 3 ist verpflichtend
Ein erfolgreicher Test gegen den Simulator ersetzt die Abnahme gegen die SLON Plattform nicht. Erst in Phase 3 werden echte Adressprüfung, echte Preisberechnung und die tatsächliche Abarbeitung des Transportauftrags durchlaufen. Planen Sie diese Phase fest ein.Was der Simulator nicht abbildet
Die folgenden Punkte werden vom Simulator bewusst nicht nachgebildet und können ausschließlich in Phase 3 geprüft werden:
- Adressprüfung und Geokodierung – ob eine Adresse tatsächlich in die Datenkontrolle gelangt, entscheidet erst die SLON Plattform.
- Preisberechnung – der Preis des Simulators ist ein fester, angenommener Wert.
- Aufteilung und Routenplanung des Transportauftrags.
- Gültigkeit der IDs von Logistiknetzwerken, Lagereinheiten und Transportoptionen.
- Inhalt von Barcode-Etikette und Lieferschein – der Simulator liefert Platzhalter-Dokumente ohne Barcode. Diese sind nicht scannbar und dürfen nicht produktiv verwendet werden.
Fehlerfälle gezielt auslösen
Für eine belastbare Anbindung ist es wichtig, nicht nur den fehlerfreien Ablauf zu testen. Der Simulator kann die relevanten Fehler- und Sonderfälle gezielt erzeugen.
Zwei Sonderfälle werden über eine Kennung im Feld externalDocumentId ausgelöst – also in dem Feld, in dem Ihr ERP-System beim Senden des Transportauftrags seine eigene Belegnummer übergibt. Es genügt, wenn die Kennung an beliebiger Stelle im Wert vorkommt; Groß- und Kleinschreibung sind unerheblich. Ihr gewohntes Nummernschema bleibt dadurch erhalten, zum Beispiel ERP-SIM-ROUTEFAIL-3001.
| Situation | Auslöser | Antwort des Simulators |
|---|---|---|
| Datenkontrolle (Quarantäne) | Transportauftrag ohne Koordinaten übergeben | Der Transportauftrag verbleibt zunächst in der Datenkontrolle und wird nicht bepreist |
| Routenberechnung fehlgeschlagen | Kennung SIM-ROUTEFAIL im Feld externalDocumentId | Zustand „Routenberechnung fehlgeschlagen“ |
| Datenkontrolle erzwingen | Kennung SIM-QUARANTINE im Feld externalDocumentId | Datenkontrolle, auch wenn Koordinaten übergeben wurden |
| Fehlender oder falscher Schlüssel | Aufruf ohne gültigen Zugriffsschlüssel | Fehler „nicht autorisiert„ |
| Unvollständige Daten | z. B. Transporteinheit ohne Gewicht | Fehlermeldung mit Begründung |
| Doppelte Übermittlung | Zweimal denselben Wert in externalDocumentId senden | Der Auftrag wird einmalig angelegt, die Wiederholung wird als Dublette erkannt |
| Bestätigung zu früh | Bestätigen, bevor ein Preis vorliegt | Hinweis, dass noch kein Preis zur Bestätigung vorliegt |
| Referenzdaten nicht erreichbar | Entsprechende Startoption des Simulators | Fehler „Referenzdaten nicht verfügbar“ |
Belegnummer beim wiederholten Testen variieren
Das FeldexternalDocumentId dient zugleich als Schlüssel gegen Doppelerfassung. Senden Sie denselben Wert ein zweites Mal, wird der Transportauftrag als Dublette erkannt und das gewünschte Szenario nicht ausgelöst. Verwenden Sie beim wiederholten Testen daher jeweils einen neuen Wert, etwa mit fortlaufender Nummer.
Datenkontrolle im Simulator
Auf der SLON Plattform wird ein Transportauftrag in der Datenkontrolle manuell in der Web-App korrigiert. Da der Simulator keine Web-App besitzt, gibt er den Transportauftrag nach einer einstellbaren Wartezeit automatisch frei. Das Verhalten weicht hier bewusst vom Echtsystem ab.Bezug und weitere Unterlagen
Der Simulator wird zusammen mit dem Test-Client und der OpenAPI-Spezifikation bereitgestellt. Eine ausführliche technische Beschreibung inklusive aller Startoptionen liegt dem Simulator bei.