PDF Export

Auftragsanlage

Allgemeines

Die Batch Schnittstelle zur Anlage von Abonnement-Aufträgen ermöglicht es der Gegenseite, Abonnements in einer Datei zu sammeln und diese dann zur weiteren Verarbeitung an dsb zu übermitteln. Die Schnittstelle basiert auf XML. (eXtensible Markup Language). Die gesamte Struktur wird im Gegensatz zu den Web-Service Anbindungen in einer Datei übertragen. Die XML-Struktur besteht im wesentlichen aus einem Header-Teil, in dem zusätzlich zu den üblichen Dokumentenbeschreibungen (XML-Version, encoding, etc.) verarbeitungsspezifische Daten (z.B. Dateibeschreibung, Zielmandant) hinterlegt werden, die für die gesamte Datei gelten. Die auftragsspezifischen Daten werden innerhalb des

  • Tags hinterlegt. Zu einem Auftrag können mehrere Geschäftspartner in ihren jeweils erforderlichen Bedeutungen (Rollen) angelegt werden, es können mehrere Prämien und mehrere Nachrichten angegeben werden. Die Dateien werden per FTP auf den FTP-Server der DSB übertragen. Details hierzu, sowie zur Dateinamenskonventionen werden ihnen vor Einsatz von der AVS/3-Kundenbetreuung mitgeteilt. Eine Vielzahl von Feldattributen sind abhängig von mandantenspezifischen Einstellungen (Stammdaten oder Customizing) in AVS/3 und können in dieser Schnittstellenbeschreibung nicht explizit ausgeprägt werden. Bei Unklarheiten oder konkreten Fragen stimmen Sie dies bitte mit ihrem entsprechenden Ansprechpartner der AVS/3-Kundenbetreuung ab.

Gesamtstruktur

Alle Aufträge werden innerhalb eines XML-Dokuments und damit einer .xml-Datei versendet. Im Header stehen Verwaltungsinformationen, wie zum Beispiel der Zielmandant im AVS/3-System, in den die Daten übernommen werden sollen. Die Aufträge(Abonnements) werden innerhalb des <body> -Tags zusammengefasst. Ein einzelner Auftrag (Abonnement) wird mit seinen Elementen innerhalb eines Tags geführt. Die Adressdaten werden innerhalb der <business-partner>-Tags geführt. Pro Rolle (=Funktion), die ein Geschäftspartner annehmen kann und für die eine Adresse angelegt werden soll, wird ein eigenes Element eines <business-partner>-Tags gebildet. Zum Beispiel für den Auftraggeber (Rolle ‚AG‘), für einen abweichenden Warenempfänger (Rolle ‚WE‘), bei Prämienabos für den Vermittler (Rolle ‚VM‘). Die Rolle des Geschäftspartners kann sowohl über die Struktur ‚subscription-to-business-partner-relationship‘ übermittelt werden als auch direkt als Attribut in der Struktur ‚business-partner‘. Es wird empfohlen, die Rolle über die Struktur ‚business-partner‘ zu übermitteln. Es ist für jede Prämie eine Struktur mit dem Namen ‚premium‘ einzufügen. Wichtig ist, dass alle genannten Elemente, die zu einem bestimmten Auftrag gehören von einem - Tag umschlossen sind, da sonst keine eindeutige Zuordnung erfolgen kann. Die Reihenfolge der Elemente ist wie dargestellt einzuhalten. Dateien, die diesbezügliche Fehler aufweisen werden als Ganzes abgelehnt. Ein zentrales Feld ist das Feld „BQ“ (Bestellquelle) in der Struktur „subscription“. Dieser Wert entspricht der Werbeaktionsnummer und ihm können verschiedene Werte hinterlegt werden. Die so hinterlegten Werte sind dann nicht mehr über die Schnittstelle zu übergeben, sondern werden bei DSB zugesteuert. Einige Felder sind als Konstanten anzusehen (wie z.B. das Feld „client“ im Header). Die Belegung dieser Felder wird ihnen noch mitgeteilt.

Da alle von Ihnen gesendeten Dateien maschinell weiterverarbeitet werden, müssen die Dateinamen einer speziellen Konvention folgen. Ein Dateiname hat normalerweise folgenden Aufbau:

<System><Dienstleister><Mandant><Datum><fortlaufende Nummer>.xml.pgp

Feld LängeBeschreibung
System 2 Identifiziert das Zielsystem
v3 = VHS/3
a3 = AVS/3
z3 = ZHS/3
Dienstleister 3 Kennzeichnet den Dienstleister, der diese Datei erzeugt hat.
Mandant 3 - 43 bzw. 4stellige Nummer des Mandanten im Zielsystem Mandantennummer.
Datum 8 Datum der Dateierstellung bzw. Übertragung im Format YYYYMMDD
Fortlaufende Nummer3 Einfacher Zähler

