HVS32 PSI REST Schnittstelle (Automatik-Polling)

Aus Wiki - Heidler Strichcode GmbH
Version vom 1. Juni 2022, 14:39 Uhr von Odelice (Diskussion | Beiträge) (Die Seite wurde neu angelegt: „= Voraussetzungen = {| class="wikitable" |- | DGS-Version || 3.8.4 oder höher |- | DGS-Plugins || HVS32Client, PSI-Server |} Die PSI-Schnittstelle ist anhand…“)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)
Zur Navigation springen Zur Suche springen

Voraussetzungen

DGS-Version 3.8.4 oder höher
DGS-Plugins HVS32Client, PSI-Server

Die PSI-Schnittstelle ist anhand den vorgaben der PSI Software AG umgesetzt worden. Zur Umsetzung standen folgende Dokumentationen zur Verfügung:

  • PSIwms WebService Interface, Version 1.2 (26.02.2021)
  • PSIwms Schnittstelle zum Versandsystem, Version 2021 (23.07.2020)

Funktionsbeschreibung

Bei der PSI-REST-Schnittstelle stellt der DataGatewayServer (DGS) einen REST-Server mit nur einer Funktion ( /request ) zur Verfügung. Über diese Funktion kann das PSI-System verschiedene Telegramme übermitteln. Die auszuführende HVS32-Funktion wird dabei über den Parameter MsgNam gesteuert, welcher in jedem Telegram vorhanden ist.

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.

Ablauf

  • Das PSI-System bereitet das Telegramm vor und übermittelt dieses über die REST-Schnittstelle an den DataGatewayServer (DGS)
  • Der DGS quittiert den Erhalt des Telegrammes
  • Im DGS wird das Telegramm für die Verarbeitung im HVS32 vorbereitet. Bei einer Druckanfrage wird jedes Packstück in eine separate Verbuchungsanfrage gesplittet und sequenziell verarbeitet.
  • Bei einer Verbuchungsanfrage werden die Daten im HVS32 zuerst nur verbucht. Es wird noch kein Etikett erzeugt.
  • Bei jeder Anfrage wird geprüft, ob eine HVS32 Station mit dem DGS verbunden ist. Sollte keine Station verbunden sein, so wird die Anfrage mit einem Fehler quittiert und somit auch das komplette Telegramm.
  • Bei einer Verbuchungsanfrage werden alle bereits verbuchten Packstücke aus diesem Telegramm im HVS32 storniert und das Hostsystem mit einer "Alarmmeldung" benachrichtigt.
  • Wenn eine HVS32 Station verbunden ist, so wird die Anfrage an die nächste freie Station weitergeleitet, in welcher die Anfrage verarbeitet wird.
  • Sollte es sich um eine Verbuchungsanfrage handeln und in diesem Prozess ein Fehler auftreten, so werden wie oben beschrieben alle Packstücke aus diesem Telegramm storniert und es erfolgt eine Alarmmeldung.
  • Erst nachdem alle Verbuchungsanfragen erfolgreich verarbeitet worden sind, werden Druckanfragen erzeugt und erneut an das HVS32 gesendet. Erst hier werden die Etiketten gedruckt. Dies verhindert, die Ausgabe von Etiketten, welche im Fehlerfall automatisiert storniert werden müssten.
  • Sollte in diesem Druck-Prozess ein Fehler auftreten, erfolgt eine Alarmmeldung. An dieser Stelle werden keine Packstücke mehr storniert, da diese bereits gedruckt und auf einem Packstück aufgebracht sein könnten.
  • Der DGS sammelt die Rückmeldungen der einzelnen Anfragen innerhalb eines Telegrammes und meldet die Rückmeldedaten aus dem HVS32 gesammelt in dem vorgesehenen Telegramm ans Hostsystem zurück.
  • Sollte die Rückmeldung fehlschlagen, z.B. weil das Hostsystem zu diesem Zeitpunkt nicht erreichbar ist, kann ein entsprechendes Fehlerhandling im DGS getriggert werden. Wie dieses Handling jedoch auszusehen hat, bzw. ob es überhaupt benötigt wird, ist noch unbekannt.

  • Ablauf: PSI-REST Etikettendruck

  • Ablauf: PSI-REST Storno, Verladung, etc.

Notwendige PSI Parameter

Folgende Parameter werden für die Einrichtung der PSI-REST-Schnittstelle benötigt:

