Schweizer UID-Prüfung – Dokumentation

Anwendung

Auf dieser Seite finden Sie das Benutzerhandbuch der Schweizer UID-Prüfung.

Die Software Schweizer UID-Prüfung ist unterteilt in zwei Bereiche. Der Einzelabfrage und der Stapelverarbeitung.

Schweizer-UID-Prüfung
Schweizer-UID-Prüfung

Einzelabfrage

Die Einzelprüfung ermöglicht es, mit der Eingabe der Schweizer UID-Nummer eine Prüfung unmittelbar auszuführen.

Bei der Einzelabfrage findet keine Ausgabe der Prüfergebnisse in eine Datei statt. Diese Anwendungssicht dient zur schnellen Prüfung, z.B. bei der Durchgabe von Schweizer UID-Nummern per Telefon, um diese auf Ihre Gültigkeit zu prüfen. Die Verarbeitung von Dateien werden über die Stapelverarbeitung oder der Hintergrundverarbeitung durchgeführt.

Ist die Schweizer UID-Nummer korrekt, erhalten Sie in den weiteren Feldern alle Informationen, die von der Schnittstelle zurückgemeldet werden. Im Fehlerfall erhalten Sie die genaue Rückmeldung der Schweizer UID Schnittstelle vom BFS.

Stapelverarbeitung

Wählen Sie eine Datei aus oder ziehen Sie diese per Drag&Drop auf das Feld “Importdatei” und prüfen Sie diese durch das Betätigen des “Prüfen-Button”. Dadurch startet die Überprüfung der gesamten Datei. Diese erzeugt im Hintergrund das Protokoll. Das Protokoll kann im Anschluss über den Protokoll-Button geöffnet werden. Dieses beinhaltet alle Prüfergebnisse, der einzelnen Datensätze. Der Vorgang der Überprüfung nimmt je nach Größe der Datei einige Zeit in Anspruch.

Der Name der Schweizer UID-Protokolldatei wird automatisch vergeben und im identischen Format erzeugt, wie das übergebene Format. Wird zum Beispiel eine Datei mit dem Namen “daten.json” übergeben, so ist die Bezeichnung der Protokolldatei “daten-log.json”.

Vorab-Validierung

Die Vorabprüfung einer Schweizer UID Importdatei kann Ihnen helfen, das Format und die Anzahl der gefundenen Datensätze, ohne eine Prüfung durchzuführen, zu prüfen. Die Datei wird dabei analysiert und das Ergebnis Ihnen mit einer Meldung angezeigt.

Konfiguration

Über das Hauptmenü Extras – Einstellungen UID-Nummer werden die Einstellungen für die Schweizer UID-Prüfung vorgenommen.

Allgemeine Einstellungen

Schweizer UID-Prüfung - Einstellungen UID Allgemein
Schweizer UID-Prüfung – Einstellungen UID Allgemein

Archiv

Über das Archiv der Schweizer UID-Prüfung stellen wir Ihnen eine Funktion bereit, um den gesetzlichen Anforderungen der nachvollziehbaren Speicherung der Anfragen und Antworten bereit. Wird die Option aktiviert, geben Sie bitte noch das entsprechende Verzeichnis an, in denen alle Anfragen und Antworten gespeichert werden. Sofern Sie den gesetzlichen Vorgaben unterliegen, um jede Anfrage zu speichern, wählen Sie bitte einen Speicherort aus, der regelmäßig gesichert (Backup) wird und ggf. gegen Veränderung Dritter geschützt ist. Fragen Sie dazu Ihre IT-Abteilung, um einen solchen Speicherplatz für Sie zu konfigurieren.

Bitte beachten Sie, dass jede Anfrage an das Schweizer Bundesamt für Statistik (BFS) gespeichert wird. Selbst erneute Versuche werden gespeichert und können schnell zu einem Anwachsen der Anzahl der Dateien führen.

Verarbeitung

