Senden und Empfangen per SFTP

Diese Anleitung beschreibt den Datenaustausch mit xTool per SFTP: Zugang einrichten, Dateien benennen und hochladen, Antwort-XML lesen und eingehende Dokumente empfangen.

Für CSV-Import per SFTP siehe CSV-Import per SFTP und Dokumente importieren.

Was SFTP ist

xTool stellt für Ihre Organisation einen SFTP-Server bereit. Nach der Aktivierung in der Web-App zeigt xTool Host, Port und Benutzername — Sie wählen ein Passwort (oder nutzen einen privaten Schlüssel). Ihr ERP oder Integrationsclient verbindet sich mit diesem Server und legt Dateien im Ordner upload ab; xTool verarbeitet sie und schreibt Status-XML in Antwortordner.

Unterstützte Dateitypen entsprechen dem Web-Upload: XML- und PDF-Rechnungen und -Gutschriften in unterstützten Formaten sowie xTool-CSV für den Import.

Zugang einrichten

1. Melden Sie sich in der xTool-Web-App an und wählen Sie Ihre Organisation.
2. Öffnen Sie Schnittstellen → SFTP-Konfiguration (Berechtigung zum Verwalten von Integrationen erforderlich).
3. Passwort eingeben und bestätigen, dann SFTP einrichten klicken.
4. Warten Sie, bis der Zugang bereit ist (bis zu 2 Minuten). Bei Erfolg wird der Status grün und die Verbindungsdaten (Host, Port, Benutzername) angezeigt.

Alternative: Die Anmeldung mit einem privaten Schlüssel wird ebenfalls unterstützt.

Aktionen auf der SFTP-Seite:

Siehe Organisation und Benutzer zu Berechtigungen.

Dateinamen-Regeln

Dateinamen dürfen keine Leerzeichen, Umlaute oder andere Sonderzeichen enthalten.

Erlaubte Zeichen: a-z, A-Z, 0-9, ., _, -

Erlaubte Erweiterungen für Rechnungsdateien: .xml, .pdf

Beispiele — korrekt:

• INV2020_158.xml
• INV2020_212.pdf

Beispiele — falsch:

Verwenden Sie + als Trennzeichen, wenn Routing- oder Konvertierungsanweisungen im Dateinamen stehen sollen (siehe unten).

Vollständige Rechnungsdateien

Versand per Peppol — IDs in der XML

Wenn Peppol-Teilnehmer-IDs von Absender und Empfänger in der Rechnungs-XML enthalten sind:

1
2

<eindeutiger-dateiname>.xml
<eindeutiger-dateiname>.pdf

Versand per Peppol — IDs im Dateinamen

Wenn Peppol-IDs nicht im Dateiinhalt gesetzt werden können, übergeben Sie sie im Dateinamen:

1

<eindeutiger-dateiname>+<Absender-Peppol-ID>+<Empfänger-Peppol-ID>.xml

Jede Peppol-ID besteht aus Electronic Address Scheme (EAS) und ID, getrennt durch einen Punkt.

Vollständige EAS-Liste: PEPPOL EAS Codelist

Beispiele:

• 9930.DE279247134 — Deutsche USt-IdNr.
• 0204.16067088 — Deutsche Leitweg-ID
• 0088.5790000123456 — GLN

Beispiel-Dateiname:

1

invoice-20200821-1+9930.DE279247134+9930.DE123456789.xml

Versand per E-Mail

Für Versand per E-Mail statt Peppol:

1

<eindeutiger-dateiname>+<E-Mail-Empfänger>.xml

Beispiel:

1

invoice-20200821-1+receiver@webware24.de.xml

Konvertierung vor dem Versand

Fügen Sie einen Formatcode hinzu, um Konvertierung vor Validierung und Versand anzufordern:

1

<eindeutiger-dateiname>+<format-code>.xml

Beispiele: 68451+fa3.xml, 68451+xrech_ubl.xml

Dateien mit Anhängen

Für XRechnung- oder Peppol-BIS-Rechnungen mit eingebetteten Anhängen gilt diese Namenskonvention:

Rechnungsdatei:

1
2

<eindeutiger-dateiname>+source.xml
<eindeutiger-dateiname>+source.pdf