Aufgrund der maschinellen Weiterverarbeitung ist es notwendig, dass Sie nach der Übertragung der eigentlichen Dateien noch eine sog. OK-Datei übertragen. Diese Datei hat den gleichen Namen wie die Datendatei aber noch zusätzlich die Dateierweiterung „.ok“. Diese Datei kann leer sein und der Inhalt wird nicht weiter beachtet.

Der Grund für diese OK-Datei liegt darin, dass es nicht möglich ist festzustellen, ob eine Datei bereits komplett von Ihnen übertragen wurde. Falls nun der Upload noch im Gange ist und wir bereits mit der Verarbeitung der Datei beginnen würden, könnte dies zum Verlust von Daten führen. Aus diesem Grund müssen Sie nach erfolgreicher Übertragung noch eine OK-Datei mit auf den FTP Server stellen. Erst wenn zu einer Datendatei eine zugehörige OK-Datei existiert, wird mit der Verarbeitung begonnen. Das heißt aber auch, dass Dateien ohne entsprechende OK-Datei auf unserer Seite nicht verarbeitet werden.

Beispiel:

Falls Sie am 14.02.2003 Ihre 15. Übertragung mit dem Ziel (VHS/3) durchgeführt hätten, Ihre Dienstleister Kennung „dke“ und Ihr Mandant „4711“ wäre, dann müssten sich nach der Übertragung folgende Dateien im Verzeichnis 'an_dsb' auf unserem FTP-Server befinden.

v3dke471120030214015.xml.pgp

v3dke471120030214015.xml.pgp.ok

Schematische Darstellung (neu): 

<?xml version='1.0' encoding='ISO-8859-1'?>
<message version='1.0' system='avs/3'>
  <header>
    <creation-date></creation-date>
    <creation-time></creation-time>
    <collection-office></collection-office>
    <file-name></file-name>
    <file-number></file-number>
    <client></client>
    <number-of-entries></number-of-entries>
  </header>
  <body>
    <!-- umfasst einen Auftrag -->
    <subscription>
      <!—Felder und Elemente gemäß Beschreibung -->
      <business-partner>
        <!-- Aufbau und Elementdefinition gemäß Beschreibung -->
      </business-partner>
      <premium>
        <!-- Aufbau und Elementdefinition gemäß Beschreibung -->
      </premium>
      <order-attribute>
        <!-- Aufbau und Elementdefinition gemäß Beschreibung -->
      </order-attribute>
    </subscription>
    <subscription>
      <!-- weiterer Auftrag -->
    </subscription>
    <subscription>
      <!-- weiterer Auftrag, usw. -->
    </subscription>
  </body>
</message>

Die Struktur der zu liefernden XML-Fragmente subscription, hat im Batch Modus den gleichen Aufbau wie im Realtime Modus. Bitte verwenden Sie daher die Beschreibugen der angeführten Request Struktur:

Request Struktur

Größe der Dateien

Die Dateien sind prinzipiell keiner Größenbeschränkung unterworfen. Da die Verarbeitung von großen XML-Dateien recht speicherintensiv ist, sollten die übermittelten Dateien nicht mehr als 1.500 Aufträge enthalten. Falls mehr Aufträge übermittelt werden sollten, so sollten diese auf mehrere XML-Dateien aufgeteilt werden. Durch den Zähler am Ende des Dateinamens bleiben die Dateinamen eindeutig. Die entsprechenden Dateien werden dann sequentiell verarbeitet.

Verschlüsselung von Kundendaten

Prinzipiell existieren zwei verschiedene Möglichkeiten Kundendaten zu verschlüsseln:

  • Symmetrische Verschlüsselung: hier werden die Daten mittels eines Passwortes verschlüsselt. Der Vorteil bei diesem Verfahren liegt darin, dass es recht einfach zu implementieren bzw. anzuwenden ist. Die Stärke der Verschlüsselung hängt im wesentlichen von der Qualität des Passworts ab.
  • Public-Key Verschlüsselung: hier werden die Daten mit dem öffentlichen Schlüssel von dsb verschlüsselt.

dsb bietet beide dieser Möglichkeiten der Verschlüsselung von Kundendaten an.

Die Beispiele wurden mit GnuPG bzw. der Windows Variante Gpg4win getestet: https://www.gnupg.org/ (am Besten die Kommandozeilen-Version verwenden).

Symmetrische Verschlüsselung

Verwendung von gpg:
Um eine Kundendatei mit dem Namen a3fnk5251510200201.xml zu verschlüsseln wird einfach folgende Kommandozeile eingegeben: 

gpg --symmetric a3fnk5251510200201.xml

oder 

gpg --c a3fnk5251510200201.xml

Hierbei steht „-c“ für symmetrische Verschlüsselung.