Sie haben auf der Reiterkarte die Möglichkeit, einige Einstellungen für die Schweizer UID-Prüfung festzulegen. Diese werden bei der Verarbeitung berücksichtigt. Im Folgenden werden diese Einstellungen im Einzelnen beschrieben.

Schweizer UID-Prüfung - Einstellungen UID Verarbeitung
Schweizer UID-Prüfung – Einstellungen UID Verarbeitung

Versuche

Über den eingegebenen Wert der Versuche haben Sie die Möglichkeit, die Anzahl an Wiederholungen einer Prüfung einzustellen. Eine Wiederholung der Anfrage kann ausgelöst werden, wenn die Gegenstelle des BFS ausgelastet ist oder Ihre Netzwerkverbindung zu einem Timeout führt. Jeder Versuch wird, sofern aktiviert, im Audit-Log gespeichert.

Trennzeichen

Das Trennzeichen ist nur für den Import von CSV-Dateien für die Schweizer UID-Prüfung relevant (unabhängig ob Stapelverarbeitung oder Hintergrundverarbeitung). Die Daten werden in einzelne Werte anhand dieses Trennzeichens aufgeteilt und zur Prüfung aufbereitet. Berücksichtigen Sie bitte bei der Einstellung des Trennzeichens auf ein Vorkommen in Ihren Stammdaten. Ein Komma oder ein Semikolon kann u.U. in einem Firmennamen vorkommen und zu einem Fehler in der Verarbeitung führen. Wir haben das Pipe-Zeichen “|” als Standardwert definiert. Für JSON und XLSX ist dieses Trennzeichen nicht notwendig.

Leerzeichen

Werden Leerzeichen in Ihren Stammdaten bei der Erfassung von Schweizer UID-Nummer erlaubt, so kann dies zu Fehlern bei der Prüfung kommen. Diese Einstellung gibt Ihnen die Möglichkeit, dass bei der Prüfung diese ignoriert werden.

Groß- und Kleinschreibung

Sofern die Eingabe von Kleinbuchstaben in Ihren Stammdaten bei der Erfassung von Schweizer UID-Nummer erlaubt ist, so kann dies zu Fehlern bei der Prüfung kommen. Diese Einstellung gibt Ihnen die Möglichkeit, dass bei der Prüfung die Groß- und Kleinschreibung ignoriert wird und auf das richtige Format automatisch gesetzt wird.

Schweizer UID-Nummer bereinigen

Wird diese Option gesetzt, wird die bereinigte Schweizer UID-Nummer (Leerzeichen, Groß- und Kleinschreibung) in der Exportdatei zurückgegeben. Dies bedeutet, dass in Protokolldateien (diese haben den gleichen Aufbau wie die importierte CSV Datei) die Schweizer UID-Nummer ohne diese fehlerhafte Schreibweise ausgegeben werden. Bei einem Reimport in Ihr ERP System kann somit der Datensatz bereinigt werden.

Zeichenkodierung der Ausgabe

Mit dieser Einstellung haben Sie die Möglichkeit, die Codepage der CSV Ausgabe der Schweizer UID-Prüfung zu steuern. Im Standard ist hier UTF-8 angegeben. Wird die CSV Datei mit Microsoft Excel weiterverarbeitet, empfiehlt es sich Win1252 (dies entspricht der ANSI Kodierung) empfohlen.

Sollte die Datensätze in der Ausgabedatei der Schweizer UID-Prüfung in Ihrem Texteditor oder in Microsoft Excel beispielsweise bei Umlauten nicht korrekt dargestellt werden, stellen Sie bitte ebenfalls diesen Parameter auf den jeweils anderen als der bei Ihnen aktuell eingestellten. Dies behebt in den meisten Fällen Darstellungsprobleme.

Hintergrundverarbeitung

Die Verarbeitung im Hintergrund ermöglicht Ihnen die Schweizer UID-Prüfung in regelmäßigen Abständen und automatisch zu verwenden. Einige Einstellungen sind hierbei vorab durchzuführen.

