Zum Inhalt

Mit KSeF verbinden

Diese Anleitung beschreibt, wie Sie eine Organisation in xTool mit KSeF (Krajowy System e-Faktur), dem polnischen nationalen E-Rechnungssystem, verbinden.

Nach der Aktivierung kann xTool strukturierte Rechnungen im Format KSeF FA(3) senden und eingehende Rechnungen aus KSeF empfangen.

Was Sie brauchen

  • Zugriff auf die xTool-Webanwendung und die Organisation, die Sie verbinden möchten.
  • Recht Integrationen verwalten. Zum Anzeigen der Seite reicht Integrationen lesen. Das Senden an KSeF ist ein eigenes Recht, das Member und Administrator besitzen, Viewer dagegen nicht. Siehe Organisation und Benutzer.
  • Die NIP des Unternehmens (10 Ziffern).
  • Ein KSeF-Authentifizierungszertifikat (Typ 1), ausgestellt für diese NIP:
  • Datei mit privatem Schlüssel im PEM-Format (.key oder .pem, die Datei beginnt mit -----BEGIN)
  • Zertifikatdatei (.crt oder .pem, PEM oder DER)
  • das Key-Passwort, wenn der private Schlüssel verschlüsselt ist (KSeF setzt beim Generieren eines; bei unverschlüsseltem Schlüssel das Feld leer lassen)

xTool verwendet keine KSeF-Token. Nur ein Authentifizierungszertifikat vom Typ 1 funktioniert. Ein Offline-Zertifikat (Typ 2) kann nicht zum Verbinden verwendet werden.

Gültigkeit des Zertifikats

Ein KSeF-Zertifikat ist in der Regel zwei Jahre ab Ausstellungsdatum gültig (oder ab dem Startdatum, das Sie beim Antrag gewählt haben). Ist es abgelaufen, deaktivieren Sie die Integration und verbinden Sie sie mit einem neuen Zertifikat erneut.

KSeF-Authentifizierungszertifikat beziehen

Stellen Sie das Zertifikat in der offiziellen Aplikacja Podatnika KSeF 2.0 (Taxpayer Application) für dasselbe Umfeld aus, das Ihre xTool-Instanz verwendet.

xTool-Umgebung Taxpayer Application
Produktion https://ap.ksef.mf.gov.pl
Test https://ap-test.ksef.mf.gov.pl
Demo / Vorproduktion https://ap-demo.ksef.mf.gov.pl

Ein Zertifikat aus dem Test-KSeF funktioniert nicht gegen Produktion und umgekehrt.

Ihre xTool-Instanz ist an genau eine KSeF-Umgebung gebunden, die beim Deployment festgelegt wird. Die Weboberfläche zeigt nicht an, welche das ist — fragen Sie im Zweifel beim Support nach.

Offizielle Hintergrundinformationen: KSeF-Zertifikate.

  1. Öffnen Sie die Taxpayer Application der passenden Umgebung und melden Sie sich an (Profil Zaufany, qualifizierte elektronische Signatur oder qualifiziertes elektronisches Siegel).
  2. Authentifizieren Sie sich im NIP-Kontext des Unternehmens, den Sie in xTool verwenden.
  3. Gehen Sie zu Zertifikate → Zertifikat beantragen (Certyfikaty → Wnioskuj o certyfikat).
  4. Zertifikatnamen und Passwort eingeben, dann auf Generieren klicken.
  5. Die heruntergeladene .key-Datei sofort speichern. Den privaten Schlüssel können Sie nicht erneut herunterladen.
  6. Als Verwendungszweck Authentifizierung in KSeF wählen (Uwierzytelnienie w systemie KSeF). Nicht die Offline-/Ausstellerprüfungs-Option wählen.
  7. Antrag senden, Status aktualisieren, dann Zertifikat herunterladen klicken. Die .crt-Datei speichern.

Bewahren Sie die .key-Datei, die .crt-Datei und das Passwort sicher auf. Das Finanzministerium kann einen verlorenen privaten Schlüssel oder ein Passwort nicht wiederherstellen.

Das in der Taxpayer Application erstellte Passwort muss in der Regel mindestens 15 Zeichen lang sein und einen Großbuchstaben, einen Kleinbuchstaben, eine Ziffer und ein Sonderzeichen enthalten.

In xTool verbinden