Anhangsdateien:

1

<eindeutiger-dateiname>+attachment_<id>.<Erweiterung>

Erlaubte Anhangs-Erweiterungen: jpg, jpeg, png, pdf, xlsx, ods

Bei Peppol-Routing über den Dateinamen +source+ vor den IDs verwenden:

1
2
3

invoice-20200821-1+source+9930.DE279247134+9930.DE123456789.xml
invoice-20200821-1+attachment_1.pdf
invoice-20200821-1+attachment_2.png

Bei E-Mail-Routing:

1
2

invoice-20200821-1+source+max@webware24.de.xml
invoice-20200821-1+attachment_1.pdf

Ordnerstruktur

Mit aktiviertem SFTP-Zugang erhalten Sie folgende Ordnerstruktur. Sie können Dateien in diesen Ordnern anlegen oder löschen, Ordner jedoch nicht löschen.

Sie können mehrere Dateien gleichzeitig hochladen, einschließlich ZIP-Archive oder Ordner. ZIP-Archive werden entpackt; alle Dateien aus Unterordnern (beliebige Tiefe) werden nach upload verschoben und geprüft. Hochgeladene Archive und leere Ordner werden entfernt.

Ausgehende Rechnungen

Upload-Ordner

So senden Sie eine Rechnung per SFTP:

1. Gültige Rechnungsdatei mit korrektem Namen in upload hochladen.
2. xTool registriert die Datei und verarbeitet sie (validieren, optional konvertieren, per Peppol oder E-Mail senden).
3. Die Datei wird nach der Verarbeitung aus upload entfernt. Das Dokument ist im Portal sichtbar.

Beispiel-Dateinamen:

• INV2020_158.xml
• INV2020_212.pdf
• invoice+9930.DE279247134+9930.DE123456789.xml
• invoice+receiver@webware24.de.xml
• 68451+fa3.xml

Upload-Response-Ordner

Pro hochgeladener Datei werden eine oder mehrere Antwort-XML-Dateien in upload_response/<Rechnungsnummer>/ geschrieben — eine pro Verarbeitungsschritt (z. B. Validierung, Konvertierung, Versand).

Antwortdateien heißen:

1

<Format>_<Unix-Zeitstempel>.xml

Beispiele:

• FA3_1713000000.xml (Validation Accepted)
• Inv-20200821-01/FA3_1713000001.xml (KSeF Accepted)

Schlägt Validierung oder Konvertierung fehl, wird eine Antwort mit Status Validation Rejected oder Conversion Rejected und einem <Errors>-Block im selben Unterordner erstellt.

Rejected-Ordner

Dateien, die Grundprüfungen vor der Verarbeitung nicht bestehen (nicht unterstützte Erweiterung, leere Datei, ungültige Zeichen im Namen, unbekannter Formatcode), werden nach rejected verschoben. Pro Datei wird eine Textdatei mit dem Grund erstellt:

1

<Originaldateiname>_<Zeitstempel>_error.txt

Beispiel:

• INV2020_144.xml
• INV2020_144_1592399949_error.txt

Eingehende Rechnungen

Ist Ihre Organisation als Peppol-Empfänger registriert, können eingehende Rechnungen gemäß Eingehende Datei-Zustellung auf der SFTP-Seite in den Ordner download geliefert werden.

Zustellmodus

Zustellinhalt

Sie können wählen, was geliefert wird:

• Originaldatei — empfangene XML (oder Quelldatei)
• PDF-Visualisierung — PDF-Darstellung der Rechnung
• Anhänge — dekodierte Anhänge aus XML oder aus ZUGFeRD-PDF extrahiert

Gelieferte Dateien heißen nach der Dokumentnummer, z. B.:

1
2

68451.xml
68451.pdf

Download-Status-Ordner

Für jede empfangene Rechnung wird eine Statusdatei in download_status erstellt:

1

<Dokumentnummer>_<Zeitstempel>.xml

Beispiel: 68451_1713000000.xml

Siehe Empfang per Peppol.

Antwortdateien

Jede Antwort-XML enthält ein <Status>-Element mit dem Ergebnis eines Verarbeitungsschritts.

Mögliche Statuswerte:

• Validation Accepted / Validation Rejected
• Conversion Accepted / Conversion Rejected
• Upload Rejected
• Peppol Accepted / Peppol Rejected
• Email Accepted
• KSeF Accepted / KSeF Rejected

Bei Fehlern enthält die Antwort einen <Errors>-Block mit einem oder mehreren Fehlerelementen.

Ausgehend — Validierung erfolgreich

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>INV2020_158.xml</File>
  <Time>2020-06-01 09:37:16</Time>
  <Format>PEPPOL BIS 3 Invoice</Format>
  <Sender>9930:987654321</Sender>
  <Receiver>9930:123456789</Receiver>
  <Status>Validation Accepted</Status>
</Response>

Ausgehend — Validierung abgelehnt

Bei Validierungsfehlern werden <Sender> und <Receiver> auf 0088:0000000000000 gesetzt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>INV № 2020/144.xml</File>
  <Time>2020-06-01 09:37:16</Time>
  <Format>Undefined</Format>
  <Sender>0088:0000000000000</Sender>
  <Receiver>0088:0000000000000</Receiver>
  <Status>Validation Rejected</Status>
  <Errors>
    <Error>Incorrect file name.</Error>
  </Errors>
</Response>

Ausgehend — Peppol erfolgreich

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>INV2020_158.xml</File>
  <Time>2020-06-01 09:37:16</Time>
  <Format>PEPPOL BIS 3 Invoice</Format>
  <Sender>9930:987654321</Sender>
  <Receiver>9930:123456789</Receiver>
  <Status>PEPPOL Accepted</Status>
  <Details>
    <MessageTime>2020-06-01T09:35:30Z</MessageTime>
    <MessageUID>b07fba39-496f-49cb-b910-3f52a3658c82@receiver</MessageUID>
    <InvoiceUID>c24b8882-b6f3-4df2-a13f-db3d62d53a36</InvoiceUID>
  </Details>
</Response>

Eingehend — Download-Status

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<?xml version='1.0' encoding='utf-8'?>
<InboundNotification>
  <DocumentNumber>68451</DocumentNumber>
  <Time>2026-04-16 12:34:56</Time>
  <Status>SUCCESS</Status>
  <DeliveredFiles>
    <File>68451.xml</File>
    <File>68451.pdf</File>
  </DeliveredFiles>
</InboundNotification>

KSeF-Konvertierungskette (Beispiel)

Laden Sie eine Peppol-BIS-3-Rechnung mit +fa3 im Dateinamen hoch (z. B. 603275+fa3.xml), validiert xTool, konvertiert nach KSeF FA (3) und übermittelt an KSeF. Antwortdateien für jeden Schritt landen in upload_response/<Rechnungsnummer>/. Bei Erfolg enthält die Antwort die KSeF-Referenznummer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <File>603275.xml</File>
  <Time>2026-03-31 15:14:00</Time>
  <Format>KSeF FA (3)</Format>
  <Sender>9945:PL5252567476</Sender>
  <Receiver>9945:PL9581498695</Receiver>
  <Status>KSeF Accepted</Status>
  <KSeF>5252567476-20260331-6B31C2000000-54</KSeF>
</Response>

Nach erfolgreicher KSeF-Übermittlung wird das konvertierte FA-(3)-Dokument im selben Unterordner gespeichert, z. B. FA3_1743429240.xml.

Siehe Status-Lebenszyklus.

CSV-Import per SFTP

Legen Sie .csv-Dateien im Ordner upload ab. Jede Datei muss eine Rechnung oder Gutschrift im Format xTool CSV v1.0 enthalten. xTool nutzt denselben Importer wie Web und API.

Dateinamen können +-Routing enthalten (gleiches Muster wie bei XML). Siehe Dokumente importieren — SFTP für CSV-spezifische Regeln und CSV-Importformat für die Spaltenspezifikation.

Nächste Schritte

• CSV importieren — Dokumente importieren
• Unterstützte Formate — Formate
• Per Peppol versenden — Per Peppol versenden
• Per E-Mail versenden — Per E-Mail versenden
• Per Peppol empfangen — Empfang per Peppol
• Hilfe — Support

← Dokumente importieren · Per Peppol versenden