Schweizer UID-Prüfung - Einstellungen UID Hintergrundverarbeitung
Schweizer UID-Prüfung – Einstellungen UID Hintergrundverarbeitung

Nur ungültige Schweizer UID-Nummer in Exportdatei ausgeben

Mit dieser Option haben Sie die Möglichkeit, dass nur ungültige Schweizer UID-Nummern in die Exportdatei ausgegeben werden. Wurde der E-Mail-Versand aktiviert, erhält der Sachbearbeiter entsprechend auch nur diese Einträge aus der importierten Datei zugesandt.

Gerade bei großen Datenmengen oder sehr regelmäßiger Schweizer UID-Prüfungen kann dies das Postfach des Benutzers oder der freigegebenen Gruppe schonen.

Keine Überschriften in CSV Exportdatei

Aktivieren Sie diese Option, damit in der CSV Exportdatei der Schweizer UID-Prüfung keine Überschriften ausgegeben werden.

Verzeichnisse

Damit die Hintergrundverarbeitung die Dateiverarbeitung der Schweizer UID-Prüfung ordnungsgemäß durchführen kann, geben Sie bitte für alle notwendigen Verzeichnisse vollständig an. Bitte beachten Sie, dass die Verzeichnisse sich voneinander unterscheiden müssen, damit es beispielsweise nicht zu einer Endlosschleife der Prüfungen kommt, wenn die Exportdatei immer wieder als zu importierende Datei erkannt wird.

Sind für die Schweizer UID-Prüfung die Verzeichnisse nicht angegeben, kann die Hintergrundverarbeitung nicht durchgeführt werden. Haben Sie Verzeichnisse angegeben, die noch nicht vorhanden sind, versucht die Software diese beim ersten Aufruf anzulegen. Sind nicht die notwendigen Rechte vorhanden oder das Anlegen schlägt fehl, so erhalten Sie eine entsprechende Meldung.

Kommandozeile (cli)

Die Hintergrundverarbeitung kann nicht über die Oberfläche gestartet werden. Um die Hintergrundverarbeitung zu starten, öffnen Sie eine Kommandozeile in dem Verzeichnis, in dem die Datei ew_service_uid.exe liegt und rufen diese mit dem Parameter --mode=auto auf.

Die Hintergrundverarbeitung verarbeitet damit alle Schweizer UID Dateien, die sich im Importverzeichnis befinden. Im Backup-Verzeichnis wird stets eine Kopie der Importdatei abgespeichert und das fertige Prüfergebnis im Exportverzeichnis abgestellt. Im Protokollverzeichnis werden einzelne Verarbeitungsschritte festgehalten.

Der Aufruf für die Schweizer UID-Prüfung mit der Option --mode=auto kann über eine wiederholende Aufgabe oder cronjob eingeplant werden. Das Ausführen der Verarbeitung im Hintergrund kann einige Zeit in Anspruch nehmen. Dies hängt unmittelbar von der Schnittstelle des Schweizer Bundesamtes für Statistik ab.

Parameter

Führen Sie ew_service_uid --help aus und Sie erhalten die Übersicht aller Parameter der Schweizer UID-Prüfung, die Sie an die cli bzw. den Service übergeben können.

Usage of: ew_service_uid.exe [options]
----------------------------------------------------------------------------
-h  --help              Show this help
-v  --version           Version Return the version information.
    --lang              Language (de,en). Overwrites settings.
    --mode              Set the validation mode (single, batch, auto).
    --dataobject        JSON object for single validation mode.
    --inputfile         Input ImportData file for batch validation.
    --outputfile        Output file for batch validation.
    --testmail          Send a testmail.
    --validatefile      Check file, if structure is readable.
----------------------------------------------------------------------------

-h --help

Zeigen Sie sich alle notwendigen Parameter an, die die cli der Schweizer UID-Prüfung unterstützt.

-v --version

Gibt die aktuelle installierte Version der Schweizer UID-Prüfung aus.

--lang

Mit diesem Parameter können Sie die Sprache der Schweizer UID-Prüfung angeben bzw. überschreiben.

