Zum Inhalt

Dokumente importieren

Diese Anleitung beschreibt, wie Sie Rechnungen und Gutschriften aus einer xTool-CSV-Datei in xTool importieren — über die Weboberfläche, REST-API oder SFTP. Spaltenbeschreibung und Beispiele: CSV-Importformat.

Was Import ist

Import bedeutet: Quelldatei einlesen, parsen und validieren und ein gespeichertes Dokument in xTool anlegen. Der Importer wandelt die Datei in das interne xTool-Modell um (xtool.invoice.1_0 oder xtool.credit_note.1_0, wenn document_type_code einen Gutschriftcode gemäß Abschnitt 6.6 der CSV-Spezifikation hat).

Derzeit wird nur xTool CSV Version 1.0 (Semikolon-getrennt) als Importquelle unterstützt.

Ergebnis ist ein Dokument mit einer id. Danach können Sie es bearbeiten, in ein Zielformat konvertieren (z. B. XRechnung oder Peppol BIS), versenden (Peppol, E-Mail) oder andere Dokumentenoperationen nutzen. Siehe Dokumentenmodell und Status-Lebenszyklus.

Import vs. Erstellen oder Hochladen

Aspekt Erstellen / Hochladen Import (CSV)
Eingabe JSON-Modell (Formular/API) oder XML-Datei xTool-CSV-Datei
Format Arbeitsformat (z. B. XRechnung UBL, Peppol BIS) oder internes Modell CSV ist kein Arbeitsformat — nur Import
Gespeichert als Gewähltes oder erkanntes Format / Modell Internes xTool-Modell nach Konvertierung
CSV bleibt? — Nein — CSV wird nicht als Dokumentinhalt gespeichert
  • Erstellen — Einheitliches Formular ausfüllen oder JSON-Modell per POST senden. Siehe Dokumente erstellen.
  • Hochladen — XML-Rechnung oder -Gutschrift in unterstütztem Format hochladen. Siehe Dokumente erstellen.
  • Import — CSV hochladen; xTool parst sie und legt ein Dokument aus dem internen Modell an. CSV kann nicht als Dokumentformat gewählt, versendet oder über die Format-API als Formatcode validiert werden.

Zur Feldsemantik nach dem Import: Formatmodelle. Zu CSV-Spalten und Dateistruktur: CSV-Importformat.

Web: Import aus CSV

  1. Dokumente → Importieren (Berechtigung zum Erstellen von Dokumenten erforderlich).
  2. xTool-CSV-Datei wählen (.csv, Semikolon-getrennt, Version 1.0).
  3. Absenden. Die Datei wird geparst, validiert und als ausgehendes Dokument gespeichert.
  4. Bei Erfolg Weiterleitung zur Dokumentdetailseite. Bei Validierungsfehlern erscheint ein Validierungsbericht (CSV-Parse- oder Modellfehler).

Richtung

Der Web-Import legt ausgehende Dokumente an. Für andere Richtungen die API nutzen.

Siehe Dokumente-Oberfläche.

API: CSV importieren

POST-Anfrage mit rohem CSV-Body senden.

Endpoint: POST /api/v2/documents/import/csv

Berechtigung: api.v2.documents.import.csv (beim Anlegen des API-Schlüssels vergeben).

Header: x-api-key, Content-Type: text/csv

Query-Parameter:

Parameter Standard Beschreibung
direction outbound Dokumentrichtung (outbound oder inbound).
require_valid true Bei true werden ungültige Dokumente mit Validierungsbericht abgelehnt.

Body: Roher CSV-Dateiinhalt (UTF-8).

Antwort: Details des erstellten Dokuments (inkl. id). Diese id für Versand, Abruf, Liste oder Konvertierung nutzen.

1
2
3
4
curl -X POST "https://xtool.invoice-portal.de/api/v2/documents/import/csv?direction=outbound" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary "@invoice.csv"

Fehlerantworten:

  • 400 — Parse- oder Validierungsfehler (Validierungsbericht im Body bei require_valid=true).
  • 409 — Format nicht erkannt oder nicht unterstützt.

Siehe Setup, API-Schlüssel und Logs und API-Referenz.

SFTP: Automatischer CSV-Import

Legen Sie .csv-Dateien im SFTP-Ordner upload ab. xTool verarbeitet sie mit demselben Importer wie Web und API. Zur SFTP-Einrichtung, Ordnerstruktur und Dateinamen siehe Senden und Empfangen per SFTP.

CSV-Dateien auf SFTP

  • .csv-Dateien in den Upload-Ordner legen. Jede Datei muss eine Rechnung oder Gutschrift im xTool-CSV-Format v1.0 enthalten.
  • Der Importer läuft automatisch: CSV wird geparst, validiert, ins interne Modell konvertiert und ein Dokument angelegt.
  • Verarbeitete Dateien werden aus dem Upload-Ordner entfernt; Status oder Fehler können je nach Konfiguration in einen Antwortordner geschrieben werden.

Optionale Dateinamen-Routing

Dateinamen können Routing-Informationen mit + als Trennzeichen enthalten (gleiches Muster wie für XML auf SFTP):

Muster Beispiel Wirkung
datei.csv invoice.csv Nur Import; Empfänger aus Dokumentmetadaten
datei+empfaenger.csv invoice+buyer@example.com.csv Routing für E-Mail-Versand nach Verarbeitung
datei+absender+empfaenger.csv inv+1234.DE123456789+5678.DE987654321.csv Peppol-Routing (Absender und Empfänger im Dateinamen)

Nach dem Import das Dokument wie jedes andere behandeln: bei Bedarf ins Zielformat konvertieren, dann per Peppol oder E-Mail versenden. Siehe Versand über Peppol und Versand per E-Mail.

Nächste Schritte