Parameter Beschreibung
Port Port, unter welchem der DGS die PSI-REST-Schnittstelle zur Verfügung stellt
PSI-Telegram Versionsnr. Versionsnr., welche vom PSI-System in jedem Telegram als VersionsNr übermittelt wird
REST Endpoint PSI-System REST Endpoint, worüber das PSI-System für die asynchrone Rückmeldung erreichbar ist

Verfügbare HVS32 Funktionen

Artikel-Daten und Gefahrgut-Informationen müssen im Request-XML als eigener Knoten (z.B. PESSGGV) auf gleicher Hirachie-Ebene zu den Packstückdaten übergeben werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.
Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.

Packstück-Verarbeitung (VersandDatenAnfrage) [HCUSAG=1]

Die Gatewayfunktion VersandDatenAnfrage wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort ein Etikett für ein Packstück zu erzeugen und verbuchen. Ein Etikett wird für alle weiteren Funktionen wie Storno, Verladefreigabe, etc. anhand der hostseitigen Packstück-ID identifiziert. Diese wird im Feld PackstueckID übergeben und muss dementsprechend innerhalb des Versandsystems eindeutig sein.

Schnittstellen-Feld-Beschreibung

Packstück verladen/freigeben (VerladeVersandDaten) [HCUSAG=5]

Die Gatewayfunktion VerladeVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort Packstücke für den Ausgang frei zu geben. Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Tagesabschluss berücksichtigt.

Schnittstellen-Feld-Beschreibung

Packstückdaten aktualisieren (UpdateVersandDaten) [HCUSAG=2]

Die Gatewayfunktion UpdateVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort die Daten von bestehende Packstücken zu verändern. Diese Anfrage wird zum Beispiel gesendet, wenn der Warenwert für ein Packstück erst zu einem späteren Zeitpunkt bekannt ist. Dabei wird stets über das Feld PackstueckID und bei Belegung auch über das Feld TrackingNr gesucht. Bei dieser Anfrage werden allerdings die zu aktualisierenden Felder und Inhalte nicht mehr nach den Richtlinien des Frachtführers geprüft (z.B. Gewichtsgrenzen, etc.). Es muss somit vom Vorsystem sichergestellt werden, dass die aktualisierenden Werte mit den Richtlinien des Frachtführers übereinstimmen. Sollte dies nicht möglich sein, kann diese Funktion nicht genutzt werden, sondern das Etikett muss storniert und neu verarbeitet werden. Außerdem können Felder, welche bereits auf einem Etikett angedruckt oder vom Versandsystem HVS32 in einer Frachtführerabwicklung ermittelt wurden (z.B. Adresse, Route, TrackingNr, Sonderdienste, etc.) nicht manipuliert werden.

Schnittstellen-Feld-Beschreibung

Packstück stornieren (StornoVersandDaten) [HCUSAG=4]

Die Gatewayfunktion StornoVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort bestehende Packstücke zu stornieren, die noch nicht auf einer Ausgangsliste sind. In der Regel wird ein Packstück anhand der hostseitigen Packstück-ID storniert. Diese wird im Feld PackstueckID übergeben. Zusätzlich zur hostseitigen Packstück-ID kann auch die TrackingNr zur Identifikation des Packstücks beitragen, für den Fall, dass die hostseitige Packstück-ID keine Eindeutigkeit garantieren kann.

Schnittstellen-Feld-Beschreibung

Tagesabschluss (Tagesabschluss) [HCUSAG=6]

Das Gateway sendet die Tagesabschluss-Anfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit ein Tagesabschluss anhand der zusätzlich übergebenen Parameter ausgelöst. Der Tagesabschluss setzt sich aus den Punkten Ausgangsliste erzeugen und Frachtführer DFÜ erzeugen zusammen. Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Tagesabschluss berücksichtigt. Standardmäßig sind alle Packstücke freigegeben, außer sie wurden durch das Erweiterungsmodul Ausgangsscannung gesperrt. Die Rückmeldung im HVS32 findet nach dem Ausführen des Tagesabschluss statt. Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung.

Schnittstellen-Feld-Beschreibung

Beispiele

