Mit dem PowerShell-Skript Connect-Import.ps1 können Sie eine CSV-Datei in ein bestehendes Monitoring-Portfolio der Creditsafe Connect API importieren.

Das Skript übernimmt automatisch die Prüfung der CSV-Datei, die Authentifizierung an der API, den Upload und die Übergabe an das angegebene Monitoring-Portfolio.

Voraussetzungen

Sie benötigen:

• Windows 10 oder Windows 11
• Windows PowerShell oder PowerShell 7
• curl.exe
• gültige Zugangsdaten für die Creditsafe Connect API
• eine gültige Monitoring-Portfolio-ID
• eine CSV-Datei im vorgesehenen Monitoring-Importformat
• eine aktive Internetverbindung
• Zugriff auf https://connect.creditsafe.com

Prüfen Sie die Verfügbarkeit von curl.exe mit:

curl.exe --version

Wird eine Versionsnummer angezeigt, ist cURL verfügbar.

Bereitgestellte Dateien

Für den Import werden mindestens folgende Dateien benötigt:

C:\Creditsafe-Import\ ├── Connect-Import.ps1 └── Beispiel-import.csv

Die CSV-Datei muss nicht im gleichen Ordner wie das Skript liegen. Es kann auch ein relativer oder vollständiger Dateipfad angegeben werden.

1. Skript konfigurieren

Öffnen Sie Connect-Import.ps1 mit einem Texteditor, beispielsweise dem Windows-Editor, Notepad++, Visual Studio Code oder PowerShell ISE.

Tragen Sie im Abschnitt Konfiguration Ihre Daten ein:

$BaseUrl = 'https://connect.creditsafe.com/v1' $PortfolioId = 1234567 $Username = 'benutzername@unternehmen.de' $Password = 'IhrPasswort'

Portfolio-ID

Ersetzen Sie die Beispiel-ID durch die ID des Monitoring-Portfolios:

$PortfolioId = 1234567

Die Portfolio-ID muss numerisch sein und für den verwendeten Creditsafe-Zugang erreichbar sein.

Benutzername und Passwort

Tragen Sie Ihre Zugangsdaten ein:

$Username = 'benutzername@unternehmen.de' $Password = 'IhrPasswort'

Da das Passwort in einfachen Anführungszeichen steht, werden PowerShell-Sonderzeichen wie $ nicht als Variable interpretiert.

Beispiel:

$Password = 'Beispiel$Passwort!123'

Speichern Sie das Skript anschließend.

Sicherheit: Benutzername und Passwort werden in dieser Skriptversion direkt im Skript gespeichert. Schützen Sie die Datei vor unbefugtem Zugriff und geben Sie sie nicht mit eingetragenen Zugangsdaten weiter.

2. CSV-Importdatei vorbereiten

Die CSV-Datei muss das vorgegebene Monitoring-Importformat verwenden.

Sie enthält sechs Spalten in dieser Reihenfolge:

"Safe No/ID","Local Org No.","Country Code","Optional Reference","Optional Free Text","Optional Personal Limit"

Bedeutung der Spalten

Identifikation über die Safe Number

Die empfohlene Variante ist die Verwendung der Creditsafe Safe Number in der ersten Spalte:

"Safe No/ID","Local Org No.","Country Code","Optional Reference","Optional Free Text","Optional Personal Limit" "DE02104336","","DE","","","" "DE01485454","","DE","","",""

Dabei gilt:

• Safe No/ID: Safe Number
• Local Org No.: leer
• Country Code: zweistelliger Ländercode
• optionale Felder: können leer bleiben

Alternativ kann in der ersten Spalte eine Connect ID verwendet werden, beispielsweise:

DE-0-DE12345678

Identifikation über die lokale Organisationsnummer

Ist keine Safe Number oder Connect ID vorhanden, kann die lokale Organisationsnummer verwendet werden:

"Safe No/ID","Local Org No.","Country Code","Optional Reference","Optional Free Text","Optional Personal Limit" "","HRB123456","DE","","",""

Dabei gilt:

• Safe No/ID: leer
• Local Org No.: lokale Organisationsnummer
• Country Code: erforderlich
• optionale Felder: können leer bleiben

Der Country Code ist erforderlich, weil Registrierungsnummern in unterschiedlichen Ländern gleich aufgebaut sein können.

Optionale Felder

Die optionalen Felder können für interne Informationen genutzt werden:

"Safe No/ID","Local Org No.","Country Code","Optional Reference","Optional Free Text","Optional Personal Limit" "DE02104336","","DE","KUNDE-10025","Strategischer Kunde","25000"

