Beispiele für die Verwendung des egeko-Service per Xml-Schnittstelle

Die Anfragen werden als Xml-Datei zur Beschreibungsdatei Egeko.dtd formuliert. Das root-element einer Anfrage ist der Tag egeko. Die Xml-Dateien, die als Antwort zurückkommen entsprechen ebenso der Beschreibungsdatei Egeko.dtd, das root-element hängt jedoch von der erfolgreichen Durchführung der Anfrage ab. In diesem Abschnitt werden nur die Antworten für die korrekte Durchführung (HTTP-Status 200 und die Anfrage ist für die Argumente möglich) betrachtet.

  1. Nachrichtenoperationen
    Diese Abfragen werden für den Aufruf von Nachrichtenlisten und Einzelnachrichten verwendet.

    1. getClosedMessages.
      Die Abfrage ermittelt alle Nachrichten im Archiv. Bei korrekter Ausführung wird eine Liste der Nachrichtenschlüssel zurückgegeben.
      Die zugehörige Nachricht kann durch die Abfrage getMessageByKey geholt werden. eine Liste der Nachrichtenschlüssel zurückgegeben. Die zugehörige Nachricht kann durch die Anfrage getMessageByKey geholt werden.
    2. getMessageByKey.
      Liste der eingehenden Nachrichten. Nachricht zurückgegeben.
    3. getMessagesByOrder.
      Diese Operation gibt eine Liste der Nachrichten zu einem KV aus. eine Liste der Nachrichtenschlüssel zurückgegeben. Die zugehörige Nachricht kann durch die Anfrage getMessageByKey geholt werden.
    4. getInboxMessages.
      Nachrichten im Posteingang eine Liste der Nachrichtenschlüssel zurückgegeben. Die zugehörige Nachricht kann durch die Anfrage getMessageByKey geholt werden.
    5. getOutboxMessages
      Liste der ausgehenden Nachrichten. eine Liste der Nachrichtenschlüssel zurückgegeben. Die zugehörige Nachricht kann durch die Anfrage getMessageByKey geholt werden.
    6. getInboxUnreadMessages.
      Ungelesene Nachrichten im Posteingang eine Liste der Nachrichtenschlüssel zurückgegeben. Die zugehörige Nachricht kann durch die Anfrage getMessageByKey geholt werden.

  2. Lieferbestätigungsoperationen
    Diese Operationen benötigen einen Login-Context, d.h. sie müssen zwischen login und logout aufgerufen werden.
    Zusätzlich muss beachtet werden, dass der eingeloggte Benutzer nach 30 Min Inaktivität automatisch aus dem egeko abgemeldet wird (session timeout).

    1. abortShipmentOnOrder.
      Auslieferung des Auftrags ist fehlgeschlagen.
    2. confirmShipmentOnOrder.
      Auslieferung des Auftrags wird bestätigt.

  3. Abfragen

    1. getConfirmReadyOrders.
      Liefert eine Liste der neuen Versorgungsaufträge, die vom Kunden zu bestätigen sind.
    2. getConfirmedOrders.
      Diese Abfrage liefert eine Liste der bestätigten Versorgungsaufträge.
    3. getDocumentReadyOrders.
      Diese Operation liefert eine Liste der Versorgungsaufträge, die noch die Angabe von Kostenvoranschlägen benötigen zurück.
    4. getInboxOrders.
      Liefert eine Liste der offenen/aktiven/unbestätigten Versorgungsaufträge, darunter fallen auch die Aufträge, die vom Kostenträger noch zu bestätigen/genehmigen sind.
    5. getShipmentReadyOrders.
      Liefert eine Liste der lieferbereiten Kostenvoranschläge
    6. getSupplyReadyOrders.
      Liefert eine Liste der versorgungsbereiten Kostenvoranschläge
    7. getOrderTemplateSan.
      Gibt einen Versorgungsauftrag in Template- Datenstruktur zurück.
    8. getVersion.
      Die Abfrage ermittelt die aktuelle Schnittstellenversion des XML-Service zurück. Bei korrekter Ausführung dieser Abfrage wird die aktuelle Versionsnummer des egeko XML-Service zurückgegeben. aktuellen Version der xml Schnittstelle zurückgegeben.

    Fehlerbehandlung (Anwenderfehler)

    Der HTTP-Status 200 bei der Datenübermittlung bedeuted, dass die Ansteuerung des Xml-Services generell erfolgreich war.
    Dies schließt allerdings nicht aus, dass die angeforderten Anfrage aus verschiedenen Gründen nicht erfolgreich ausgeführt werden konnte. Im Falle eines Anwendungsfehlers geben die folgenden Rückgaben Begründungen, weshalb eine Anfrage nicht ausgeführt werden konnte:

    Technische Ansteuerung der Xml-Schnittstelle

    Die Kommunikation zu der egeko-xml-schnittstelle erfolgt über eine ssl- verschlüsselte HTTP-Verbindung mit der Methode POST zu der Addresse https://ws.optadata.com/egeko-service-order-v2/xmlservice. Die Kommunikation zur Schnittstelle erfolgt immer in folgenden Schritten:
    1. Aufbau einer Verbindung mit übergabe der Logindaten
    2. Absenden der Anfrage
    3. Auswerten des HTTP-Statuscodes
    4. Bei erfolgreicher Übertragung wird das Antwortdokument ausgelesen
    Im weiteren geben wir einige Beispiele für die Umsetzung der Kommunikationsschnittstelle zum Xml-Service in verschiedenen Programmiersprachen.