Beispiel eines XML-Dokuments für eine Druckanfrage an den Packplatz DRELPPA07 inklusive einer Gefahrgutposition.
	<?xml version="1.0" encoding="ISO-8859-15"?>
	<LFS>
		<PESSSND>
			<HCKONZ>200</HCKONZ>
			<HCFIRM>010</HCFIRM>
			<HCUSAG>1</HCUSAG>
			<HCOUTQ>DRELPPA07</HCOUTQ>
			<HCSART>IMP</HCSART>
			<HCKDNR>0091052005</HCKDNR>
			<HCAN1>Beispiel GmbH</HCAN1>
			<HCAN2>z.H. Max Mustermann</HCAN2>
			<HCSTR>Teststr. 4</HCSTR>
			<HCLAKZ>DE</HCLAKZ>
			<HCPLZ>12345</HCPLZ>
			<HCLORT>Musterstadt</HCLORT>
			<HCLRGN>001</HCLRGN>
			<HCBHF>Versand+LS</HCBHF>
			<HCMAND>200010</HCMAND>
			<HCHVAR>DANS</HCHVAR>
			<HCLSNR>0014488006</HCLSNR>
			<HCANR1>0014488006</HCANR1>
			<HCBST1>0201583029</HCBST1>
			<HCWAWE_NUM>427,5000</HCWAWE_NUM>
			<HCWSWW>EUR</HCWSWW>
			<HCSSVC>31000</HCSSVC>
			<HCFLCO>medical equipment</HCFLCO>
			<HCDEDA>00.00.0000</HCDEDA>
			<HCDETI>00:00</HCDETI>
			<HCBGEW_NUM>224,05000</HCBGEW_NUM>
			<HCNGEW_NUM>201,15000</HCNGEW_NUM>
			<HCQUPA_NUM>1</HCQUPA_NUM>
			<HCPANR_NUM>1</HCPANR_NUM>
			<HCTOPA>PAL</HCTOPA>
			<HCPLEN_NUM>120</HCPLEN_NUM>
			<HCPWID_NUM>80</HCPWID_NUM>
			<HCPHEI_NUM>72</HCPHEI_NUM>
			<HCPKNR_NUM>357249014</HCPKNR_NUM>
			<HCDDAT>01.06.2007</HCDDAT>
			<HCDTIM>10:22</HCDTIM>
			<HCIDOC>0000000022309156</HCIDOC>
			<HCLBSL>FH</HCLBSL>
			<HCLAPA>1</HCLAPA>
			<HCRA13>A3001140</HCRA13>
			<HCRA18>DZL/4501017185</HCRA18>
			<HCAJH_NUM>20</HCAJH_NUM>
			<HCAJA_NUM>7</HCAJA_NUM>
			<HCAMO_NUM>6</HCAMO_NUM>
			<HCATA_NUM>1</HCATA_NUM>
			<HCASTD_NUM>10</HCASTD_NUM>
			<HCAMIN_NUM>22</HCAMIN_NUM>
			<HCASEK_NUM>24</HCASEK_NUM>
			<HCLFDN_NUM>1992951</HCLFDN_NUM>
		</PESSSND>
		<PESSGGV>
			<HGKONZ>200</HGKONZ>
			<HGFIRM>010</HGFIRM>
			<HGZUNR_NUM>6251</HGZUNR_NUM>
			<HGGGS>UN31</HGGGS>
			<HGGMEN_NUM>1,000</HGGMEN_NUM>
			<HGME>ST</HGME>
		</PESSGGV>
	</LFS>