Hierbei können beispielsweise Kundennummer, interne Notiz und ein eigener Grenzwert hinterlegt werden.

Der Optional Personal Limit ist ein kundenspezifischer interner Wert und kein von Creditsafe berechnetes oder empfohlenes Kreditlimit.

Pflichtregeln für Datenzeilen

Für jede Datenzeile gilt:

1. Es muss eine Safe Number, Connect ID oder lokale Organisationsnummer vorhanden sein.
2. Bei Verwendung der lokalen Organisationsnummer bleibt Safe No/ID leer.
3. Bei Verwendung der lokalen Organisationsnummer muss der Country Code angegeben werden.
4. Der Country Code muss ein zweistelliger ISO-Code sein.
5. Nicht verwendete optionale Felder bleiben leer.
6. Die sechs Spalten müssen in der vorgegebenen Reihenfolge erhalten bleiben.
7. Jede Datenzeile darf nur ein Unternehmen enthalten.

Trennzeichen und Dateiformat

Die Datei verwendet ein Komma als Spaltentrennzeichen und doppelte Anführungszeichen für die Werte:

"DE02104336","","DE","","",""

Die Anzahl der Felder muss in jeder Datenzeile mit der Kopfzeile übereinstimmen.

Bearbeitung mit Excel

Beim Öffnen und erneuten Speichern einer CSV-Datei mit Microsoft Excel können unter anderem folgende Werte verändert werden:

• Trennzeichen
• führende Nullen
• Datumswerte
• lange Nummern
• Zeichenkodierung
• Anführungszeichen

Insbesondere deutschsprachige Excel-Versionen können CSV-Dateien mit Semikolon statt Komma speichern.

Nicht vorgesehen ist beispielsweise:

"DE02104336";"";"DE";"";"";

Prüfen Sie die Datei nach der Bearbeitung deshalb bei Bedarf mit einem Texteditor.

3. PowerShell öffnen

Öffnen Sie PowerShell und wechseln Sie in den Ordner, in dem sich das Skript befindet:

cd 'C:\Creditsafe-Import'

Mit folgendem Befehl können Sie den Inhalt des Ordners anzeigen:

Get-ChildItem

4. Import starten

CSV-Datei im gleichen Ordner

.\Connect-Import.ps1 'Beispiel-import.csv'

Alternativ:

.\Connect-Import.ps1 -CsvFile 'Beispiel-import.csv'

Beide Aufrufe sind gleichwertig.

CSV-Datei in einem Unterordner

.\Connect-Import.ps1 '.\Importdateien\Beispiel-import.csv'

Vollständiger Dateipfad

.\Connect-Import.ps1 'C:\Users\Benutzer\Downloads\Beispiel-import.csv'

Dateipfad mit Leerzeichen

Enthält der Pfad Leerzeichen, muss er in Anführungszeichen stehen:

.\Connect-Import.ps1 'C:\Import Dateien\Beispiel Import.csv'

Alternative Parameternamen

Da CsvFile der erste Parameter des Skripts ist, kann der Dateipfad auch ohne Parameternamen angegeben werden.

Zusätzlich können die Aliase File und Filename verwendet werden:

.\Connect-Import.ps1 -File 'Beispiel-import.csv'

.\Connect-Import.ps1 -Filename 'Beispiel-import.csv'

Skript über vollständigen Pfad starten

Das Skript kann auch aus einem anderen PowerShell-Verzeichnis gestartet werden:

& 'C:\Creditsafe-Import\Connect-Import.ps1' `    'C:\Importdateien\Beispiel-import.csv'

Das Zeichen & ist der PowerShell-Aufrufoperator und ermöglicht die Ausführung eines Skripts über einen vollständigen Pfad.

5. Ausführungsrichtlinie

Beim ersten Start kann PowerShell die Ausführung des Skripts blockieren.

Falls die Meldung erscheint, dass die Ausführung von Skripts auf dem System deaktiviert ist, können Sie die Ausführung für die aktuelle PowerShell-Sitzung erlauben:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Starten Sie anschließend das Skript erneut:

.\Connect-Import.ps1 'Beispiel-import.csv'

Die Einstellung gilt nur für das aktuell geöffnete PowerShell-Fenster und wird nach dessen Schließen zurückgesetzt.

Alternativ kann das Skript einmalig mit einer Umgehung der Ausführungsrichtlinie gestartet werden:

powershell.exe -ExecutionPolicy Bypass `    -File '.\Connect-Import.ps1' `    'Beispiel-import.csv'

6. Ablauf des Imports

Nach dem Start führt das Skript automatisch mehrere Schritte aus.

CSV-Datei prüfen

Bei einem relativen Dateipfad sucht das Skript zunächst im aktuellen PowerShell-Arbeitsverzeichnis und anschließend im Verzeichnis des Skripts.

Wird die Datei gefunden, wird der Pfad angezeigt.

Authentifizierung

Anschließend authentifiziert sich das Skript an der Creditsafe Connect API und speichert das erhaltene Zugriffstoken für die aktuelle Skriptausführung.

Bei erfolgreicher Authentifizierung erscheint beispielsweise:

Authentifizierung erfolgreich. 
Token wurde gespeichert.

Import starten

Anschließend werden unter anderem Portfolio-ID und CSV-Datei angezeigt:

Portfolio-ID: 1234567 CSV-Datei: C:\Creditsafe-Import\Beispiel-import.csv 
Import wird gestartet ...

API-Antwort

Bei erfolgreicher Übergabe erscheint beispielsweise:

Die Importanfrage wurde erfolgreich übermittelt. 
correlationId : 23921650-c073-11ea-860f-06bc8182190e status        : Accepted for processing. Import Id 339523

Die Meldung bedeutet, dass die API die Importanfrage angenommen und zur Verarbeitung übergeben hat.

Wichtig: Die erfolgreiche Annahme bedeutet nicht automatisch, dass jede einzelne Zeile der CSV-Datei erfolgreich importiert wurde. Die inhaltliche Verarbeitung erfolgt anschließend durch den Monitoring-Importdienst.

7. Verhalten bei bereits vorhandenen Unternehmen

Der Import ergänzt das bestehende Monitoring-Portfolio.

Bereits im Portfolio vorhandene Unternehmen beziehungsweise Duplikate innerhalb der Importdatei werden übersprungen. Bestehende Unternehmen werden durch den Import nicht entfernt.

Das Skript verwendet ausschließlich die Importfunktion und keine Synchronisation.

• Import: ergänzt das Portfolio um neue Unternehmen.
• Synchronisation: würde den bisherigen Portfolioinhalt durch den Inhalt der übergebenen Datei ersetzen.

8. Größere CSV-Dateien

Für eine schnellere Verarbeitung empfiehlt Creditsafe möglichst kleine CSV-Dateien. Laut Dokumentation werden Dateien unter 50 KB typischerweise schneller verarbeitet.

Größere Datenbestände können auf mehrere Dateien aufgeteilt werden:

Import-Teil-01.csv Import-Teil-02.csv Import-Teil-03.csv

Diese können anschließend nacheinander importiert werden:

.\Connect-Import.ps1 '.\Import-Teil-01.csv' .\Connect-Import.ps1 '.\Import-Teil-02.csv' .\Connect-Import.ps1 '.\Import-Teil-03.csv'

9. Aufruf über eine Batch-Datei

Das Skript kann bei Bedarf über eine Windows-Batch-Datei gestartet werden.

Erstellen Sie beispielsweise eine Datei Start-Import.bat mit folgendem Inhalt:

@echo off powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0Connect-Import.ps1" "%~1" pause

Start mit einer CSV-Datei:

Start-Import.bat "C:\Importdateien\Beispiel-import.csv"

Befindet sich die CSV-Datei im gleichen Ordner:

Start-Import.bat "Beispiel-import.csv"

%~dp0 verweist auf den Ordner, in dem sich die Batch-Datei befindet.

10. Häufige Fehlermeldungen

CSV-Datei wurde nicht gefunden

Prüfen Sie:

• Dateiname und Dateipfad
• tatsächliche Dateiendung
• relative und absolute Pfade
• zusätzliche Leerzeichen im Dateinamen

Mit folgendem Befehl können Sie die Dateien im aktuellen Ordner anzeigen:

Get-ChildItem -File

Achten Sie außerdem darauf, dass die Datei nicht versehentlich beispielsweise Beispiel-import.csv.csv heißt.

Die angegebene Datei ist keine CSV-Datei

Das Skript akzeptiert nur Dateien mit der Endung .csv.

Prüfen Sie im Windows-Explorer die tatsächliche Dateiendung. Aktivieren Sie bei Bedarf:

Ansicht → Anzeigen → Dateinamenerweiterungen

curl.exe wurde nicht gefunden

Prüfen Sie:

Get-Command curl.exe

oder:

curl.exe --version

Ist cURL nicht verfügbar, wenden Sie sich an Ihre IT-Abteilung.

Authentifizierung fehlgeschlagen

Mögliche Ursachen sind:

• falscher Benutzername oder falsches Passwort
• gesperrtes oder deaktiviertes Benutzerkonto
• fehlende API-Berechtigung
• unterbrochene Internetverbindung
• Firewall oder Proxy
• nicht erreichbare Creditsafe Connect API

Prüfen Sie insbesondere die Zugangsdaten im Skript.

Die Erreichbarkeit der API kann beispielsweise mit folgendem Befehl geprüft werden:

Test-NetConnection connect.creditsafe.com -Port 443

Die Antwort enthält kein Token

Die Authentifizierungsanfrage wurde beantwortet, die Antwort enthält jedoch kein verwertbares Zugriffstoken.

Prüfen Sie Zugangsdaten, API-Berechtigungen und die vollständige Fehlermeldung.

HTTP 400 – Bad Request

Die Anfrage oder Importdatei ist möglicherweise ungültig.

Prüfen Sie insbesondere:

• CSV-Format
• Spaltenüberschriften und Reihenfolge
• Unternehmenskennungen
• Trennzeichen
• fehlerhafte oder unvollständige Zeilen

HTTP 401 – Unauthorized

Die Authentifizierung wurde nicht akzeptiert.

Prüfen Sie:

• Benutzername
• Passwort
• API-Zugang
• Gültigkeit des Tokens

Das Skript authentifiziert sich bei jedem Start neu.

HTTP 403 – Forbidden

Der Benutzer wurde erkannt, verfügt aber möglicherweise nicht über die erforderlichen Berechtigungen.

Mögliche Ursachen:

• fehlende Berechtigung für Global Monitoring
• kein Zugriff auf das angegebene Portfolio
• Portfolio gehört zu einem anderen Creditsafe-Konto
• Importfunktion ist für den Zugang nicht freigeschaltet

HTTP 404 – Not Found

Prüfen Sie die angegebene Portfolio-ID:

$PortfolioId = 1234567

Das Monitoring-Portfolio muss existieren und für den verwendeten Zugang erreichbar sein.

HTTP 500 – Internal Server Error

Es liegt möglicherweise ein serverseitiger Fehler vor.

Versuchen Sie den Import später erneut. Bleibt der Fehler bestehen, übermitteln Sie dem zuständigen Support:

• vollständige Fehlermeldung
• Portfolio-ID
• Zeitpunkt des Aufrufs

11. Sicherheit

Da Benutzername und Passwort in der vorliegenden Skriptversion direkt in der PowerShell-Datei gespeichert werden:

• speichern Sie das Skript nur in einem geschützten Verzeichnis,
• beschränken Sie den Zugriff auf berechtigte Benutzer,
• versenden Sie das Skript nicht unverschlüsselt mit eingetragenen Zugangsdaten,
• laden Sie das Skript nicht in öffentliche Dateiablagen oder Versionsverwaltungssysteme hoch.

Für automatisierte Prozesse empfiehlt sich die Verwendung eines dafür vorgesehenen technischen Benutzerkontos.

Die Dateiberechtigungen können beispielsweise über Eigenschaften → Sicherheit im Windows-Explorer eingeschränkt werden.

12. Empfohlene Ordnerstruktur

Für eine übersichtliche Ablage kann folgende Struktur verwendet werden:

C:\Creditsafe-Import\ ├── Connect-Import.ps1 ├── Eingabe\ │   └── Beispiel-import.csv └── Archiv\

Der Import wird beispielsweise gestartet mit:

cd 'C:\Creditsafe-Import' 
.\Connect-Import.ps1 '.\Eingabe\Beispiel-import.csv'

Nach erfolgreicher Verarbeitung kann die CSV-Datei bei Bedarf manuell in das Archiv verschoben werden.

Kurzfassung

1. Connect-Import.ps1 öffnen.
2. Portfolio-ID, Benutzername und Passwort eintragen.
3. CSV-Datei im erforderlichen Format vorbereiten.
4. PowerShell öffnen und in den Skriptordner wechseln.
5. Skript mit der CSV-Datei starten:

.\Connect-Import.ps1 'Beispiel-import.csv'

6. Ausgabe des Skripts prüfen.
7. Bei erfolgreicher Übergabe erscheint:

Die Importanfrage wurde erfolgreich übermittelt.

Die API-Antwort enthält außerdem eine Correlation ID und eine Import ID, über die der Import technisch nachvollzogen werden kann.