XRechnungen einlesen

Close Up Photo of Plugged Cables

Das Einlesen von XRechnungen kann sich als knifflig herausstellen. Wir zeigen wie Sie mit der Nutzung der finaX API den XRechnung-Standard nachhaltig einhalten können.

Gesetzliche Grundlage zur XRechnung

In früheren Blogartikeln haben wir bereits über die gesetzliche Grundlagen zu XRechnung detailliert berichtet. Hier eine kurze Übersicht zu den gesetzlichen Regelungen ab 2025:

XRechnung Deadlines Übersicht
XRechnung gesetzliche Fristen

Das Einlesen von XRechnung-Dateien wird also eine verpflichtende Aktivität in jedem Unternehmen. Dies stellt viele Betriebe vor Herausforderungen, denn die unterschiedlichen Formate, Syntaxen und Regeln können schnell überfordern.

Warum finaX API für’s Einlesen von XRechungen?

Wir werden oftmals gefragt, warum es die finaX API eigentlich benötigt. Ein bisschen XML kann doch jeder verarbeiten, oder?

Genau so dachten wir auch am Anfang von finaX – XRechnung – das kann doch nicht so schwer sein! Es stellte sich heraus – das ist es allerdings. Doch warum?

  1. Der Standard XRechnung wird kontinuierlich weiterentwickelt. Das bedeutet regelmäßiges Aktualisieren und Testen der Software zum Einlesen.
  2. Mit 2 gültigen Syntaxen (UBL und CII) verdoppelt sich jeglicher Pflegeaufwand.
  3. Auf die Syntaxen sind die EN16931 und XRechnung Regelwerke anzuwenden. Dies sind spezielle Validierungsregeln, welche dazu dienen festzustellen ob ein Dokument konform ist. Dies umfasst über 230 Regeln zu Validierung eines Dokumentes.
  4. Weiterhin referenziert der Standard XRechnung multiple Code-Listen (z.B. UNTDID 4461 Payment means code) welche regelmäßig aktualisiert werden sollten.
  5. Bestimmte Industrien (z.B. das Baugewerbe) verwenden eine Erweiterung (XRechnung-Extension) als Format. Dieses kommt mit eignen Feldern, Werten und Regeln.

finaX macht dies zum eigenen Geschäftsmodell und übernimmt all diese Arbeiten. Wir stellen unseren Kunden eine aktuelle, sichere und hochqualitative API zur Verarbeitung von XRechnungs-Daten zur Verfügung.

Einlesen von XRechnungen via finaX API

Zum Testen stellen wir einen kostenlosen 14 Tage gültigen Testschlüssel zur Verfügung. Unsere offene Dokumentation erklärt alle Endpunkte im Detail. Nehmen wir folgendes Rechnungsbeispiel:

<ubl:Invoice xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
    <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</cbc:CustomizationID>
    <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
    <cbc:ID>AB-13352</cbc:ID>
    <cbc:IssueDate>2024-08-24</cbc:IssueDate>
    <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
    <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
    <cbc:BuyerReference>KV-55126</cbc:BuyerReference>
    <cac:AccountingSupplierParty>
        <cac:Party>
            <cbc:EndpointID schemeID="9930">DE123456789</cbc:EndpointID>
            <cac:PartyIdentification>
                <cbc:ID schemeID="0094">Verkäufer GmbH</cbc:ID>
            </cac:PartyIdentification>
            <cac:PostalAddress>
                <cbc:CityName>Berlin</cbc:CityName>
                <cbc:PostalZone>12345</cbc:PostalZone>
                <cac:Country>
                    <cbc:IdentificationCode>DE</cbc:IdentificationCode>
                </cac:Country>
            </cac:PostalAddress>
            <cac:PartyTaxScheme>
                <cbc:CompanyID>DE-123213123</cbc:CompanyID>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:PartyTaxScheme>
            <cac:PartyLegalEntity>
                <cbc:RegistrationName>Verkäufer - schnell GmbH</cbc:RegistrationName>
            </cac:PartyLegalEntity>
            <cac:Contact>
                <cbc:Name>Max Mustermann</cbc:Name>
                <cbc:Telephone>876 654 321</cbc:Telephone>
                <cbc:ElectronicMail>max.m@mustermail.de</cbc:ElectronicMail>
            </cac:Contact>
        </cac:Party>
    </cac:AccountingSupplierParty>
    <cac:AccountingCustomerParty>
        <cac:Party>
            <cbc:EndpointID schemeID="9930">DE987654321</cbc:EndpointID>
            <cac:PostalAddress>
                <cbc:CityName>Potsdam</cbc:CityName>
                <cbc:PostalZone>14473</cbc:PostalZone>
                <cac:Country>
                    <cbc:IdentificationCode>DE</cbc:IdentificationCode>
                </cac:Country>
            </cac:PostalAddress>
            <cac:PartyLegalEntity>
                <cbc:RegistrationName>Käufer UG</cbc:RegistrationName>
            </cac:PartyLegalEntity>
        </cac:Party>
    </cac:AccountingCustomerParty>
    <cac:PaymentMeans>
        <cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>
        <cac:PayeeFinancialAccount>
            <cbc:ID>DE99991122222</cbc:ID>
        </cac:PayeeFinancialAccount>
    </cac:PaymentMeans>
    <cac:PaymentTerms>
        <cbc:Note>#SKONTO#TAGE=14#PROZENT=2.25#</cbc:Note>
    </cac:PaymentTerms>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="EUR">536.25</cbc:TaxAmount>
        <cac:TaxSubtotal>
            <cbc:TaxableAmount currencyID="EUR">2145</cbc:TaxableAmount>
            <cbc:TaxAmount currencyID="EUR">536.25</cbc:TaxAmount>
            <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:TaxCategory>
        </cac:TaxSubtotal>
    </cac:TaxTotal>
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="EUR">2145</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="EUR">2145</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="EUR">2681.25</cbc:TaxInclusiveAmount>
        <cbc:PayableAmount currencyID="EUR">2681.25</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
    <cac:InvoiceLine>
        <cbc:ID>12</cbc:ID>
        <cbc:InvoicedQuantity unitCode="H87">100</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">2145</cbc:LineExtensionAmount>
        <cac:Item>
            <cbc:Name>Beratungsdienstleistung XYZ</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="EUR">21.45</cbc:PriceAmount>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:Amount currencyID="EUR">100</cbc:Amount>
                <cbc:BaseAmount currencyID="EUR">121.45</cbc:BaseAmount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>
</ubl:Invoice>

Die Syntax dieser XRechnung ist in diesem Fall UBL. Dieses XML kann einfach via HTTP POST an die finaX API gesendet werden:

curl --location '<https://api.finax.dev/v1/json/ubl>' \
--header 'Content-Type: application/xml' \
--header 'X-API-KEY: ••••••' \
--data-raw '<ubl:Invoice xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
    <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</cbc:CustomizationID>
    <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
    <cbc:ID>AB-13352</cbc:ID>
    <cbc:IssueDate>2024-08-24</cbc:IssueDate>
    <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
    <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
    <cbc:BuyerReference>KV-55126</cbc:BuyerReference>
    <cac:AccountingSupplierParty>
        <cac:Party>
            <cbc:EndpointID schemeID="9930">DE123456789</cbc:EndpointID>
            <cac:PartyIdentification>
                <cbc:ID schemeID="0094">Verkäufer GmbH</cbc:ID>
            </cac:PartyIdentification>
            <cac:PostalAddress>
                <cbc:CityName>Berlin</cbc:CityName>
                <cbc:PostalZone>12345</cbc:PostalZone>
                <cac:Country>
                    <cbc:IdentificationCode>DE</cbc:IdentificationCode>
                </cac:Country>
            </cac:PostalAddress>
            <cac:PartyTaxScheme>
                <cbc:CompanyID>DE-123213123</cbc:CompanyID>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:PartyTaxScheme>
            <cac:PartyLegalEntity>
                <cbc:RegistrationName>Verkäufer - schnell GmbH</cbc:RegistrationName>
            </cac:PartyLegalEntity>
            <cac:Contact>
                <cbc:Name>Max Mustermann</cbc:Name>
                <cbc:Telephone>876 654 321</cbc:Telephone>
                <cbc:ElectronicMail>max.m@mustermail.de</cbc:ElectronicMail>
            </cac:Contact>
        </cac:Party>
    </cac:AccountingSupplierParty>
    <cac:AccountingCustomerParty>
        <cac:Party>
            <cbc:EndpointID schemeID="9930">DE987654321</cbc:EndpointID>
            <cac:PostalAddress>
                <cbc:CityName>Potsdam</cbc:CityName>
                <cbc:PostalZone>14473</cbc:PostalZone>
                <cac:Country>
                    <cbc:IdentificationCode>DE</cbc:IdentificationCode>
                </cac:Country>
            </cac:PostalAddress>
            <cac:PartyLegalEntity>
                <cbc:RegistrationName>Käufer UG</cbc:RegistrationName>
            </cac:PartyLegalEntity>
        </cac:Party>
    </cac:AccountingCustomerParty>
    <cac:PaymentMeans>
        <cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>
        <cac:PayeeFinancialAccount>
            <cbc:ID>DE99991122222</cbc:ID>
        </cac:PayeeFinancialAccount>
    </cac:PaymentMeans>
    <cac:PaymentTerms>
        <cbc:Note>#SKONTO#TAGE=14#PROZENT=2.25#</cbc:Note>
    </cac:PaymentTerms>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="EUR">536.25</cbc:TaxAmount>
        <cac:TaxSubtotal>
            <cbc:TaxableAmount currencyID="EUR">2145</cbc:TaxableAmount>
            <cbc:TaxAmount currencyID="EUR">536.25</cbc:TaxAmount>
            <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:TaxCategory>
        </cac:TaxSubtotal>
    </cac:TaxTotal>
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="EUR">2145</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="EUR">2145</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="EUR">2681.25</cbc:TaxInclusiveAmount>
        <cbc:PayableAmount currencyID="EUR">2681.25</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
    <cac:InvoiceLine>
        <cbc:ID>12</cbc:ID>
        <cbc:InvoicedQuantity unitCode="H87">100</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">2145</cbc:LineExtensionAmount>
        <cac:Item>
            <cbc:Name>Beratungsdienstleistung XYZ</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="EUR">21.45</cbc:PriceAmount>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:Amount currencyID="EUR">100</cbc:Amount>
                <cbc:BaseAmount currencyID="EUR">121.45</cbc:BaseAmount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>
</ubl:Invoice>'

Diese wandelt das XML dann in das allgemeine finaX JSON Format um. Egal ob UBL/CII, XRechnung-Extension oder nicht – die finaX API bietet ein einheitliches Format zum Einlesen der XRechnungen:

{
    "invoice_number": "AB-13352",
    "invoice_issue_date": "2024-08-24",
    "invoice_type_code": 380,
    "invoice_currency_code": "EUR",
    "vat_accounting_currency_code": null,
    "value_added_tax_point_date": null,
    "value_added_tax_point_date_code": null,
    "payment_due_date": null,
    "buyer_reference": "KV-55126",
    "project_reference": null,
    "contract_reference": null,
    "purchase_order_reference": null,
    "sales_order_reference": null,
    "receiving_advice_reference": null,
    "despatch_advice_reference": null,
    "tender_or_lot_reference": null,
    "invoiced_object_identifier": null,
    "buyer_accounting_reference": null,
    "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
    "invoice_note": null,
    "process_control": {
        "business_process_type": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
        "specification_identifier": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0"
    },
    "preceding_invoice_reference": null,
    "seller": {
        "name": "Verkäufer - schnell GmbH",
        "trading_name": null,
        "identifier": [
            {
                "value": "Verkäufer GmbH",
                "scheme_identifier": "0094"
            }
        ],
        "legal_registration_identifier": null,
        "vat_identifier": "DE-123213123",
        "tax_registration_identifier": null,
        "additional_legal_information": null,
        "electronic_address": {
            "value": "DE123456789",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "address_line_1": null,
            "address_line_2": null,
            "address_line_3": null,
            "city": "Berlin",
            "post_code": "12345",
            "country_subdivision": null,
            "country_code": "DE"
        },
        "contact": {
            "point": "Max Mustermann",
            "telephone_number": "876 654 321",
            "email_address": "max.m@mustermail.de"
        }
    },
    "buyer": {
        "name": "Käufer UG",
        "trading_name": null,
        "identifier": null,
        "legal_registration_identifier": null,
        "vat_identifier": null,
        "electronic_address": {
            "value": "DE987654321",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "address_line_1": null,
            "address_line_2": null,
            "address_line_3": null,
            "city": "Potsdam",
            "post_code": "14473",
            "country_subdivision": null,
            "country_code": "DE"
        },
        "contact": null
    },
    "payee": null,
    "seller_tax_representative_party": null,
    "delivery_information": null,
    "payment_instructions": {
        "payment_means_type_code": "30",
        "payment_means_text": null,
        "remittance_information": null,
        "credit_transfer": [
            {
                "payment_account_identifier": "DE99991122222",
                "payment_account_name": null,
                "payment_service_provider_identifier": null
            }
        ],
        "payment_card_information": null,
        "direct_debit": null
    },
    "document_level_allowances": null,
    "document_level_charges": null,
    "document_totals": {
        "sum_of_invoice_line_net_amount": "2145",
        "sum_of_allowances_on_document_level": null,
        "sum_of_charges_on_document_level": null,
        "invoice_total_amount_without_vat": "2145",
        "invoice_total_vat_amount": "536.25",
        "invoice_total_vat_amount_in_accounting_currency": null,
        "invoice_total_amount_with_vat": "2681.25",
        "paid_amount": null,
        "rounding_amount": null,
        "amount_due_for_payment": "2681.25"
    },
    "vat_breakdown": [
        {
            "vat_category_taxable_amount": "2145",
            "vat_category_tax_amount": "536.25",
            "vat_category_code": "S",
            "vat_category_rate": "25",
            "vat_exemption_reason_text": null,
            "vat_exemption_reason_code": null
        }
    ],
    "additional_supporting_documents": null,
    "invoice_line": [
        {
            "invoice_line_identifier": "12",
            "invoice_line_note": null,
            "invoice_line_object_identifier": null,
            "invoiced_quantity": "100",
            "invoiced_quantity_unit_of_measure_code": "H87",
            "invoice_line_net_amount": "2145",
            "referenced_purchase_order_line_reference": null,
            "invoice_line_buyer_accounting_reference": null,
            "invoice_line_period": null,
            "invoice_line_allowances": null,
            "invoice_line_charges": null,
            "price_details": {
                "item_net_price": "21.45",
                "item_price_discount": "100",
                "item_gross_price": "121.45",
                "item_price_base_quantity": null,
                "item_price_base_quantity_unit_of_measure_code": null
            },
            "line_vat_information": {
                "invoiced_item_vat_category_code": "S",
                "invoiced_item_vat_rate": "25"
            },
            "item_information": {
                "name": "Beratungsdienstleistung XYZ",
                "description": null,
                "sellers_identifier": null,
                "buyers_identifier": null,
                "standard_identifier": null,
                "classification_identifier": null,
                "country_of_origin": null,
                "item_attributes": null
            },
            "sub_invoice_line": null
        }
    ],
    "third_party_payment": null,
    "version": "3.0.1",
    "extension": false
}

Fazit

Mit der finaX API lassen sich beliebige XRechnungs-Dateien auf ein einheitliches Format runterbrechen. Dies vereinfacht der langfristige Pflege und Verarbeitung von XRechnungen enorm.