Das tun Sie einmal pro Organisation.

  1. Bei xTool anmelden und die Organisation wählen.
  2. Kanäle → KSeF öffnen.
  3. Auf Aktivieren klicken.

  4. Das Formular ausfüllen:

    Feld Was eintragen
    NIP Steuernummer des Unternehmens, genau 10 Ziffern
    Private-Key-Datei Die .key- oder .pem-Datei aus der Taxpayer Application, im PEM-Format
    Zertifikatdatei Die .crt- oder .pem-Datei aus der Taxpayer Application
    Key-Passwort Optional. Das Passwort, das Sie beim Generieren des Zertifikats gesetzt haben. Leer lassen, wenn der private Schlüssel nicht verschlüsselt ist

  5. Auf Speichern klicken.

Bei Erfolg zeigt die Seite die NIP und den Zeitpunkt der Aktivierung.

Schlägt die Authentifizierung fehl, wird nichts gespeichert. Prüfen Sie NIP, Zertifikattyp, Dateien, Passwort und ob das Zertifikat zur selben KSeF-Umgebung gehört wie diese xTool-Instanz.

Nach dem Verbinden

  • Senden über die Weboberfläche — Dokument im Format ksef_fa.invoice.3_0.xml erstellen oder hochladen. Unter Dokumente → Ausgehend öffnen und Senden → Per KSeF senden wählen. Die Aktion erscheint nur bei Dokumenten in diesem Format.
  • Senden über die API — POST /api/v2/documents/{document_id}/send mit {"transaction_type": "send.ksef"}. Siehe API-Referenz und Transaktionen.
  • Senden per SFTP — Datei mit +fa3 im Namen hochladen, z. B. 68451+fa3.xml (XML-Konvertierung) oder Scan 603275+fa3.pdf (PDF-Erkennung, keine XML-Konvertierung). xTool erzeugt FA(3) und übermittelt automatisch an KSeF; in der Weboberfläche ist kein weiterer Schritt nötig. Siehe Senden und Empfangen per SFTP.
  • Empfangen — xTool importiert eingehende KSeF-Rechnungen für verbundene Organisationen zweimal täglich. Sie erscheinen unter Dokumente → Eingehend als receive.ksef.
  • Status — Zeigt die KSeF-Seite KSeF-Authentifizierung fehlgeschlagen, ist das Zertifikat in der Regel abgelaufen oder widerrufen. Deaktivieren Sie die Integration und verbinden Sie sie mit einem gültigen Zertifikat erneut.

Die PDF-Vorschau in xTool dient nur der Anzeige. Sie ist nicht die offizielle KSeF-Visualisierung. Laden Sie das offizielle PDF bei Bedarf aus der Taxpayer Application herunter.

Trennen

Sie können die KSeF-Verbindung jederzeit entfernen.

  1. Kanäle → KSeF öffnen.
  2. Auf Deaktivieren klicken und bestätigen.

Senden und Empfangen über KSeF stoppen für diese Organisation. Bereits in xTool vorhandene Dokumente werden nicht gelöscht.

Zum erneuten Verbinden müssen Sie die Zertifikatdateien wieder hochladen.

Häufige Probleme

Situation Bedeutung Was tun
KSeF-Authentifizierung fehlgeschlagen KSeF hat Zertifikat, NIP oder Umgebung abgelehnt. Ein Authentifizierungszertifikat Typ 1 für diese NIP aus derselben KSeF-Umgebung wie xTool verwenden. Key-Passwort erneut eingeben.
Schlüssel/Zertifikat konnte nicht geladen werden Der private Schlüssel ist nicht als PEM lesbar, Schlüssel und Zertifikat gehören nicht zusammen, oder das Passwort ist falsch. Die gemeinsam erzeugten .key- und .crt-Dateien hochladen; der private Schlüssel muss im PEM-Format vorliegen. Das in der Taxpayer Application gesetzte Passwort eingeben oder leer lassen, wenn der Schlüssel nicht verschlüsselt ist.
KSeF-Konfiguration für Organisation … existiert bereits Diese Organisation ist bereits verbunden. Die Weboberfläche blendet Aktivieren dann aus, diesen Fehler sehen Sie also nur bei API-Aufrufen. Zuerst Deaktivieren, wenn Sie das Zertifikat ersetzen müssen.
Zertifikat abgelaufen KSeF-Zertifikate gelten etwa zwei Jahre. Ein neues Zertifikat Typ 1 ausstellen und erneut verbinden.
Falsche Taxpayer Application Test-, Demo- und Produktionszertifikate sind nicht austauschbar. Das Zertifikat in der Umgebung erzeugen, die zu dieser xTool-Instanz passt.

Nächste Schritte