Interface Spezifikation exotargets LS

Transkript

1 Interface Spezifikation exotargets LS

2 Einführung Inhaltsverzeichnis Inhaltsverzeichnis Inhalt 1. Einführung 3 2. History 3 3. Online-Schnittstelle 3 4. Offline-Schnittstelle 6 5. Implementationshinweise 8 6. Lizenzbedingungen 9 7. Registrierung als Service-Provider 9 8. Registrierung von Endkunden 9 9. Fakturierungsprozess Kontaktdaten 10 2

3 Interface Spezifikation exotargets LS Einführung Interface Spezifikation exotargets LS 1. Einführung Dieses Dokument beschreibt die Anwendung der Schnittstelle zum Service exotargets LS von CodX Software. Die Nutzung der Schnittstelle, wie auch die Nutzung der zurückgegebenen Daten obliegt den Nutzungsbedingungen von CodX Software AG und den entsprechenden Datenlieferanten. Es werden zwei verschiedene Schnittstellen angeboten. Der Web-Service bietet eine Online- Schnittstelle und bearbeitet Einzelanfragen als HTTPS POST-Request. Die Offline-Schnittstelle ist eine File-Schnittstelle für den Batch-Betrieb. Die beiden Schnittstellen unterscheiden sich weder in der Funktionalität noch in der Verarbeitungsgeschwindigkeit, wenn die untenstehenden Implementationshinweise berücksichtigt werden. Wir empfehlen, wenn möglich die Online-Schnittstelle zu implementieren. 2. History Version Date Changes Initial edition 3. Online-Schnittstelle Die Online-Schnittstelle unterstützt Überprüfung von einzelnen Adressen als Web-Service. Falls eine Nachsendeadresse gefunden wurde, wird die gefundene Adresse zurückgegeben. Bei Datenquellen für Unzustellbarkeit oder Sterbe-Informationen wird nur der Treffer zurückgegeben Request Der Request wird per POST an den Web-Server ( übertragen Beispiel Request <?xml version="1.0" encoding="utf-8"?> <ExotargetsRequest> <RequestHeader Type="LS" Action="MoversCheck" /> <CustomerData CustomerHash="15991b8c29b5a2fd6e54603c " EndCustomerID="132" EndCustomerKey="465" /> <RequestData> <Firstname>TestFirstname</Firstname> <Lastname>TestLastName</Lastname> <Street>TestStreet</Street> <StreetNumber>21</StreetNumber> <ZipCode>TEST</ZipCode> <City>Stadt der Briefe</City> <Country>D</Country> </RequestData> </ExotargetsRequest> Beispiel Request 3

4 Online-Schnittstelle Interface Spezifikation exotargets LS Beschreibung der Attribute Element Attribut Beschreibung ExotargetsRequest Element, welches den kompletten Request beinhaltet RequestHeader Header des Requests RequestHeader Type Typ des Requests in diesem Fall immer "LS" RequestHeader Action Aktion welche durchgeführt wird. Moverscheck: Adressprüfung auf Umzug CustomerData Beinhaltet die Daten für die Authentifizierung CustomerData CustomerHash Diesen Hash erhalten Sie von CodX Software AG nach der Registrierung als Service-Provider. CustomerData EndCustomerID ID des Endkunden. Diese ID erhalten Sie von CodX Software AG nach der Registrierung des Endkunden. CustomerData EndCustomerKey Key des Endkunden. Diesen Key erhalten Sie von CodX Software AG nach der Registrierung des Endkunden. RequestData Beinhaltet die Daten der Anfrage. Dieses Element kann nur einmal vorkommen. Die nachfolgenden Elemente sind immer anzugeben. Firstname Vorname Lastname Nachname Street Strasse StreetNumber Hausnummer ZipCode Postleitzahl City Ort Country Land (immer "D"). Beschreibung der Attribute (Request) XML Schema für Request <xs:schema attributeformdefault="unqualified" elementformdefault="qualified" xmlns:xs=" <xs:element name="exotargetsrequest"> <xs:complextype> <xs:sequence> <xs:element name="requestheader" maxoccurs="1" minoccurs="1"> <xs:complextype> <xs:simplecontent> <xs:extension base="xs:string"> <xs:attribute type="xs:string" name="type" use="required"/> <xs:attribute type="xs:string" name="action" use="required"/> </xs:extension> </xs:simplecontent> </xs:complextype> </xs:element> <xs:element name="customerdata" maxoccurs="1" minoccurs="1"> <xs:complextype> <xs:simplecontent> <xs:extension base="xs:string"> <xs:attribute type="xs:string" name="customerhash" use="required"/> <xs:attribute type="xs:string" name="endcustomerid" use="required"/> <xs:attribute type="xs:string" name="endcustomerkey" use="required"/> </xs:extension> </xs:simplecontent> 4

5 Interface Spezifikation exotargets LS Online-Schnittstelle </xs:complextype> </xs:element> <xs:element name="requestdata"> <xs:complextype> <xs:sequence> <xs:element type="xs:string" name="firstname" maxoccurs="1" minoccurs="1"/> <xs:element type="xs:string" name="lastname" maxoccurs="1" minoccurs="1"/> <xs:element type="xs:string" name="street" maxoccurs="1" minoccurs="1"/> <xs:element type="xs:string" name="streetnumber" maxoccurs="1" minoccurs="1"/> <xs:element type="xs:string" name="zipcode" maxoccurs="1" minoccurs="1"/> <xs:element type="xs:string" name="city" maxoccurs="1" minoccurs="1"/> <xs:element type="xs:string" name="country" maxoccurs="1" minoccurs="1"/> </xs:sequence> </xs:complextype> </xs:element> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> XML Schema Definition für Request 3.2. Response Die Antwort erfolgt als UTF-8 codiertes XML Beispiel Response <?xml version="1.0" encoding="utf-8"?> <ExotargetsResponse> <Status>OK</Status> <ResponseHeader Type="LS" Action="MOVERSCHECK" /> <ResponseData SourceType="3" SourceDescription="BeispielQuelle" SourceQuality="1" ValidFrom=" " ValidTo=" "> <Firstname>Hans</Firstname> <Lastname>Muster</Lastname> <Street>TestStr.</Street> <StreetNumber>99</StreetNumber> <ZipCode>99999</ZipCode> <City>TestStadt</City> <Country>D</Country> </ResponseData> </ExotargetsResponse> Beschreibung der Attribute Beispiel Antwort Element Attribut Beschreibung ExotargetsResponse Enthält die Antwort vom Server Status Status der Antwort UNDEFINED: Undefiniert OK: Status OK (Treffer oder kein Treffer) NO_RESULTS: Kein Resultat/Antwort von exotargets erhalten. 5

6 Offline-Schnittstelle Interface Spezifikation exotargets LS Element Attribut Beschreibung XML_MISSING_PARAMETER: Fehlender Parameter in der Anfrage. NO_EXOCLOUD_SERVER_CONNECTION: Keine Verbindung zum exocloud Server. CUSTOMER_NOT_KNOWN: Kunde ist nicht bekannt. ResponseHeader ResponseHeader Type Typ des Requests in diesem Fall immer "LS" ResponseHeader Action Aktion welche durchgeführt wird. Moverscheck: Adressprüfung auf Umzug ResponseData SourceType Typ der Quelle 1: Umzüge 2: Unzustellbar 3: Verstorbene SourceDescrip Beschreibung der Quelle tion SourceQuality Qualität der Quelle 1 (niedrig) - 3 (hoch) ValidFrom Gültig von ValidTo Gültig Bis Firstname Vorname Lastname Nachname Street Strasse StreetNumber Hausnummer ZipCode Postleitzahl City Ort Country Land (immer D) Beschreibung der Attribute (Response) 4. Offline-Schnittstelle Die Offline-Schnittstelle unterstützt Überprüfung von mehreren Adressen. Die Adressen werden als CSV-File an CodX Software übertragen. Falls eine Nachsendeadresse gefunden wurde, wird die gefundene Adresse zurückgegeben. Bei Datenquellen für Unzustellbarkeit oder Sterbe-Informationen wird nur der Treffer zurückgegeben File-Format Input-File Die Input-Datei enthält alle zu prüfenden Adressen und wird vom Service-Provider an CodX Software gesendet. Die einzelnen Attribute werden durch Semikoln (;) getrennt. Die Datenwerte dürfen kein Semikolon beinhalten. Die einzelnen Adressen werden durch CR/LF getrennt. Die Datensätze müssen immer komplett übergeben werden. Die optionalen Attribute dürfen jedoch leer sein. Attribut Typ Beschreibung CustomerHash String Diesen Hash erhalten Sie von CodX Software AG nach der Registrierung als Service-Provider. EndCustomerID String ID des Endkunden. Diese ID erhalten Sie von CodX Software AG nach der Registrierung des Endkunden. EndCustomerKey String Key des Endkunden. Diesen Key erhalten Sie von CodX Software AG nach der Registrierung des Endkunden. Action String Aktion welche durchgeführt wird. Moverscheck: Adressprüfung auf Umzug 6

7 Interface Spezifikation exotargets LS Offline-Schnittstelle Attribut Typ Beschreibung Firstname String Vorname Lastname String Nachname Street String Strasse StreetNumber String Hausnummer ZipCode String Postleitzahl City String Ort Country String Land (immer "D"). Die Input-Datei wird mit einem Passwort gezippt und über FTP in den Input-Folder an CodX Software übertragen. Das Passwort und der URL des FTP-Servers erhalten Sie bei der Registrierung als Service- Provider. Grundsätzlich verarbeitet der Service alle ZIP-Files, welche im Input-Folder liegen. Damit die einzelnen Files jedoch einfach unterschieden werden können, empfehlen wir diese wie folgt zu benennen: 'exols_<dd.mm.yyy_hh.mm.ss>.in.zip'. Da FTP keine Übertragungstransaktion kennt, soll für die Übertragung die Endung '.tmp' angehängt werden. Nach erfolgreicher Übertragung über FTP soll das ZIP-File mit dem korrekten Namen umbenannt werden. Damit wird verhindert, dass der Service bereits auf die ZIP-Datei zugreift, währenddem diese durch den Service-Provider noch hochgeladen wird. Ein ZIP-File darf nur eine CSV-Datei mit dem Namen 'exols.in.csv' enthalten. Alle übrigen Files des ZIP-Files werden nicht verarbeitet. Das ZIP-File wird durch CodX Software nach der Verarbeitung gelöscht File-Format Output-File Das Output-File enthält die geprüften Adressen mit den zurückgegebenen Daten und geht von CodX Software an den Service-Provider. Die einzelnen Attribute werden durch Semikoln (;) getrennt. Die Datenwerte dürfen kein Semikolon beinhalten. Die einzelnen Adressen werden durch CR/LF getrennt. Die Datensätze müssen immer komplett übergeben werden. Die optionalen Attribute dürfen jedoch leer sein. Attribut Typ Beschreibung CustomerHash String Diesen Hash erhalten Sie von CodX Software AG nach der Registrierung als Service-Provider. EndCustomerID String ID des Endkunden. Diese ID erhalten Sie von CodX Software AG nach der Registrierung des Endkunden. EndCustomerKey String Key des Endkunden. Diesen Key erhalten Sie von CodX Software AG nach der Registrierung des Endkunden. Action String Aktion welche durchgeführt wird. Moverscheck: Adressprüfung auf Umzug Firstname String Vorname Lastname String Nachname Street String Strasse StreetNr String Hausnummer ZipCode String Postleitzahl City String Ort Country String Land (immer "D"). Status String Status der Antwort UNDEFINED: Undefiniert OK: Status OK (Treffer oder kein Treffer) 7

8 Implementationshinweise Interface Spezifikation exotargets LS Attribut Typ Beschreibung NO_RESULTS: Kein Resultat / Antwort von exotargets erhalten. XML_MISSING_PARAMETER: Fehlender Parameter in der Anfrage. NO_EXOCLOUD_SERVER_CONNECTION: Keine Verbindung zum exocloud Server. CUSTOMER_NOT_KNOWN: Kunde ist nicht bekannt. SourceType Integer Typ der Quelle 1: Umzüge 2: Unzustellbar 3: Verstorbene SourceDescription String Beschreibung der Quelle SourceQuality Integer Qualität der Quelle 1 (niedrig) - 3 (hoch) ValidFrom DD.MM.YYYY Gültig von ValidTo DD.MM.YYYY Gültig Bis New Firstname String Neuer Vorname (nur bei Umzügen) New Lastname String Neuer Nachname (nur bei Umzügen) New Street String Neue Strasse (nur bei Umzügen) New StreetNr String Neue Hausnummer (nur bei Umzügen) New ZipCode String Neue Postleitzahl (nur bei Umzügen) New City String Neuer Ort (nur bei Umzügen) New Country String Neues Land (nur bei Umzügen) Das Output-File der CSV-Datei hat den Namen 'exols.out.csv' ersetzt. Das Output-File wird auch mit einem passwort gezippt und in den Output-Folder des FTP-Servers übertragen. Der Filename des ZIP- Files lautet gleich wie das Input-Zip-File, jedoch wird die Endung '.in.zip' mit der Endung '.out.zip' ersetzt. Es gilt das selbe Passwort und URL des FTP-Servers wie für das Input-File und wird bei der Registrierung als Service-Providers zur Verfügung gestellt. Der Service-Provider prüft zyklisch den FTP-Server nach einem ZIP-File. Ist das File vorhanden, wird dies durch den Service-Provider heruntergeladen und anschliessend auf dem FTP-Server gelöscht. 5. Implementationshinweise Die nachfolgenden Implementationshinweise sollen helfen, den Dienst optimal einsetzen zu können Performance Online-Schnittstelle Die Prüfung einer Adresse dauert im Normalfall zwischen ca. 50 ms und ca. 150 ms. Die Verarbeitungsgeschwindigkeit hängt davon ab, welche Datenquellen verwendet werden und wie viele unterschiedliche Treffer für diese Anfrage vorhanden sind. Damit ergibt sich eine Leistung von ca. 6 bis 20 Anfragen pro Sekunde (10'000 Anfragen: ca. 17 Min.). Die Leistung kann kann weiter gesteigert werden, indem mehrere Anfragen parallel ausgeführt werden (Multithreading). Dabei dürfen maximal 10 Threads pro System gleichzeitig Anfragen starten. Sind mehr Threads vorhanden, so werden diese durch den Dienst automatisch serialisiert. Mit Multithreading kann die Leistung auf ca. 60 bis 200 Anfragen pro Sekunde (10'000 Anfragen: ca. 100 Sek.) gesteigert werden. Auf Anfrage können mehrere Server (URLs) für den Service angeboten werden. Dabei sollten die Anfragen an die einzelnen URLs nach der Round-Robin-Methode angefragt werden. Dabei werden die 8

9 Interface Spezifikation exotargets LS Lizenzbedingungen Anfragen gleichzeitig auf alle verfügbaren Server verteilt. (z.b. bei 2 Servern: 1. Anfrage: 1. Server; 2. Anfrage: 2. Server; 3. Anfrage: 1. Server usw.). Damit können bei drei Servern ca. 180 bis 600 Anfragen pro Sekunde (10'000 Anfragen: ca. 30 Sek.) verarbeitet werden Performance Offline-Schnittstelle Die Offlinie-Schnittstelle verarbeitet ca. 60 bis 200 Adressen pro Sekunde (10'000 Adressen: ca. 100 Sek.), ohne die eigentliche Datenübertragung. Die Leistung hängt jedoch stark von der Anzahl der zu verarbeitenden Adressen im File ab (kleine Leistung bei kleinen Files) Testanfragen Jeder Treffer führt automatisch zu Kosten. Testsysteme sind aus lizenztechnischen Gründen nicht möglich. Aus diesem Grund ist eine spezielle Testabfrage implementiert worden. Dazu wird eine normale Anfrage mit einer beliebigen Adresse aufgegeben. Als PLZ wird jedoch der Wert 'TEST' eingetragen. Diese Testanfragen werden nicht an die Datenquellen weitergeleitet, sondern direkt verarbeitet. Als Datenquelle wird auch Test zurückgegeben. 6. Lizenzbedingungen Die zurückgegebenen Adressdaten unterliegen strengen Lizenzbedingungen der Datenlieferanten. Für die Nutzung dieser Daten wird ein Nutzungsvertrag zwischen dem Datenlieferanten und dem Endkunden geschlossen. Dieser Nutzungsvertrag ist davon abhängig, von welchen Datenlieferanten der Endkunde die Daten beziehen will. Aus lizenztechnischen Gründen darf die Anwendung kein Caching oder Pooling der zurückgegebenen Daten implementieren. Jede Adresse muss einzeln und jedes Mal neu angefragt werden. 7. Registrierung als Service-Provider Als Service-Provider müssen Sie sich bei CodX Software AG registrieren. Damit aktzeptieren Sie die Nutzungsbedingungen des Services und erhalten den Customer-Hash. Dieser Customer-Hash wird bei jeder Anfrage angegeben. 8. Registrierung von Endkunden Jeder einzelne Endkunde muss vor der Erstnutzung des Dienstes bei CodX Software AG registriert werden. Diese Registrierung erfolgt über das entsprechende Registrierungsformular. Durch die erfolgreiche Registrierung wird ein Endkunden-Profil erstellt. Das Endkunden-Profil wird durch die ID (EndCustomerID) und den Schlüssel (EndCustomerKey) referenziert. Diese müssen dann bei jeder Anfrage angegeben werden. Dem Endkunden-Profil kann auch hinterlegt werden, welche Datenquellen in welcher Reihenfolge genutzt werden. Es kann auch hinterlegt werden, ob die Daten für die Einmalnutzung oder für die Dauernutzung abgefragt werden. Damit können die möglichen Treffer und damit die Kosten beeinflusst werden. Ein Endkunde kann mehrere Endkunden-Profile haben. 9

10 Fakturierungsprozess Interface Spezifikation exotargets LS 9. Fakturierungsprozess Die Fakturierung der Anfragen erfolgt nach den abgeschlossenen Nutzungsverträgen. Dabei wird jeder zurückgegebene Treffer in Rechnung gestellt. Die Rechnungsstellung erfolgt durch CodX Software AG an den Service-Provider. Die Rechnung wird nach Endkunden und Endkunden-Profil gegliedert und enthält die Anzahl der Treffer unterteilt nach den Datenquellen. Es werden nur Endkunden und Datenquellen ausgewiesen, welche auch in der entsprechenden Abrechnungsperiode (in der Regel monatlich) Treffer hatten. Die Rechnungsstellung an den Endkunden erfolgt durch den Service-Provider. Je nach Datenlieferant kann diese Rechnungsstellung speziellen Anforderungen unterliegen. Diese sind in den Nutzungsverträgen zwischen CodX Software AG und dem Service-Provider beschrieben. 10. Kontaktdaten CodX Software AG Sinserstrasse Cham Schweiz