Danach muss das Passwort zur Verschlüsselung eingegeben werden und das Programm erzeugt automatisch die verschlüsselte Datei a3fnk5251510200201.xml.gpg. Diese Datei kann dann (mit der OK-Datei a3fnk5251510200201.xml.gpg.ok) auf den Server bei dsb gestellt werden, von wo sie weiterverarbeitet werden kann.

Das Passwort zur Verschlüsselung wird Ihnen von der Kundenbetreuung vor Produktivstart mitgeteilt und ist dann bei jeder Verschlüsselung der Daten zu verwenden.

Asymmetrische Verschlüsselung

Verwendung von gpg:
Um den von dsb eingesetzten Schlüssel einzubinden ist folgender Befehl einzugeben: 

gpg --import Schlüsseldatei

Der öffentliche Schlüssel ist hier hinterlegt.

Mittels gpg -k kann überprüft werden, ob der Schlüssel ordnungsgemäß eingebunden ist. (Es wird eine Liste der public keys im Key Ring ausgegeben). Danach ist GnuPG bereit, Kundendateien zu verschlüsseln.

Um die Datei mit dem Namen a3fnk5251510200201.xml per Public Key Verfahren zu verschlüsseln, ist folgendes auf der Kommandozeile einzugeben: 

gpg --default-recipient <ID dsb public key> --encrypt a3fnk5251510200201.xml

Das Programm erzeugt dann automatisch die verschlüsselte Datei a3fnk5251510200201.xml.gpg. Diese Datei kann dann (mit der OK-Datei a3fnk5251510200201.xml.gpg.ok) auf den Server von dsb gestellt werden, von wo sie weiterverarbeitet werden kann.

Hinweis: Die verschlüsselte Datei darf keine Signatur enthalten bzw. darf nicht signiert sein.

XML-Definition: Header

Aufbau 

<header>
  <creation-date></creation-date>
  <creation-time></creation-time>
  <collection-office></collection-office>
  <file-name></file-name>
  <file-number></file-number>
  <client></client>
  <number-of-entries></number-of-entries>
</header>
Name Typ / LängeText Kann / MussBeschreibung
creation-date 10 /C Erstellungsdatum der Datei m
creation-time 8/ C Erstellungszeit der Datei m
collection-office12 /C Erfassungsbüro m Soll denselben Inhalt haben wie das Feld ‚input-office‘ im Auftrag. Dieses Feld dient zum Versenden der Berichtsemail. Der Inhalt wird Ihnen von der Kundenbetreuung mitgeteilt.
file-name 30 / C Dateiname (dient der Verifizierung) m
file-number 2/ N Fortlaufende Dateinummer (vom Erfassungsbüro zu vergeben.)m Beginnend bei 01 bis 99 (rollierend).
client 3/ N Name des Zielmandanten m Nach Rücksprache mit AVS/3-Kundenbetreuung.
number-of-entries8/ N Anzahl der Einträge m Anzahl der ‚subscription‘ Einträge in der Datei.

Änderungen der XML-Strukturen

DSB behält sich vor die in diesem Dokument beschrieben XML-Strukturen ohne Vorankündigung anzupassen, solange diese Anpassungen komplett abwärtskompatibel bleiben. In der Praxis sind dies hauptsächlich Ergänzungen von Elementen und Attributen.

Beispiel 1: Neues Element

Neue Elemente können hinzugeführt werden. Alle Clients sollten so auf die Elemente zugreifen (z. B. nur über den Namen), dass keine Anpassung notwendig ist.

Struktur VOR der Erweiterung/Anpassung: 

<existing-element1>ABCD</existing-element1>
<existing-element2>1234</existing-element2>

Struktur NACH der Erweiterung/Anpassung: 

<existing-element1>ABCD</existing-element1>
<new-element>XYZ</new-element1>
<existing-element2>1234</existing-element2>
Beispiel 2: Neues Attribut

Attribute zu Elementen können hinzugeführt werden. Alle Clients sollten so auf die Elemente zugreifen (z.B. nur über den Namen), dass keine Anpassung notwendig ist.

Struktur VOR der Erweiterung/Anpassung: 

<existing-element1>ABCD</existing-element1>

Struktur NACH der Erweiterung/Anpassung: 

<existing-element1 new-attribute="XYZ">ABCD</existing-element1>

Um dies auf Seite des Clients sicherstellen zu können, gibt es einen speziellen Webservice, mit dem geprüft werden kann, wie der Client auf solche Erweiterungen reagiert.

Siehe hierzu Abschnitt zum Service checkUpgradeCompatibility.

Cookies helfen bei der Bereitstellung von Inhalten. Durch die Nutzung dieser Seiten erklären Sie sich damit einverstanden, dass Cookies auf Ihrem Rechner gespeichert werden. Weitere Information