Rechnungsbegründende Unterlagen (BG-24) angeben und auslesen

Thema

VB.NET

SDK-Mitglieder

AddAdditionalReferencedDocument() AdditionalReferencedDocumentCount() AdditionalReferencedFileCount() FillZUGFeRD_Structure() GetAdditionalReferencedFile() ReadAdditionalReferencedDocument()

Business Terms

BG-24 Rechnungsbegründende Unterlagen BT-17 Ausschreibungs- oder Losreferenz BT-122 Kennung der rechnungsbegründenden Unterlage BT-123 Beschreibung der rechnungsbegründenden Unterlage BT-124 Bezugsort der rechnungsbgegründenden Unterlage BT-125 Anhangsdokument BT-18 Objektkennung BT-128 Objektkennung auf Ebene der Rechnungsposition

Codebeispiele

VB.NET

Veröffentlicht

7. Oktober 2026

Mit den rechnungsbegründenden Unterlagen (BG-24) verweist eine E-Rechnung auf Dokumente, die die Forderung belegen: Stundennachweise, Aufmaße, Lieferscheine oder eine öffentliche Ausschreibung. Technisch landet all das im Rechnungskopf als ram:AdditionalReferencedDocument – auch die Ausschreibungs- oder Losreferenz (BT-17) und die Objektkennung (BT-18), die nur über den Dokumenttyp unterschieden werden. Dieser Artikel zeigt den schnellen Weg zum Schreiben mit AddAdditionalReferencedDocument und vor allem das Auslesen eingehender Rechnungen.

Felder

Schreiben: Vergabenummer und Belegreferenz

AddAdditionalReferencedDocument legt mit einem Aufruf einen Eintrag aus Kennung und Dokumenttyp an. Achtung: Der zweite Parameter heißt zwar ReferenceTypeCode, das SDK speichert ihn aber als Dokumenttyp (TypeCode). Sind Kennung oder Dokumenttyp leer, wird nichts angelegt.

VB.NET

Dim alo As New Aloaha_ZUGFeRD.XML(Aloaha_ZUGFeRD.iXML.ZUGFeRDProfile.comfort, False, "IHR-LIZENZSCHLUESSEL")
' ... Rechnungskopf, Parteien und Positionen setzen ...

' BT-17: Vergabe-/Losnummer der Ausschreibung
alo.AddAdditionalReferencedDocument("VG-2026-0815", "50")
' BT-122: Kennung eines Belegs, z. B. eines Stundennachweises
alo.AddAdditionalReferencedDocument("STD-2026-09", "916")

Beim Speichern als ZUGFeRD 2.x, Factur-X oder XRechnung schreibt das SDK die Kennung als IssuerAssignedID. Ist sie eine Web-Adresse (http bzw. https), wird sie zusätzlich als URIID (BT-124) ausgegeben. Ist die Rechnung auf BASIC eingestellt, stellt das SDK sie auf EN 16931 (COMFORT) um, denn BG-24 gibt es erst ab diesem Profil.

Brauchen Sie eine Beschreibung (BT-123), einen getrennten Bezugsort (BT-124), das Schema der Objektkennung (BT-18-1) oder einen eingebetteten Anhang (BT-125), verwenden Sie Add_AdditionalReferencedDocument bzw. Add_AdditionalReferencedFile – siehe Vergabenummer und Objektkennung und Unterlagen in die XML einbetten.

Lesen: alle Unterlagen einer Rechnung

AdditionalReferencedDocumentCount liefert die Anzahl der Einträge im Rechnungskopf, ReadAdditionalReferencedDocument füllt die Felder eines Eintrags per Referenz. Der Index beginnt bei 0. Den Inhalt eines eingebetteten Anhangs gibt diese Methode nicht zurück – dafür gibt es GetAdditionalReferencedFile, das ihn als Byte-Array liefert.

ReadAdditionalReferencedDocument füllt die Ausgaben für jeden vorhandenen Index, auch für die häufigen Einträge ohne URL (BT-124); nicht vorhandene Angaben kommen als leere Zeichenkette zurück. In älteren Versionen des SDK blieben die Variablen bei Einträgen ohne URIID unverändert – dort hilft GetAdditionalReferencedFile, das jeden Eintrag liefert.

VB.NET

Dim alo As New Aloaha_ZUGFeRD.XML
If alo.FillZUGFeRD_Structure("C:\Rechnungen\eingang.pdf", "IHR-LIZENZSCHLUESSEL") Then
    For i As Integer = 0 To alo.AdditionalReferencedDocumentCount() - 1
        Dim Kennung As String = "", Ort As String = "", Typ As String = "", Beschreibung As String = ""
        Dim MimeCode As String = "", Dateiname As String = "", Datum As String = "", DatumFormat As String = ""
        Dim Schema As String = "", MimeType As String = ""

        alo.ReadAdditionalReferencedDocument(i, Kennung, Ort, Typ, Beschreibung, MimeCode, Dateiname, Datum, DatumFormat, Schema, MimeType)

        Dim Anhang() As Byte = {}
        If Dateiname <> "" Then
            ' Eingebetteten Anhang (BT-125) als Byte-Array holen
            Dim LineID As String = ""
            Anhang = alo.GetAdditionalReferencedFile(i, Ort, Dateiname, MimeType, Kennung, LineID, Typ, Schema, Datum, Beschreibung)
        End If

        Select Case Typ
            Case "50" : Console.WriteLine("Vergabenummer (BT-17): " & Kennung)
            Case "130" : Console.WriteLine("Objektkennung (BT-18): " & Kennung & " Schema " & Schema)
            Case Else : Console.WriteLine("Unterlage (BT-122): " & Kennung & " – " & Beschreibung & " " & Ort)
        End Select
        If Dateiname <> "" Then Console.WriteLine("  Anhang: " & Dateiname & " (" & MimeType & ")")
    Next
End If

VBA / VB6 (COM) – AdditionalReferencedFileCount liefert dieselbe Anzahl wie AdditionalReferencedDocumentCount. Die Variablen müssen als String deklariert sein und sollten vor jedem Aufruf geleert werden:

Dim i As Long
Dim Kennung As String, Ort As String, Typ As String, Beschreibung As String

For i = 0 To alo.AdditionalReferencedFileCount - 1
    Kennung = "": Ort = "": Typ = "": Beschreibung = ""
    alo.ReadAdditionalReferencedDocument i, Kennung, Ort, Typ, Beschreibung
    Debug.Print i, Typ, Kennung, Beschreibung, Ort
Next i

Hinweise

• Profile: BG-24 mit BT-17, BT-18 und BT-122 bis BT-125 gibt es ab EN 16931 (COMFORT), also auch in EXTENDED und XRechnung.
• MimeCode und MimeType: Beide Ausgaben von ReadAdditionalReferencedDocument enthalten den MIME-Typ des Anhangs (z. B. application/pdf), sofern einer vorhanden ist.
• Im selben Programmlauf angelegt: Lesen Sie einen Eintrag, den Sie gerade erst mit AddAdditionalReferencedDocument angelegt haben (also ohne Speichern und erneutes Einlesen), steht die Kennung im Parameter URIID, nicht in IssuerAssignedID.
• Das Belegdatum (optionale Parameter IssueDateTime und Document_DateFormat) ist kein Feld der EN 16931. Für EN 16931 und XRechnung genügen Kennung und Dokumenttyp.
• Objektkennungen auf Positionsebene (BT-128) sind ein eigenes Feld, siehe Rechnungsbezugsobjekt BT-128.

Business Terms in diesem Artikel: BG-24 BT-17 BT-122 BT-123 BT-124 BT-125 BT-18 BT-128