--mode

Der Modus, in dem die Schweizer UID-Prüfung ausgeführt werden soll.

--dataobject

Dieser Parameter ist notwendig bei einer einzelnen Prüfung einer Schweizer UID-Nummer.

-i --inputfile

Übergeben Sie mit diesem Parameter die Datei mit zu importierenden Daten für die Schweizer UID-Prüfung an.

-o --outputfile

Die Exportdatei für die Schweizer UID-Prüfung wird mit diesem Parameter angegeben. Wichtig ist, dass dieser nicht identisch mit der Importdatei ist.

--testmail

Testen Sie aus der Schweizer UID-Prüfung heraus einen Versand einer Test-E-Mail durch. Nach der Verarbeitung einer Datei kann Ihnen am Ende eine E-Mail zugesandt werden.

--validatefile

Überprüfen Sie die Importdatei der Schweizer UID-Prüfung zuvor auf Ihre formale Richtigkeit.

Ausgaben der Kommandozeile

Alle Ausgaben sind im JSON Format und variieren nach Ihren Rückgabewerten.

CSV Schnittstelle

Wir empfehlen die Nutzung der XLSX oder JSON Importschnittstellen.

Durch die Verwendung einer einfachen CSV-Datei bietet Ihnen der Schweizer UID-Prüfung eine Möglichkeit, Ihren gesamten Datenbestand zu überprüfen.

Wir achten darauf, dass bei der Erweiterung der Schnittstelle für den Import von CSV der Software Schweizer UID-Prüfung die Kompatibilität gewahrt bleibt. Damit können Sie jeweils die aktuellste Version einsetzen, ohne zusätzlichen Aufwand bei einer Integration in Ihr ERP System zu generieren.

Um die Zugehörigkeit der einzelnen Schweizer UID Datensätze in Ihre Stammdaten zu gewährleisten, haben Sie die Möglichkeit, bis zu zwei eindeutige Schlüssel in der Importdatei anzugeben. Diese werden in der Exportdatei wieder zurückgegeben und können für den Reimport in Ihr ERP System genutzt werden. Sie können diese beiden Felder (Schluessel_1 und Schluessel_2) auch leer lassen.

Das Standard-Trennzeichen der einzelnen Elemente für die Schweizer UID-Prüfung ist das ‚|‘-Zeichen (pipe). Dieses kann über die Einstellungen geändert werden. Fettgedruckte Feldnamen sind Pflichtfelder (das Trennzeichen über Einstellungen änderbar).

Da die Schweizer UID-Schnittstelle auch den Namen und Adresse zurück gibt, werden wir in einem zukünftigen Release der Schweizer UID-Prüfung auch eine Überprüfung Ihrer hinterlegten Daten ermöglichen und die CSV Schnittstelle erweitern.

Bitte beachten Sie, dass alle Felder in der Importdatei der Schweizer UID-Prüfung angegeben werden müssen, auch wenn Sie Schluessel_1 und Schluessel_2 nicht verwenden.

Aufbau – CSV Importdatei

FeldFormatBeispiel
Schluessel_1String4711
Schluessel_2String2
UIDStringCHE123456

Beispiel in Form einer CSV-Datei:
4711|2|CHE123456 … (weitere Schweizer UID-Prüfungen)

Hinweis

Bitte achten Sie bei dem Erstellen der Schweizer UID-Importdatei auf die korrekte Anzahl an Spalten (3 Spalten). Dieser Hinweis ist wichtig für eventuelle Fehler beim Import bei der Verwendung von CSV. Zukünftig werden wir weitere Importformate unterstützen, die diese Einschränkung nicht mehr haben.

Aufbau – CSV Exportdatei

Die CSV-Exportdatei der Schweizer UID-Prüfung beinhaltet die zurückgegebenen Werte der einzelnen Prüfungen.

