CSV-Importformat
Version 1.0
Im Gegensatz zu JSON und XML ist CSV in xTool nur eine Importquelle. Es ist kein Arbeitsformat: Sie können es beim Erstellen eines Dokuments nicht wählen, nicht als Dokumentinhalt speichern, nicht versenden und nicht als Formatcode über die Format-API validieren oder konvertieren. Nach erfolgreichem Import wird das Dokument als internes xTool-Modell (xtool.invoice.1_0 oder xtool.credit_note.1_0) gespeichert.
Diese Seite ist die Referenzspezifikation für das xTool-CSV-Importformat (Semikolon-getrennt, Version 1.0). Wie Sie Rechnungen über die Web-App, API oder SFTP importieren, steht unter Dokumente importieren.
Siehe auch Formatmodelle und Rechnungsmodell verstehen für das interne Modell, auf das CSV abgebildet wird.
1. Änderungsprotokoll
| Version | Datum | Beschreibung |
|---|---|---|
| 1.0 | 2026-08-26 | Erstveröffentlichung des xTool-CSV-Formats. Flache Projektion des kanonischen Rechnungsmodells xtool.invoice.1_0. |
2. Regeln
Codelisten stammen aus der offiziellen PEPPOL BIS Billing 3.0-Dokumentation:
https://docs.peppol.eu/poacc/billing/3.0/
Felder, die in der Spaltennummer mit einem Sternchen (*) markiert sind, sind vom CSV-Parser erforderlich und dürfen nicht leer sein. Zielformate für E-Rechnungen (XRechnung, PEPPOL BIS, ZUGFeRD / Factur-X) können zusätzliche Felder verlangen; fehlende Zielformat-Felder werden nach der Konvertierung gemeldet, nicht beim CSV-Parsen.
Nicht verwendete optionale Felder müssen leer bleiben. Optionale Spalten können auch ganz aus der Kopfzeile eines Blocks weggelassen werden. Optionale Blöcke können vollständig entfallen.
Datei- und Inhaltsregeln
- Die Kodierung muss UTF-8 sein. Eine UTF-8-BOM ist erlaubt und wird entfernt.
- Eine CSV-Datei enthält genau eine Rechnung oder Gutschrift.
- Spaltentrennzeichen ist ein Semikolon (
;). Das Trennzeichen darf nicht innerhalb eines Spaltenwerts vorkommen. Anführungszeichen und Escaping werden nicht unterstützt. - Es gibt kein globales 50-Zeichen-Limit. Feldlängenbeschränkungen folgen EN 16931 / dem Zielformat nach der Konvertierung.
- Zahlen verwenden einen Punkt als Dezimaltrennzeichen und kein Tausendertrennzeichen:
2450.00. Der Parser begrenzt die Anzahl der Nachkommastellen nicht; Genauigkeitsanforderungen folgen dem Zielformat nach der Konvertierung. Beträge verwenden typischerweise 2. - Datumsangaben verwenden
YYYY-MM-DD(ISO 8601), z. B.2024-06-06. - Werte werden von führenden und nachgestellten Leerzeichen bereinigt.
- Ein leerer Wert bedeutet, dass das Feld fehlt.
- Spaltennamen leiten sich aus dem kanonischen Modellpfad ab, wobei Punkte durch Unterstriche ersetzt werden, z. B.
customer.address_line_1→customer_address_line_1. - Der Parser liest Spalten nach Name, nicht nach Position. Die Spaltenreihenfolge innerhalb eines Blocks und die Blockreihenfolge in der Datei sind irrelevant.
- Unbekannte Spaltennamen werden abgelehnt. Spaltennamen unterscheiden Groß- und Kleinschreibung (
Document_Numberist nicht dasselbe wiedocument_number), die Blockerkennung am ersten Spaltennamen der Kopfzeile jedoch nicht. Die Fehlermeldung „Unknown column“ betrifft Spalten innerhalb eines erkannten Blocks; ist die erste Spalte einer Kopfzeile unbekannt, wird die Zeile nicht als Blockkopfzeile behandelt und es wird ein anderer Fehler gemeldet. - Die Anzahl der Werte in einer Datenzeile muss der Anzahl der Spalten in der Kopfzeile dieses Blocks entsprechen.
- Leere Zeilen zwischen Blöcken sind erlaubt und werden ignoriert. Eine leere Zeile innerhalb eines Blocks (zwischen Kopfzeile und Wertzeilen) beendet diesen Block; zwischen Blockkopfzeile und Wertzeilen dürfen keine Leerzeilen stehen.
Erkennung
Die erste nicht-leere Zeile muss die meta-Kopfzeile sein:
Dateien, die nicht mit dem Header meta_version beginnen, werden abgelehnt.
Dokumenttyp
document_type_code ist ein UN/CEFACT UNCL 1001-Code (380, 381, 326, …). 381 und die weiteren in 6.6 aufgeführten Codes erzeugen eine Gutschrift; andere Codes werden als Rechnung importiert.
3. Dateistruktur
Jeder Block besteht aus einer Kopfzeile, gefolgt von einer oder mehreren Wertzeilen.
| # | Block | Kardinalität | Quelle im Modell |
|---|---|---|---|
| 1 | meta |
1 | CSV-Version (nicht Teil des Rechnungsmodells) |
| 2 | document |
1 | document |
| 3 | supplier |
1 | supplier |
| 4 | supplier_ids |
0..N | supplier.ids[] |
| 5 | customer |
1 | customer |
| 6 | delivery |
0..1 | delivery |
| 7 | payee |
0..1 | payee |
| 8 | tax_representative |
0..1 | tax_representative |
| 9 | notes |
0..N | notes[] |
| 10 | additional_documents |
0..N | additional_documents[] |
| 11 | preceding_documents |
0..N | preceding_documents[] |
| 12 | discounts_charges |
0..N | discounts_charges[] |
| 13 | payment_details |
0..N | payment_details[] |
| 14 | taxes |
1..N | taxes[] |
| 15 | totals |
1 | totals |
| 16 | items |
1..N | items[] |
| 17 | items_discounts_charges |
0..N | items[].discounts_charges[] |
| 18 | items_commodity_classifications |
0..N | items[].commodity_classifications[] |
| 19 | items_properties |
0..N | items[].properties[] |
Ein Block wird anhand der ersten Kopfzeilenspalte erkannt, die einer bekannten Spalte dieses Blocks entspricht. Längere Blocknamen haben Vorrang, damit items_discounts_charges nicht mit items verwechselt wird.
Untergeordnete Positionsblöcke (17–19) werden über die Position verknüpft: items_discounts_charges_position (und die Entsprechungen in 18 und 19) muss einem items_position-Wert entsprechen. Ein Verweis auf eine nicht existierende Position ist ein Validierungsfehler.
Die folgenden Modellfelder sind in CSV nicht abgebildet:
| Modellfeld | Grund |
|---|---|
additional_documents[].content |
Binäre Anhänge werden nicht über CSV übertragen |
format |
Vom System nach dem Import zugewiesen |
Steueraufschlüsselung und Dokumentensummen werden unverändert aus der Datei übernommen. Der Importer berechnet Steuern oder Summen nicht aus den Positionen.
4. CSV-Spezifikation
Legende für die Spalte Typ:
| Typ | Bedeutung |
|---|---|
| Alphanum | Text |
| Num | Dezimalzahl (2450.00) |
| Date | YYYY-MM-DD |
| Code | Wert aus einer Codeliste in Abschnitt 6 |
| Sign | - (Nachlass / Rabatt) oder + (Zuschlag / Gebühr) |
EN-16931-Geschäftsbegriffe (BT-xx / BG-xx) werden angegeben, wo eine direkte Zuordnung besteht.
4.1. meta
CSV-Formatversion. Eine Datei mit nicht unterstützter Version wird abgelehnt.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | meta_version |
Alphanum | Version dieser Spezifikation | 1.0 |
Beispiel
4.2. document
Rechnungskopf: Typ, Daten, Währung, Zahlungsbedingungen und Referenzen.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | document_number |
Alphanum | Eindeutige Rechnungsnummer im System des Verkäufers. Kein Identifikationsschema. | inv2024/1 |
BT-1 |
| 2* | document_type_code |
Code | Rechnungstyp. Siehe 6.6. 381 und die dort aufgeführten weiteren Codes erzeugen eine Gutschrift. |
380 |
BT-3 |
| 3* | document_issue_date |
Date | Datum der Rechnungsstellung | 2024-06-06 |
BT-2 |
| 4 | document_due_date |
Date | Fälligkeitsdatum der Zahlung | 2024-07-06 |
BT-9 |
| 5 | document_tax_point_date |
Date | Umsatzsteuer-Leistungsdatum | 2024-06-06 |
BT-7 |
| 6 | document_period_start_date |
Date | Beginn des Abrechnungszeitraums | 2024-06-06 |
BT-73 |
| 7 | document_period_end_date |
Date | Ende des Abrechnungszeitraums | 2024-07-06 |
BT-74 |
| 8 | document_period_code |
Code | Code für das Leistungsdatum (UNTDID 2475), falls verwendet | BT-8 | |
| 9* | document_currency_code |
Code | Rechnungswährung. Siehe 6.3. | EUR |
BT-5 |
| 10 | document_tax_currency_code |
Code | Steuerbuchungswährung, falls abweichend von BT-5 | BT-6 | |
| 11 | document_terms |
Alphanum | Zahlungsbedingungen, einschließlich SKONTO- / VERZUG-Konstrukten. Siehe Anmerkung unten. | 30 days net |
BT-20 |
| 12 | document_accounting_cost |
Alphanum | Buchungsreferenz des Erwerbers | COST-44 |
BT-19 |
| 13 | document_customer_reference |
Alphanum | Käuferreferenz / Leitweg-ID. Dies ist ein Dokument-Feld, kein Kundenfeld. | 12345 |
BT-10 |
| 14 | document_order_reference |
Alphanum | Bestellreferenz des Erwerbers | ref123 |
BT-13 |
| 15 | document_contract_reference |
Alphanum | Vertragsreferenz | ref456 |
BT-12 |
| 16 | document_project_reference |
Alphanum | Projektreferenz | ref789 |
BT-11 |
| 17 | document_sales_order_reference |
Alphanum | Auftragsreferenz des Verkäufers | 123 |
BT-14 |
| 18 | document_award_reference |
Alphanum | Ausschreibungs- oder Losreferenz | 456 |
BT-17 |
| 19 | document_despatch_advice_reference |
Alphanum | Lieferscheinreferenz | DA20240606-001 |
BT-16 |
| 20 | document_receipt_advice_reference |
Alphanum | Wareneingangsreferenz | RA20240607-002 |
BT-15 |
XRechnung — BT-1 Invoice number. Eine eindeutige Kennung der Rechnung, die diese im System des Verkäufers identifiziert. Es ist kein Identification Scheme zu verwenden.
XRechnung — BT-10 Buyer reference / Leitweg-ID. Ein vom Erwerber zugewiesener und für interne Lenkungszwecke benutzter Bezeichner. Im Rahmen des Steuerungsprojekts eRechnung ist mit der Leitweg-ID eine Zuordnungsmöglichkeit entwickelt worden, deren verbindliche Nutzung von Bund und mehreren Ländern vorgegeben wird. Länder und Kommunen, die abweichende Zuordnungsmuster mitteilen, können diese statt der Leitweg-ID verwenden. Für B2B können eigene Käuferreferenzen verwendet werden.
XRechnung — BT-20 Payment terms (SKONTO / VERZUG). Unstrukturierter Text darf kein # enthalten. Skonto- oder Verzugsangaben:
Jeder Eintrag beginnt mit #, Segmente werden durch # getrennt, eine Zeile endet mit #. Schlüsselwörter müssen in Großbuchstaben stehen. Keine zusätzlichen Leerzeichen. Nach einer vollständigen SKONTO- / VERZUG-Angabe muss ein Zeilenumbruch folgen.
Beispiel
4.3. supplier
Verkäufer (Ihr Unternehmen).
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | supplier_name |
Alphanum | Eingetragener Name des Verkäufers | Webware internet solutions GmbH |
BT-27 |
| 2 | supplier_description |
Alphanum | Zusätzliche Verkäuferbeschreibung | IT services |
|
| 3 | supplier_trading_name |
Alphanum | Handelsname, falls abweichend von BT-27 | Webware |
BT-28 |
| 4 | supplier_vat_id |
Alphanum | USt-IdNr. des Verkäufers | DE279247134 |
BT-31 |
| 5 | supplier_tax_id_value |
Alphanum | Steuerregistrierungskennung des Verkäufers (z. B. deutsche Steuernummer) | 262/481/0918 |
BT-32 |
| 6 | supplier_tax_id_scheme |
Code | Schema von BT-32 | FC |
BT-32-1 |
| 7 | supplier_endpoint_id_value |
Alphanum | Elektronische Adresse (Peppol-Teilnehmer-ID-Wert) | 279247134 |
BT-34 |
| 8 | supplier_endpoint_id_scheme |
Code | Schema der elektronischen Adresse. Siehe 6.8. | 9930 |
BT-34-1 |
| 9 | supplier_legal_registration_id_value |
Alphanum | Handelsregisternummer | HRB12345 |
BT-30 |
| 10 | supplier_legal_registration_id_scheme |
Code | Schema von BT-30 | 0209 |
BT-30-1 |
| 11 | supplier_contact_name |
Alphanum | Ansprechpartner oder Abteilung | Max Mustermann |
BT-41 |
| 12 | supplier_contact_phone |
Alphanum | Telefonnummer | +49561111111 |
BT-42 |
| 13 | supplier_contact_email |
Alphanum | E-Mail-Adresse | max@webware24.de |
BT-43 |
| 14 | supplier_address_line_1 |
Alphanum | Straße und Hausnummer, or “Postfach” plus number | Teichstr. 14-16 |
BT-35 |
| 15 | supplier_address_line_2 |
Alphanum | Zusätzliche Adresszeile | Building A |
BT-36 |
| 16 | supplier_address_line_3 |
Alphanum | Dritte Adresszeile | BT-162 | |
| 17 | supplier_city |
Alphanum | Ort | Kassel |
BT-37 |
| 18 | supplier_zip |
Alphanum | Postleitzahl | 34130 |
BT-38 |
| 19 | supplier_sub_country |
Alphanum | Landes-/Regions-/Provinzunterteilung | Hessen |
BT-39 |
| 20 | supplier_country |
Code | Land. Siehe 6.2. | DE |
BT-40 |
XRechnung — BT-27 Seller name. Der vollständige Name, unter dem der Verkäufer im nationalen Register für juristische Personen oder als steuerpflichtige Person eingetragen ist oder anderweitig als Person(en) handelt (Firma).
XRechnung — BT-31 USt-IdNr. des Verkäufers. Die Umsatzsteuer-Identifikationsnummer des Verkäufers. Verfügt der Verkäufer über eine solche, ist sie hier anzugeben, sofern nicht Angaben zum Seller Tax Representative Party (BG-11) gemacht werden.
XRechnung — BT-32 Seller tax registration identifier. Eine örtliche steuerrechtliche Kennung des Verkäufers oder ein Verweis auf seinen eingetragenen Steuerstatus.
Mehrere Verkäuferkennungen (BT-29) werden im separaten Block [supplier_ids](#44-supplier_ids) angegeben. Bankverbindungsdaten stehen in [payment_details](#413-payment_details), nicht beim Verkäufer.
Beispiel
4.4. supplier_ids
Zusätzliche Verkäuferkennungen (BG-4 / BT-29). Wiederholbar. Block weglassen, wenn nicht verwendet.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | supplier_ids_value |
Alphanum | Kennungswert | 4012345000001 |
BT-29 |
| 2 | supplier_ids_scheme |
Code | Identifikationsschema (ISO 6523 ICD) | 0088 |
BT-29-1 |
Dies ist beim Erwerber bewusst nicht abgebildet: Der Erwerber hat eine einzelne Kennung (customer_id_*, BT-46).
Beispiel
4.5. customer
Erwerber.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | customer_id_value |
Alphanum | Erwerberkennung | 991-12345-67 |
BT-46 |
| 2 | customer_id_scheme |
Code | Schema von BT-46 | 0204 |
BT-46-1 |
| 3* | customer_name |
Alphanum | Name des Erwerbers | Webware internet solutions GmbH |
BT-44 |
| 4 | customer_description |
Alphanum | Zusätzliche Erwerberbeschreibung | Buyer |
|
| 5 | customer_trading_name |
Alphanum | Handelsname des Erwerbers | Webware Buyer |
BT-45 |
| 6 | customer_vat_id |
Alphanum | USt-IdNr. des Erwerbers | DE279247134 |
BT-48 |
| 7 | customer_tax_id_value |
Alphanum | Steuerregistrierungskennung des Erwerbers | 262/481/0918 |
|
| 8 | customer_tax_id_scheme |
Code | Schema der Steuerkennung | FC |
|
| 9 | customer_endpoint_id_value |
Alphanum | Elektronische Adresse | 279247134 |
BT-49 |
| 10 | customer_endpoint_id_scheme |
Code | Schema der elektronischen Adresse. Siehe 6.8. | 9930 |
BT-49-1 |
| 11 | customer_legal_registration_id_value |
Alphanum | Handelsregisternummer | HRB54321 |
BT-47 |
| 12 | customer_legal_registration_id_scheme |
Code | Schema von BT-47 | 0209 |
BT-47-1 |
| 13 | customer_contact_name |
Alphanum | Ansprechpartner oder Abteilung | Contact Person |
BT-56 |
| 14 | customer_contact_phone |
Alphanum | Telefonnummer | +123456 |
BT-57 |
| 15 | customer_contact_email |
Alphanum | E-Mail-Adresse | cp@webware24.de |
BT-58 |
| 16 | customer_address_line_1 |
Alphanum | Straße und Hausnummer | Teichstr. 14-16 |
BT-50 |
| 17 | customer_address_line_2 |
Alphanum | Zusätzliche Adresszeile | Building A |
BT-51 |
| 18 | customer_address_line_3 |
Alphanum | Dritte Adresszeile | BT-163 | |
| 19 | customer_city |
Alphanum | Ort | Kassel |
BT-52 |
| 20 | customer_zip |
Alphanum | Postleitzahl | 34130 |
BT-53 |
| 21 | customer_sub_country |
Alphanum | Landesunterteilung | Hessen |
BT-54 |
| 22 | customer_country |
Code | Land. Siehe 6.2. | DE |
BT-55 |
XRechnung — BT-44 Name des Erwerbers. Der vollständige Name des Erwerbers.
Die Leitweg-ID gehört in document_customer_reference (BT-10), nicht hierher.
Beispiel
4.6. delivery
Optionaler Lieferempfänger und tatsächliches Lieferdatum (BG-13). Von einigen Steuerkategorien erforderlich (z. B. innergemeinschaftliche Lieferung, Code K).
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | delivery_id_value |
Alphanum | Kennung des Lieferorts | 4031241000006 |
BT-71 |
| 2 | delivery_id_scheme |
Code | Schema von BT-71 | 0088 |
BT-71-1 |
| 3 | delivery_name |
Alphanum | Name des Empfängers der Waren / Dienstleistungen, falls abweichend vom Erwerber | Webware Warehouse |
BT-70 |
| 4 | delivery_date |
Date | Tatsächliches Liefer- / Leistungsdatum | 2024-06-15 |
BT-72 |
| 5 | delivery_address_line_1 |
Alphanum | Straße | Teichstr. 14-16 |
BT-75 |
| 6 | delivery_address_line_2 |
Alphanum | Zusätzliche Adresszeile | Building B |
BT-76 |
| 7 | delivery_address_line_3 |
Alphanum | Dritte Adresszeile | BT-165 | |
| 8 | delivery_city |
Alphanum | Ort | Kassel |
BT-77 |
| 9 | delivery_zip |
Alphanum | Postleitzahl | 34130 |
BT-78 |
| 10 | delivery_sub_country |
Alphanum | Landesunterteilung | Hessen |
BT-79 |
| 11 | delivery_country |
Code | Land | DE |
BT-80 |
Wenn eine Lieferadresse angegeben ist, sind Postleitzahl und Land im Zielformat in der Regel Pflicht.
Beispiel
4.7. payee
Optionaler Zahlungsempfänger, wenn die Zahlung nicht an den Verkäufer geht (BG-10).
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | payee_id_value |
Alphanum | Kennung des Zahlungsempfängers | 4012345000001 |
BT-60 |
| 2 | payee_id_scheme |
Code | Schema von BT-60 | 0088 |
BT-60-1 |
| 3 | payee_name |
Alphanum | Name des Zahlungsempfängers. In EN 16931 Pflicht, wenn BG-10 vorhanden ist. | Webware internet solutions GmbH |
BT-59 |
| 4 | payee_legal_registration_id_value |
Alphanum | Handelsregisternummer | HRB12345 |
BT-61 |
| 5 | payee_legal_registration_id_scheme |
Code | Schema von BT-61 | 0209 |
BT-61-1 |
Beispiel
4.8. tax_representative
Optionaler Steuervertreter des Verkäufers (BG-11).
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | tax_representative_name |
Alphanum | Name des Steuervertreters | Tax Advisory Services GmbH |
BT-62 |
| 2 | tax_representative_vat_id |
Alphanum | USt-IdNr. | DE111111111 |
BT-63 |
| 3 | tax_representative_tax_id_value |
Alphanum | Steuerregistrierungskennung | 111/111/11111 |
|
| 4 | tax_representative_tax_id_scheme |
Code | Schema der Steuerkennung | FC |
|
| 5 | tax_representative_address_line_1 |
Alphanum | Straße | Musterstr. 1 |
BT-64 |
| 6 | tax_representative_address_line_2 |
Alphanum | Zusätzliche Adresszeile | BT-65 | |
| 7 | tax_representative_address_line_3 |
Alphanum | Dritte Adresszeile | BT-164 | |
| 8 | tax_representative_city |
Alphanum | Ort | Berlin |
BT-66 |
| 9 | tax_representative_zip |
Alphanum | Postleitzahl | 10115 |
BT-67 |
| 10 | tax_representative_sub_country |
Alphanum | Landesunterteilung | Berlin |
BT-68 |
| 11 | tax_representative_country |
Code | Land | DE |
BT-69 |
Wenn dieser Block vorhanden ist, verlangt EN 16931 in der Regel Name, USt-IdNr. und Land.
Beispiel
4.9. notes
Unstrukturierte Rechnungshinweise (BG-1). Wiederholbar.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | notes_text |
Alphanum | Hinweistext. Kann den Aufbewahrungshinweis gemäß § 14 Abs. 4 Nr. 9 UStG enthalten. | Payment within 30 days. |
BT-22 |
| 2 | notes_subject_code |
Code | Betreffcode des Hinweises (UNTDID 4451) | PMT |
BT-21 |
Beispiel
4.10. additional_documents
Belegende Dokumente und Objektreferenzen (BG-24 / BT-18). Wiederholbar.
Binärer Inhalt (content) wird nicht akzeptiert. Stattdessen eine externe URI angeben.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | additional_documents_id_value |
Alphanum | Dokument- oder Objektkennung | ATT-1 |
BT-122 / BT-18 |
| 2 | additional_documents_id_scheme |
Code | Identifikationsschema | ||
| 3 | additional_documents_type_code |
Code | Dokumenttyp (UNTDID 1001), z. B. 130 Rechnung |
130 |
|
| 4 | additional_documents_uri |
Alphanum | Externer Speicherort | https://example.com/hours.csv |
BT-124 |
| 5 | additional_documents_description |
Alphanum | Beschreibung | Time list |
BT-123 |
| 6 | additional_documents_filename |
Alphanum | Dateiname, falls zutreffend | Hours-spent.csv |
BT-125 |
| 7 | additional_documents_mime_code |
Alphanum | MIME-Typ | text/csv |
Objektkennung (BT-18, z. B. Zählernummer, Telefonnummer, Kennzeichen) wird als Zeile in diesem Block ausgedrückt.
Beispiel
4.11. preceding_documents
Referenz auf vorherige Rechnung (BG-3). Erforderlich für Gutschriften und Rechnungskorrekturen. Wiederholbar.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | preceding_documents_number |
Alphanum | Nummer der vorherigen Rechnung | INV20240115-001 |
BT-25 |
| 2 | preceding_documents_issue_date |
Date | Ausstellungsdatum der vorherigen Rechnung | 2024-01-15 |
BT-26 |
Beispiel
4.12. discounts_charges
Nachlässe und Zuschläge auf Dokumentenebene (BG-20 / BG-21). Wiederholbar.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | discounts_charges_sign |
Sign | - = Nachlass (BG-20), + = Zuschlag (BG-21) |
- |
|
| 2 | discounts_charges_base_amount |
Num | Basisbetrag | 6000.00 |
BT-93 / BT-100 |
| 3 | discounts_charges_percent |
Num | Prozentsatz | 1.67 |
BT-94 / BT-101 |
| 4 | discounts_charges_amount |
Num | Betrag ohne USt | 100.00 |
BT-92 / BT-99 |
| 5 | discounts_charges_tax_code |
Code | USt-Kategorie. Siehe 6.5. | S |
BT-95 / BT-102 |
| 6 | discounts_charges_tax_scheme |
Alphanum | Steuerschema, typischerweise VAT |
VAT |
|
| 7 | discounts_charges_tax_percent |
Num | USt-Satz | 19.00 |
BT-96 / BT-103 |
| 8 | discounts_charges_reason |
Alphanum | Grund als Text | Early payment |
BT-97 / BT-104 |
| 9 | discounts_charges_reason_code |
Code | Grundcode (UNTDID 5189 / 7161) | 95 |
BT-98 / BT-105 |
Beispiel
4.13. payment_details
Zahlungsmittel und Kontodaten (BG-16). Wiederholbar — mehrere Konten können angegeben werden.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | payment_details_method_code |
Code | Zahlungsmittelcode. Siehe 6.1. | 58 |
BT-81 |
| 2 | payment_details_method_name |
Alphanum | Zahlungsmittel als Text | SEPA credit transfer |
BT-82 |
| 3 | payment_details_iban |
Alphanum | IBAN (oder Kontokennung außerhalb SEPA) | DE50520501511004485469 |
BT-84 |
| 4 | payment_details_bic |
Alphanum | BIC. Erforderlich für Überweisungen außerhalb SEPA (30) und für einige SEPA-Länder (z. B. CH, SM, MC). Nicht erforderlich für SEPA-SCT (58). |
WELADED1SIE |
BT-86 |
| 5 | payment_details_account_name |
Alphanum | Kontobezeichnung | Webware GmbH Payment Account |
BT-85 |
| 6 | payment_details_remittance_information |
Alphanum | Verwendungszweck (Zahlungsreferenz) | inv2024/1 |
BT-83 |
| 7 | payment_details_card_number |
Alphanum | Primäre Kontonummer der Zahlungskarte (maskiert) | BT-87 | |
| 8 | payment_details_card_holder_name |
Alphanum | Name des Karteninhabers | BT-88 | |
| 9 | payment_details_card_network |
Alphanum | Kartennetzwerk | ||
| 10 | payment_details_direct_debit_mandate_id |
Alphanum | Referenz des Lastschriftmandats | BT-89 | |
| 11 | payment_details_direct_debit_payer_account |
Alphanum | Kennung des belasteten Kontos | BT-91 |
XRechnung — BT-84 / BT-86. Für SEPA-Überweisungen (Code 58) genügt die IBAN. Für Überweisungen außerhalb des SEPA-Raums (Code 30) ist der BIC erforderlich. Ausnahmen innerhalb SEPA, in denen der BIC dennoch Pflicht ist: San Marino, Monaco, Schweiz, Saint-Pierre und Miquelon.
Beispiel
4.14. taxes
USt-Aufschlüsselung (BG-23). Mindestens eine Zeile ist erforderlich. Werte werden nicht aus Rechnungspositionen berechnet.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1 | taxes_taxable_amount |
Num | Steuerpflichtiger Betrag für diese Kategorie | 6000.00 |
BT-116 |
| 2 | taxes_currency_code |
Code | Währung des Steuerbetrags, falls erforderlich | EUR |
|
| 3 | taxes_amount |
Num | USt-Betrag für diese Kategorie | 1140.00 |
BT-117 |
| 4 | taxes_percent |
Num | USt-Satz. 0 verwenden, wenn die Kategorie außerhalb des USt-Anwendungsbereichs liegt. |
19.00 |
BT-119 |
| 5 | taxes_code |
Code | USt-Kategorie. Siehe 6.5. | S |
BT-118 |
| 6 | taxes_scheme |
Alphanum | Steuerschema, typischerweise VAT |
VAT |
|
| 7 | taxes_exemption_reason |
Alphanum | Befreiungsgrund als Text. Für Kategorie AE: „Umkehrung der Steuerschuldnerschaft“ (oder das Äquivalent in der Rechnungssprache). |
BT-120 | |
| 8 | taxes_exemption_reason_code |
Code | VATEX-Code | VATEX-EU-IC |
BT-121 |
taxes_amount sollte für die Kategorie taxes_taxable_amount × taxes_percent / 100 entsprechen (vorbehaltlich der Rundungsregeln des Zielformats).
Beispiel
4.15. totals
Dokumentensummen (BG-22). Alle Beträge stammen aus der Datei. Der Importer prüft die Konsistenz (Abschnitt 5) und berechnet nicht neu.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | totals_item_subtotal |
Num | Summe der Nettobeträge der Rechnungspositionen | 6000.00 |
BT-106 |
| 2* | totals_subtotal |
Num | Rechnungssumme ohne USt | 6000.00 |
BT-109 |
| 3* | totals_total |
Num | Rechnungssumme mit USt | 7140.00 |
BT-112 |
| 4 | totals_discount |
Num | Summe der Nachlässe auf Dokumentenebene | 100.00 |
BT-107 |
| 5 | totals_charge |
Num | Summe der Zuschläge auf Dokumentenebene | 100.00 |
BT-108 |
| 6 | totals_paid |
Num | Bereits erhaltener gezahlter Betrag | BT-113 | |
| 7 | totals_round |
Num | Rundungsbetrag | BT-114 | |
| 8* | totals_payable |
Num | Fälliger Zahlungsbetrag | 7140.00 |
BT-115 |
| 9 | totals_tax_total |
Num | Gesamt-USt-Betrag der Rechnung in Rechnungswährung | 1140.00 |
BT-110 |
| 10 | totals_tax_total_alt_currency |
Num | Gesamt-USt-Betrag der Rechnung in Buchungswährung | BT-111 |
XRechnung — BT-115 Fälliger Zahlungsbetrag. Der ausstehende Betrag: BT-112 abzüglich BT-113. Bei einer vollständig beglichenen Rechnung ist dieser Betrag gleich null. Der Betrag ist negativ, falls BT-113 größer als BT-112 ist.
Beispiel
4.16. items
Rechnungspositionen (BG-25). Mindestens eine Zeile ist erforderlich.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | items_position |
Alphanum | Eindeutige Positionskennung. Dient als Schlüssel für untergeordnete Blöcke. Jede Position muss in der Datei eindeutig sein; der Parser erzwingt Eindeutigkeit nicht — bei doppelten Positionen werden Zeilen untergeordneter Blöcke mit allen Zeilen dieser Position verknüpft. | 1 |
BT-126 |
| 2 | items_name |
Alphanum | Artikelname. In EN 16931 erforderlich. | Onboarding |
BT-153 |
| 3 | items_description |
Alphanum | Artikelbeschreibung | Kickoff package |
BT-154 |
| 4 | items_note |
Alphanum | Hinweis zur Rechnungsposition | Includes setup |
BT-127 |
| 5* | items_quantity |
Num | In Rechnung gestellte Menge | 10.00 |
BT-129 |
| 6* | items_unit_code |
Code | Maßeinheit für BT-129. Siehe 6.4. | C62 |
BT-130 |
| 7 | items_price |
Num | Nettopreis des Artikels (nach Artikelpreisrabatt) | 200.00 |
BT-146 |
| 8 | items_price_quantity |
Num | Basismenge für den Artikelpreis | 1 |
BT-149 |
| 9 | items_price_unit_code |
Code | Maßeinheit der Preisbasismenge | C62 |
BT-150 |
| 10 | items_price_discount_charge_sign |
Sign | Vorzeichen des Artikelpreis-Nachlasses/-Zuschlags | - |
|
| 11 | items_price_discount_charge_base_amount |
Num | Bruttopreis des Artikels (vor Preisrabatt) | 220.00 |
BT-148 |
| 12 | items_price_discount_charge_amount |
Num | Artikelpreisrabatt | 20.00 |
BT-147 |
| 13* | items_subtotal |
Num | Nettobetrag der Rechnungsposition | 2000.00 |
BT-131 |
| 14 | items_tax_percent |
Num | USt-Satz des in Rechnung gestellten Artikels | 19.00 |
BT-152 |
| 15* | items_tax_code |
Code | USt-Kategorie des in Rechnung gestellten Artikels. Siehe 6.5. | S |
BT-151 |
| 16* | items_tax_scheme |
Alphanum | Steuerschema, typischerweise VAT |
VAT |
|
| 17 | items_supplier_item_id |
Alphanum | Artikelkennung des Verkäufers | onb.2024.6 |
BT-155 |
| 18 | items_customer_item_id |
Alphanum | Artikelkennung des Erwerbers | BUY-ONB |
BT-156 |
| 19 | items_standard_item_id_value |
Alphanum | Standard-Artikelkennung (z. B. GTIN) | 12345678 |
BT-157 |
| 20 | items_standard_item_id_scheme |
Code | Schema von BT-157 | 0160 |
BT-157-1 |
| 21 | items_order_position_reference |
Alphanum | Referenzierte Bestellposition | 1 |
BT-132 |
| 22 | items_document_reference_id_value |
Alphanum | Objektkennung der Rechnungsposition | PO-2024-1 |
BT-128 |
| 23 | items_document_reference_id_scheme |
Code | Schema von BT-128 | ||
| 24 | items_document_reference_type_code |
Code | Dokumenttypcode | 130 |
|
| 25 | items_accounting_cost |
Alphanum | Buchungsreferenz des Erwerbers für die Rechnungsposition | 1287:65464 |
BT-133 |
| 26 | items_period_start_date |
Date | Beginn des Abrechnungszeitraums der Position | 2024-06-06 |
BT-134 |
| 27 | items_period_end_date |
Date | Ende des Abrechnungszeitraums der Position | 2024-06-30 |
BT-135 |
| 28 | items_origin_country |
Code | Ursprungsland des Artikels | DE |
BT-159 |
XRechnung — BT-126 Invoice line identifier. Eindeutige Bezeichnung für die betreffende Rechnungsposition.
XRechnung — BT-146 Item net price. Der Preis eines Postens ohne Umsatzsteuer, nach Abzug des für diese Rechnungsposition geltenden Rabatts. BT-146 muss gleich BT-148 abzüglich BT-147 sein.
XRechnung — BT-131 Nettobetrag der Rechnungsposition. Der Gesamtbetrag der Rechnungsposition ohne Umsatzsteuer, einschließlich aller für die Position geltenden Nachlässe und Abgaben.
USt-Betrag und Bruttobetrag auf Positionsebene (item_tax_total / item_total) sind in diesem Format nicht enthalten. USt wird im Block taxes angegeben. Mehrere Nachlässe/Zuschläge pro Position gehören in [items_discounts_charges](#417-items_discounts_charges).
Beispiel
4.17. items_discounts_charges
Nachlässe und Zuschläge auf Positionsebene (BG-27 / BG-28). Wiederholbar. Mehrere Zeilen können dieselbe items_position referenzieren.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | items_discounts_charges_position |
Alphanum | Muss items_position entsprechen |
1 |
|
| 2* | items_discounts_charges_sign |
Sign | - = Nachlass (BG-27), + = Zuschlag (BG-28) |
- |
|
| 3 | items_discounts_charges_base_amount |
Num | Basisbetrag | 2000.00 |
BT-137 / BT-142 |
| 4 | items_discounts_charges_percent |
Num | Prozentsatz | 2.50 |
BT-138 / BT-143 |
| 5* | items_discounts_charges_amount |
Num | Betrag ohne USt | 50.00 |
BT-136 / BT-141 |
| 6 | items_discounts_charges_reason |
Alphanum | Grund als Text | Volume discount |
BT-139 / BT-144 |
| 7 | items_discounts_charges_reason_code |
Code | Grundcode | 95 |
BT-140 / BT-145 |
Beispiel
4.18. items_commodity_classifications
Artikelklassifizierungskennungen (BT-158). Wiederholbar.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | items_commodity_classifications_position |
Alphanum | Muss items_position entsprechen |
1 |
|
| 2 | items_commodity_classifications_code |
Alphanum | Klassifizierungscode | 12344321 |
BT-158 |
| 3 | items_commodity_classifications_scheme |
Code | Identifikationsschema | STI |
BT-158-1 |
| 4 | items_commodity_classifications_scheme_version |
Alphanum | Schemaversion | 0.1 |
BT-158-2 |
Beispiel
4.19. items_properties
Artikelattribute (BG-32). Wiederholbar.
| # | Spalte | Typ | Beschreibung | Beispiel | EN 16931 |
|---|---|---|---|---|---|
| 1* | items_properties_position |
Alphanum | Muss items_position entsprechen |
1 |
|
| 2 | items_properties_name |
Alphanum | Attributname | Contract |
BT-160 |
| 3 | items_properties_value |
Alphanum | Attributwert | ONB-2024 |
BT-161 |
Beispiel
5. Konsistenz der Summen
Der Importer prüft die in der Datei angegebenen Beträge. Kein Wert wird ersetzt oder neu berechnet. Abweichungen werden als Validierungsfehler mit beiden Beträgen gemeldet.
Geprüfte Identitäten:
| Prüfung | Formel |
|---|---|
| Positionsnetto vs. Positionssumme | Σ items_subtotal = totals_item_subtotal |
| USt-Aufschlüsselung vs. Steuersumme | Σ taxes_amount = totals_tax_total (leere Steuersumme wird als 0 behandelt) |
| Netto + USt vs. Brutto | totals_subtotal + totals_tax_total = totals_total |
| Brutto − Vorauszahlung vs. fällig | totals_total − totals_paid = totals_payable (leerer gezahlter Betrag wird als 0 behandelt) |
totals_discount und totals_charge werden wie angegeben gespeichert; sie werden derzeit nicht gegen discounts_charges gegengeprüft.
6. Codelisten
6.1. Payment means code (UNCL4461)
Häufige Codes:
| Code | Name |
|---|---|
| 1 | Instrument nicht definiert |
| 10 | Bar |
| 30 | Überweisung |
| 31 | Lastschrift (Überweisung) |
| 42 | Zahlung auf Bankkonto |
| 48 | Bankkarte |
| 49 | Lastschrift |
| 58 | SEPA-Überweisung |
| 59 | SEPA-Lastschrift |
Vollständige Liste: https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4461/
6.2. ISO 3166-1 Alpha-2 country codes
Zweistellige Ländercodes. Deutschland ist DE.
Vollständige Liste: https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO3166/
6.3. ISO 4217 currency codes
Rechnungen in Euro verwenden EUR.
Vollständige Liste: https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO4217/
6.4. Unit codes
UNECE-Empfehlung 20 (und Rec. 21 für einige Verpackungseinheiten). Häufige Werte:
| Code | Name |
|---|---|
| C62 | Eins (Einheit) |
| H87 | Stück |
| DAY | Tag |
| HUR | Stunde |
| MON | Monat |
| KGM | Kilogramm |
| LTR | Liter |
| MTR | Meter |
Vollständige Listen:
- https://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec20/
- https://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec21/
6.5. Tax category codes
Teilmenge von UNCL 5305, verwendet in EN 16931:
| Code | Name | Beschreibung |
|---|---|---|
| S | Normalsatz | Standard USt-Satz |
| Z | Nullsatzware | Waren zum Nullsatz |
| E | Steuerbefreit | Steuern sind nicht anwendbar |
| AE | USt-Umkehr der Steuerschuldnerschaft | Normaler USt-Satz wird vom Rechnungsempfänger geschuldet |
| G | Freie Exportware, USt nicht berechnet | Freier Export, Steuern nicht berechnet |
| O | Leistungen außerhalb des Steueranwendungsbereichs | Steuern nicht anwendbar auf die Leistungen |
| K | USt-befreit für innergemeinschaftliche Lieferung im EWR | Innergemeinschaftliche Lieferung im EWR |
| L | Allgemeine indirekte Steuer der Kanarischen Inseln | IGIC |
| M | Steuer für Produktion, Dienstleistungen und Import in Ceuta und Melilla | IPSI |
Vollständige Liste: https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5305/
Befreiungsgrundcodes (VATEX): https://docs.peppol.eu/poacc/billing/3.0/codelist/vatex/
6.6. Invoice types
UNCL-1001-Codes, die direkt in document_type_code verwendet werden:
| Code | Name | German name |
|---|---|---|
| 380 | Commercial invoice | Rechnung |
| 381 | Credit note | Gutschrift |
| 326 | Partial invoice | Teilrechnung |
| 384 | Corrected invoice | Rechnungskorrektur |
| 389 | Self-billed invoice | Self-Billing |
| 875 | Partial construction invoice | Abschlagsrechnung |
| 876 | Partial final construction invoice | Teilschlussrechnung |
| 877 | Final construction invoice | Schlussrechnung |
381 ist der häufigste Gutschriftcode. Folgende UNCL-1001-Codes werden ebenfalls als xTool-Gutschrift importiert (EN 16931 BR-CL-01): 81, 83, 261, 262, 296, 308, 381, 396, 420, 458, 532. Jeder andere Code, einschließlich der oben aufgeführten Rechnungstypen, wird als Rechnung importiert.
6.7. Identifier schemes (ISO 6523 ICD)
Verwendet in *_id_scheme- / *_ids_scheme-Spalten (nicht EAS). Häufige Werte:
| Code | Beschreibung |
|---|---|
| 0088 | EAN-Standortcode (GLN) |
| 0060 | DUNS-Nummer |
| 0160 | GTIN |
| 0209 | GS1-Unternehmenspräfix / LEI-bezogene Handelsregistrierung (kontextabhängig) |
| FC | Steuernummer (oft für BT-32 verwendet) |
ICD-Liste: https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/
6.8. Electronic Address Scheme (EAS)
Verwendet in supplier_endpoint_id_scheme und customer_endpoint_id_scheme.
| Code | Beschreibung |
|---|---|
| 0204 | Leitweg-ID |
| 9930 | Deutsche USt-IdNr. |
| 9925 | Belgische USt-IdNr. |
| 9934 | Kroatische USt-IdNr. |
| 9938 | Luxemburgische USt-IdNr. |
| 0088 | EAN-Standortcode |
Peppol-Teilnehmer-IDs haben die Form <EAS>:<value>, z. B. 9930:DE279247134 oder 0204:999-123456-555. In CSV sind Schema und Wert getrennte Spalten.
Vollständige Liste: https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/
7. Vollständige Beispiele
7.1. Minimale Rechnung
Nur erforderliche Blöcke: meta, document, supplier, customer, taxes, totals, items.
7.2. Peppol-orientierte Rechnung
Endpoint-IDs bei beiden Parteien plus SEPA-Zahlungsdetails. Dieselben erforderlichen Blöcke wie in 7.1, mit payment_details ergänzt.
Bei Fragen zum CSV-Import oder dieser Spezifikation siehe Support.