Modul receipt

Im Modul receipt bietet Veloconnect ab der Version 1.3 mit der Belegverwaltung die Möglichkeit, elektronische Geschäftsbelege zu übermitteln.

Dabei ist es unerheblich, ob der Beleg auf eine Bestellung mittels Veloconnect zurückzuführen ist. Es werden somit auch Lieferscheine, Auftragsbestätigungen und Rechnungsinformationen an das Warenwirtschaftssystem des Händlers übergeben, die ihren Ursprung in telefonischen, schriftlichen oder Webshopbestellungen hatten. Für den Händler schließt sich damit eine Lücke, die bisher teils für beträchtlichen manuellen Aufwand sorgte.

Aktuell stehen die folgenden Belege zur Verfügung:

  1. Offer (Angebot)

  2. OrderConfirmation (Auftragsbestätigung)

  3. DeliveryNote (Lieferschein)

  4. InvoiceInformation (Rechnungsinformation)

Die Struktur und Nutzung der einzelnen Belegarten erfolgt immer nach dem gleichen Muster. Zu jeder Belegart X gibt es eine Operation XQuery bestehend aus XQueryRequest und XQueryResponse und eine Operation XDetails bestehend aus XDetailsRequest und XDetailsResponse. Wie üblich leiten die Request- und Response-Element von vct:RequestType und vct.ResponseType ab.

Ein veloconnect-Server, der die Belegart X unterstützt muss also die beiden Operationen XQuery und XDetails umsetzten und entsprechend in seinem Profil veröffentlichen.

Die folgende Abbildung zeigt schematisch eine Abfolge der einzelnen Schritte auf Client und Server bei der Abfrage von Belegen.

Es ist aber nicht zwingend, dass für einen DetalsRequest vorher ein QueryResponse ausgewertet werden muss. Z.B. sind in den Daten eines DetailsResponse Bezüge auf andere Belege enthalten, diese können dann direkt verwendet, um die enstprechenden Details dieser verknüpften Belege abzufragen.

1. QueryRequest

Der Veloconnect-Client nutzt das Element QueryRequest, um Kopfdaten zur jeweiligen Belegart abzurufen. Als Suchparameter steht immer ein Datumsbereich (DateRangeType) zur Verfügung, bestehend aus FromDate und ThruDate. Dieser Suchparameter bezieht sich immer auf das Belegdatum (IssueDate) der jeweiligen Belegart. Durch Angabe dieses Suchparameters werden alle Belege selektiert, deren Belegdatum größer oder gleich FromDate und kleiner oder gleich ThruDate sind. Da FromDate und ThruDate optionale Angaben sind, findet der Vergleich des Belegdatums nur statt, wenn das entsprechende Element vorhanden ist. Der Fall, dass weder FromDate noch ThruDate vorhanden ist, ist genauso zu behandeln, wie der Fall, dass kein DateRange angegeben ist.

Bei der Bindung URL(-S) werden die beiden Elemente FromDate und ThruDate von DateRange als QueryParameter FromDate und ThruDate serialisiert.

Je nach Belegart gibt es noch weitere spezifische Suchparameter, bei denen es sich jeweils um IDs verknüpfter Belege handelt. Diese Suchparameter sind so zu verstehen, dass in den entsprechenden Feldern der Belege eine Volltextsuche stattfindet.

Somit übermittelt also jeder QueryRequest eine – evtl. leere – Liste von Suchparametern.

Beispiel: Über das Element OfferQueryRequest ruft der Veloconnect-Client alle durch den Veloconnect-Server bereitgestellten Angebote für den autorisierten Client ab.

2. QueryResponse:

Der Veloconnect-Server liefert über das Element QueryResponse alle Kopfdaten zu Belegen der jeweiligen Belegart, für die mindestens einer der in der Query übermittelten Suchparameter zutrifft. .

Der Server darf die Liste der zurückgelieferten Kopfdaten limitieren. Wenn eine Limitierung stattfindet, muss der Server im QueryResponse einen DateRange mitteilen und sicherstellen, dass für den mitgeteilten DateRange im Response das Suchergebnis anhand der Suchparameter vollständig ist.

Der DateRange im Response muss im DateRange der Query enthalten sein, sofern die Query einen DateRange angegeben hat, ansonsten muss dieser Bereich bis zum aktuellen Datum reichen.

Sofern es nicht wirklich triftige Gründe gibt, muss die Limitierung so beschaffen sein, dass der Zeitbereich mindestens 3 Monate umfasst oder die Anzahl der Kopfdaten mindestens 200 Elemente enthält.

Beispiel: Über das Element OfferQueryResponse liefert der Server alle verfügbaren Angebote für den autorisierten Client aus und reagiert damit auf die Anfrage, die dieser Client mit dem Element OfferQueryRequest ausgeführt hat.

3. DetailsRequest:

Der Veloconnect-Client nutzt die durch den Server bereitgestellten IDs von Belegen aus der Operation QueryResponse, um die Detailwerte zu diesen Beleg-IDs abzufrufen.

Beispiel: Über das Element OfferDetailsRequest ruft der Client per ID die dazugehörigen Detailwerte zu einem Angebot ab.

4. DetailsResponse:

Der Veloconnect-Server liefert über das Element DetailsResponse alle Details zu der im DetailsRequest übermittelten Liste von IDs. Der Server kann die zurückgegebene Liste limitieren, sofern die Liste im Request mehr als 200 Elemente enthält.

Beispiel: Über das Element OfferDetailsResponse liefert der Server alle Details eines einzelnen Angebots.