wiki:eic_simulator [SLON Knowledge Center]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== 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 [[wiki:eic_transport_order|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 Referenz-Beispiel für die eigene Anbindung. Weitere Informationen zum Test-Client finden Sie unter [[wiki:eic_transport_order|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 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" |

<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, z.B. ''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-solid fa-life-ring">
Für den Zugang zu Simulator, Test-Client und OpenAPI-Spezifikation wenden Sie sich bitte an den SLON Support: [[mailto:info@slon.bz.it|info@slon.bz.it]] oder +39 0471 155 116 0
</callout>

===== Weiterführende Artikel =====

  * [[wiki:eic_intro|Einleitung zum Datenaustausch mit externer Software]]
  * [[wiki:eic_transport_order|Transportbeauftragung über SLON EIC]]
  * [[wiki:eic_list_implemented|Verfügbare SLON EIC Schnittstellen]]