Rückmeldung für die obige Anfrage:
	<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
	<LFS>
		<PHVSRCV>
			<HCKONZ>200</HCKONZ>
			<HCFIRM>010</HCFIRM>
			<HCUSAG>1</HCUSAG>
			<HCOUTQ>DRELPPA07</HCOUTQ>
			<HCSART>IMP</HCSART>
			<HCKDNR>0091052005</HCKDNR>
			<HCAN1>Beispiel GmbH</HCAN1>
			<HCAN2>z.H. Max Mustermann</HCAN2>
			<HCSTR>Teststr. 4</HCSTR>
			<HCLAKZ>DE</HCLAKZ>
			<HCPLZ>12345</HCPLZ>
			<HCLORT>Musterstadt</HCLORT>
			<HCLRGN>001</HCLRGN>
			<HCBHF>Versand+LS</HCBHF>
			<HCMAND>200010</HCMAND>
			<HCHVAR>DANS</HCHVAR>
			<HCLSNR>0014488006</HCLSNR>
			<HCANR1>0014488006</HCANR1>
			<HCBST1>0201583029</HCBST1>
			<HCWAWE_NUM>427,5000</HCWAWE_NUM>
			<HCWSWW>EUR</HCWSWW>
			<HCSSVC>31000</HCSSVC>
			<HCFLCO>medical equipment</HCFLCO>
			<HCDEDA>00.00.0000</HCDEDA>
			<HCDETI>00:00</HCDETI>
			<HCBGEW_NUM>224,05000</HCBGEW_NUM>
			<HCNGEW_NUM>201,15000</HCNGEW_NUM>
			<HCQUPA_NUM>1</HCQUPA_NUM>
			<HCPANR_NUM>1</HCPANR_NUM>
			<HCTOPA>PAL</HCTOPA>
			<HCPLEN_NUM>120</HCPLEN_NUM>
			<HCPWID_NUM>80</HCPWID_NUM>
			<HCPHEI_NUM>72</HCPHEI_NUM>
			<HCPKNR_NUM>357249014</HCPKNR_NUM>
			<HCDDAT>01.06.2007</HCDDAT>
			<HCDTIM>10:22</HCDTIM>
			<HCIDOC>0000000022309156</HCIDOC>
			<HCLBSL>FH</HCLBSL>
			<HCLAPA>1</HCLAPA>
			<HCRA13>A3001140</HCRA13>
			<HCRA18>DZL/4501017185</HCRA18>
			<HCAJH_NUM>20</HCAJH_NUM>
			<HCAJA_NUM>7</HCAJA_NUM>
			<HCAMO_NUM>6</HCAMO_NUM>
			<HCATA_NUM>1</HCATA_NUM>
			<HCASTD_NUM>10</HCASTD_NUM>
			<HCAMIN_NUM>22</HCAMIN_NUM>
			<HCASEK_NUM>24</HCASEK_NUM>
			<HCLFDN_NUM>1992951</HCLFDN_NUM>
			<HCRA15>073427000040941</HCRA15>
			<HCVENR>JND60073427000040941</HCVENR>
		</PHVSRCV>
	</LFS>
Beispiel-Mapping
HVS32 Feld LFS Feld
KundenNr HCKDNR
ZielAdrName1 HCAN1
ZielAdrName2 HCAN2
ZielAdrName3 HCAN3
ZielAdrStrasse HCSTR
ZielAdrLKZ HCLAKZ
ZielAdrPLZ HCPLZ
ZielAdrOrt HCLORT
ZielAdrRegion HCLRGN
ZielAdrBahnhof HCBHF
Ansprechpartner HCCNTC
TelefonNr HCTEL
FaxNr HCFAX
EmpfEmailAdresse HCEMAI
UstIDNr HCUIDN
ILNNr HCKILN
AuftraggeberID HCMAND
VersandartID HCVAVS
AVISHinweis1 HCSHW1
AVISHinweis2 HCSHW2
ZusatzZeile1 HCADA1
ZusatzZeile2 HCADA2
LieferscheinNr HCLSVS
AuftragNr HCANR1
BestellNr HCBST1
KundenBestellNr HCRA18
Warenwert HCWAWE_NUM
WWWaehrung HCWSWW
Nachnahme HCNNWE_NUM
NNWaehrung HCWSNN
NNVermerk HCCODT
NNVerwendung HCCODU
Versicherungswert HCINSW
VWWaehrung HCCKIW
FrankaturKennung HCLBSL
Zahlungsbedinung HCTPAY
ZbZoll HCTCUS
FrachtfuehrerKdNr HCTPNR
FrachtfuehrerKdNrZoll HCTCNR
SonderdiensteInaktiv HCSSVC
SendungsInhalt HCFLCO
TerminArt HCTKZ
TerminDatum HCDTLF
RechnungsEmpfName1 HCBAN1
RechnungsEmpfName2 HCBAN2
RechnungsEmpfName3 HCBAN3
RechnungsEmpfStr HCBSTR
RechnungsEmpfLKZ HCBLKZ
RechnungsEmpfPLZ HCBPLZ
RechnungsEmpfOrt HCBORT
PostLeitcode HCPLCD
PostZielfrachtzent HCDEFC
Frachtbrief HCBOL
Gewicht HCBGEW_NUM
PackStkGes HCQUPA_NUM
PackStkNr HCPANR_NUM
VerpackungsArt HCTOPA
PackStueckLaenge HCPLEN_NUM
PackStueckBreite HCPWID_NUM
PackStueckHoehe HCPHEI_NUM
PackStueckID HCPKNR_NUM
LieferscheinDatum HCRA10

FAQ / Troubleshooting

Abgerufen von „https://wiki.heidler-strichcode.de/w/index.php?title=HVS32_PSI_REST_Schnittstelle_(Automatik-Polling)&oldid=4272“