FeldFormatBeispiel
key1String4711
key2String2
uidStringCHE123456
nameStringMusterfirma
streetStringMusterstraße 1
postalCodeString12345
cityStringMusterdorf
countryStringDeutschland
statusString0
errorReasonString 
requestdateString 

Beispiel in Form einer CSV-Datei (mit Standard-Trennzeichen):

4711|2|CHE123456|Musterfirma||Musterstraße 1|12345|Musterdorf|Schweiz|0|Valid||

Die Benennung der Felder der Schweizer UID-Prüfung innerhalb der CSV Import bzw. Exportdatei erfolgt in deutscher Sprache. Im Zuge der Erweiterung der Importformate werden diese internationalisiert, d.h. wir werden die Feldnamen zukünftig in englischer Sprache führen. Eine Konfiguration der Feldnamen haben wir allerdings angedacht, um die Flexibilität zu erhöhen.

Die Ausgabe der Exportdatei im CSV Format der Schweizer UID-Prüfung beinhaltet stets eine zusätzliche Spalte, in der die Überschriften enthalten sind. Bitte beachten Sie dies bei einem eventuellen automatischen Reimport der Prüfungsergebnisse.

JSON Schnittstelle

Mit der Schnittstelle für den Import für JSON Dateien, bietet Ihnen die Schweizer UID-Prüfung eine Möglichkeit, Ihren gesamten Datenbestand aus Ihren Stammdaten heraus zu überprüfen.

Wir achten darauf, dass bei der Erweiterung der JSON Schweizer UID-Schnittstelle die Kompatibilität stets gewahrt bleibt. Damit können Sie jeweils die aktuellste Version einsetzen, ohne zusätzlichen Aufwand bei einer Integration in Ihr ERP System zu generieren.

Um einen JSON Datensatz aus Ihrem ERP System eindeutig in der Schweizer UID-Prüfung zuordnen zu können, haben Sie die Möglichkeit, bis zu zwei eindeutige Schlüssel in der Importdatei anzugeben. Diese werden in der Exportdatei wieder zurückgegeben und können für den Reimport in Ihr ERP System genutzt werden. Sie können diese beiden Felder (key1 und key2) jedoch auch leer lassen. Diese sind für die Verarbeitung nicht notwendig.

Da die Schweizer UID-Schnittstelle auch den Namen und Adresse zurück gibt, werden wir in einem zukünftigen Release der Schweizer UID-Prüfung auch eine Überprüfung Ihrer hinterlegten Daten ermöglichen und die JSON Schnittstelle erweitern.

Bitte beachten Sie, dass alle fettgedruckten Felder in der Importdatei angegeben werden müssen.

Aufbau – JSON Importdatei

KeyFormatBeispiel
key1String4711
key2String2
uidStringCHE123456

Beispiel in Form einer JSON-Datei mit zwei Einträgen:

[
    {
    "key1": "a",
    "key2": "b",
    "uid": "CHE123456"
    },
    {
    "key1": "a",
    "key2": "b",
    "uid": "CHE789012"
    }
]

Aufbau – JSON Exportdatei

Die JSON-Exportdatei der Schweizer UID-Prüfung beinhaltet die zurückgegebenen Werte der einzelnen Prüfungen, ebenfalls, sofern nicht anders angegeben, im gleichen Datenformat. Bitte beachten Sie, dass die JSON Schnittstelle alle verfügbaren Felder ausgibt und somit das vollständigste Format darstellt.

FeldFormatBeispiel
key1String4711
key2String2
uidStringCHE123456
nameStringMusterfirma
streetStringMusterstraße 1
postalCodeString12345
cityStringMusterdorf
countryStringDeutschland
statusString0
errorReasonString 
requestdateString 

Beispiel in Form einer JSON-Datei:

[
 {
  "uid": "CHE1537016",
  "status": "0",
  "statusDescr": "Valid",
  "name": "Musterfirma",
  "street": "Musterstraße 1",
  "postalCode": "12345",
  "city": "Musterdorf",
  "country": "Germany",
  "requestdate": "30/01/2021",
  "key1": "4711",
  "key2": "2"
 }
]

