Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- draft:rework:eic:simulator [10.08.2026 23:01] – [DRAFT] Mailto-Fix: DokuWiki setzt das mailto: selbst florian
+++ draft:rework:eic:simulator [10.08.2026 23:01] (aktuell) – Draft published, cleaning up florian
@@ Zeile 1: / Zeile 1: @@
-====== 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 [[rework:eic:transport_beauftragen|Transportbeauftragung über SLON EIC]].
-<callout type="warning" title="WICHTIG – Simulation" icon="true">
-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**.
-</callout>
-===== 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.
-{{draft:wiki:pasted:todo_screenshot_eic_simulator_start.png}}
-===== 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.
-<code>
-  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      │
-                                          └────────────────┘
-</code>
-==== 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.
-<callout type="info" title="Hinweis" icon="true">
-Der Test-Client ist von SLON EIC unabhängig und spricht denselben Vertrag wie ein externes System. Er eignet sich daher als Referenzbeispiel für die eigene Anbindung. Weitere Informationen finden Sie unter [[rework:eic:transport_beauftragen|Transportbeauftragung über SLON EIC]].
-</callout>
-==== 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".
-<callout type="warning" title="Angenommene Daten" icon="true">
-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.
-</callout>
-==== 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.
-<callout type="warning" title="Phase 3 ist verpflichtend" icon="true">
-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.
-</callout>
-===== Was der Simulator nicht abbildet =====
-Die folgenden Punkte werden 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 jenem 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 |zum Beispiel 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" |
-<callout type="warning" title="Belegnummer beim wiederholten Testen variieren" icon="true">
-Das Feld ''externalDocumentId'' 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: ''SIM-QUARANTINE-001'', ''SIM-QUARANTINE-002''.
-</callout>
-<callout type="info" title="Datenkontrolle im Simulator" icon="true">
-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.
-</callout>
-===== 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.
-<callout type="warning" title="Kontaktaufnahme mit SLON" icon="fa fa-life-ring">
-Für den Zugang zu Simulator, Test-Client und OpenAPI-Spezifikation wenden Sie sich bitte an den SLON Support: [[info@slon.bz.it|info@slon.bz.it]] oder +39 0471 155 116 0
-</callout>
-===== Verwandte Artikel =====
-  * [[rework:eic:start|SLON EIC – Datenaustausch mit externer Software]]
-  * [[rework:eic:transport_beauftragen|Transportbeauftragung über SLON EIC]]
-  * [[rework:eic:schnittstellen|Verfügbare SLON EIC Schnittstellen]]