Im Gegensatz zu XLSX oder CSV haben wir uns auf die rein englische Notation der Schlüssel der Schweizer UID-Prüfung innerhalb von JSON geeinigt. Damit können wir von vorneherein Laufzeitfehler bei einer fehlerhaften Konvertierung vermeiden.

Bitte beachten Sie, dass die Felder in der Exportdatei der Schweizer UID-Prüfung nicht immer in der gleichen Reihenfolge ausgegeben werden, wie in der obigen Tabelle angegeben.

XLSX Schnittstelle

Mit der Importschnittstelle für Microsoft Excel (XLSX) Datei, bietet Ihnen die Schweizer UID-Prüfung eine Möglichkeit, Ihren gesamten Datenbestand aus Ihren Stammdaten heraus zu überprüfen.

Wir achten darauf, dass bei der Erweiterung der XLSX Schweizer UID-Schnittstelle die Kompatibilität (auch zu Microsoft Excel) gewahrt bleibt. Damit können Sie jeweils die aktuellste Version einsetzen, ohne zusätzlichen Aufwand bei einer Integration in Ihr ERP System zu generieren.

Um einen XLSX Datensatz aus Ihrem ERP System eindeutig in der Schweizer UID-Prüfung zuordnen zu können, haben Sie die Möglichkeit, bis zu zwei eindeutige Schlüssel in der Importdatei anzugeben. Diese werden in der Exportdatei wieder zurückgegeben und können für den Reimport in Ihr ERP System genutzt werden. Sie können diese beiden Felder (Schluessel_1 und Schluessel_2) jedoch auch leer lassen.

Da die Schweizer UID-Schnittstelle auch den Namen und Adresse zurück gibt, werden wir in einem zukünftigen Release der Schweizer UID-Prüfung auch eine Überprüfung Ihrer hinterlegten Daten ermöglichen und die XLSX Schnittstelle erweitern.

Bitte beachten Sie, dass alle hervorgehobenen Felder in der Schweizer UID Importdatei angegeben werden müssen.

Die Bezeichnungen der Spaltenüberschriften der Schweizer UID-Prüfung werden beim Import innerhalb der XLSX Datei gesucht und beim Import zugeordnet. Bitte geben Sie jeweils immer nur eine Bezeichnung ein, bspw. “key1” und nicht “key1,schluessel_1”.

Die Groß- und Kleinschreibung der Spaltenüberschriften ist nicht relevant für den Import.

Aufbau – XLSX Importdatei

Spaltenüberschrift (1. Zeile!)FormatBeispiel
key1 oder schluessel_1String4711
key2 oder schluessel_2String2
UIDStringCHE123456

Aufbau – XLSX Exportdatei

Die XLSX-Exportdatei der Schweizer UID-Prüfung beinhaltet die zurückgegebenen Werte der einzelnen Prüfungen, ebenfalls, sofern nicht anders angegeben, im gleichen Datenformat.

FeldFormatBeispiel
key1String4711
key2String2
uidStringCHE123456
nameStringMusterfirma
streetStringMusterstraße 1
postalCodeString12345
cityStringMusterdorf
countryStringDeutschland
statusString0
errorReasonString 
requestdateString 

XLSX Versionen

Wir unterstützen in der Schweizer UID-Prüfung alle XLSX Versionen bis einschließlich neuster Version von Office 365. Bitte haben Sie Verständnis dafür, dass wir ältere Versionen (XLS) nicht mehr unterstützen werden.

Unser Testumfang für die Software Schweizer UID-Prüfung beinhaltet sehr viele verschiedene Varianten, wie ein Microsoft Excel-Dokument aussehen kann. Dennoch konnten wir nicht alles Funktionen und Möglichkeiten prüfen. Sollten Sie beim Import von XLSX Dateien auf ein Problem stoßen, kontaktieren Sie uns und senden uns bitte ein oder zwei Testdatensätze zu, damit wir Ihnen schnell helfen können.