XRechnung erstellen - Minimalbeispiel

In diesem Blogpost wird die Erstellung einer XRechnung mithilfe der finaX API demonstriert. XRechnungen sind ein standardisiertes elektronisches Rechnungsformat, das in Deutschland für Rechnungen an öffentliche Auftraggeber vorgeschrieben ist. Die finaX API bietet eine einfache Möglichkeit, XRechnungen programmatisch zu erstellen, indem ein JSON-Objekt an die API gesendet wird.

Der Prozess umfasst folgende Schritte:

Vorbereitung der Rechnungsdaten in einem JSON-Format
Senden des JSON-Objekts an den finaX API-Endpunkt

Das Minimalbeispiel zeigt die grundlegenden Elemente, die für eine gültige XRechnung erforderlich sind, und wie diese in der JSON-Struktur abgebildet werden. Dies dient als Ausgangspunkt für komplexere Rechnungsszenarien und kann leicht erweitert werden, um zusätzliche Rechnungsdetails einzuschließen.

Rechnung als JSON Struktur

Die finaX API arbeitet mit dem modernen und seit vielen Jahren geläufigen JSON Format. Sie ist eine typische REST API. Dafür müssen die Rechnungsdaten erstmal in JSON übersetzt werden. Dabei gehen wir davon aus, dass Sie Zugriff auf alle relevanten Daten der Rechnung haben und ein JSON mit der folgenden Struktur erzeugen:

{
    "invoice_number": "33445566",
    "invoice_issue_date": "2019-08-24",
    "invoice_type_code": 380,
    "invoice_currency_code": "EUR",
    "buyer_reference": "abs1234",
    "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
    "seller": {
        "name": "Full Formal Seller Name LTD.",
        "vat_identifier": "DE-123",
        "identifier": [
            {
                "scheme_identifier": "0094",
                "value": "Full Formal Seller Name LTD."
            }
        ],
        "electronic_address": {
            "value": "DE123456789",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "city": "Sun City",
            "post_code": "12345",
            "country_code": "AD"
        },
        "contact": {
            "point": "Jens Jensen",
            "telephone_number": "876 654 321",
            "email_address": "jens.j@buyer.se"
        }
    },
    "buyer": {
        "name": "Buyer Full Name AS",
        "electronic_address": {
            "value": "DE987654321",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "city": "Moon City",
            "post_code": "12345",
            "country_code": "AD"
        }
    },
    "payment_instructions": {
        "payment_means_type_code": "30",
        "credit_transfer": [
            {
                "payment_account_identifier": "NO99991122222"
            }
        ]
    },
    "document_totals": {
        "sum_of_invoice_line_net_amount": 2145,
        "invoice_total_amount_without_vat": 2145,
        "invoice_total_amount_with_vat": 2681.25,
        "invoice_total_vat_amount": 536.25,
        "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
        }
    ],
    "invoice_line": [
        {
            "invoice_line_identifier": "12",
            "invoiced_quantity": 100,
            "invoiced_quantity_unit_of_measure_code": "H87",
            "invoice_line_net_amount": 2145,
            "price_details": {
                "item_net_price": 21.45,
                "item_price_discount": 100,
                "item_gross_price": 121.45
            },
            "line_vat_information": {
                "invoiced_item_vat_category_code": "S",
                "invoiced_item_vat_rate": 25
            },
            "item_information": {
                "name": "Item name"
            }
        }
    ]
}

Wofür welches Feld steht lässt sich einfach unter https://docs.finax.dev nachschauen.

Mit diesem JSON Format können die Daten nun an die finaX API geschickt werden und somit eine valide XRechnung in UBL oder CII XML Syntax erstellt werden.

XRechnung XML via Rest-API

Vor dem ersten Aufruf der Schnittstelle wird ein Zugangsschlüssel benötigt. Zum Testen stellen wir einen kostenlosen 14 Tage gültigen Testschlüssel zur Verfügung.

Die folgenden Beispiele zeigen einen Aufruf via cURL zum Erstellen einer XRechnung in den beiden geläufigen Formaten UBL bzw. CII.

Erstellung einer XRechnung in UBL XML

curl --location '<http://apis.finax.dev/v1/xml/ubl>' \
--header 'Content-Type: application/json' \
--header 'X-API-KEy: ••••••' \
--data-raw '{
    "invoice_number": "33445566",
    "invoice_issue_date": "2019-08-24",
    "invoice_type_code": 380,
    "invoice_currency_code": "EUR",
    "buyer_reference": "abs1234",
    "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
    "seller": {
        "name": "Full Formal Seller Name LTD.",
        "vat_identifier": "DE-123",
        "identifier": [
            {
                "scheme_identifier": "0094",
                "value": "Full Formal Seller Name LTD."
            }
        ],
        "electronic_address": {
            "value": "DE123456789",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "city": "Sun City",
            "post_code": "12345",
            "country_code": "AD"
        },
        "contact": {
            "point": "Jens Jensen",
            "telephone_number": "876 654 321",
            "email_address": "jens.j@buyer.se"
        }
    },
    "buyer": {
        "name": "Buyer Full Name AS",
        "electronic_address": {
            "value": "DE987654321",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "city": "Moon City",
            "post_code": "12345",
            "country_code": "AD"
        }
    },
    "payment_instructions": {
        "payment_means_type_code": "30",
        "credit_transfer": [
            {
                "payment_account_identifier": "NO99991122222"
            }
        ]
    },
    "document_totals": {
        "sum_of_invoice_line_net_amount": 2145,
        "invoice_total_amount_without_vat": 2145,
        "invoice_total_amount_with_vat": 2681.25,
        "invoice_total_vat_amount": 536.25,
        "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
        }
    ],
    "invoice_line": [
        {
            "invoice_line_identifier": "12",
            "invoiced_quantity": 100,
            "invoiced_quantity_unit_of_measure_code": "H87",
            "invoice_line_net_amount": 2145,
            "price_details": {
                "item_net_price": 21.45,
                "item_price_discount": 100,
                "item_gross_price": 121.45
            },
            "line_vat_information": {
                "invoiced_item_vat_category_code": "S",
                "invoiced_item_vat_rate": 25
            },
            "item_information": {
                "name": "Item name"
            }
        }
    ]
}'

Erstellung einer XRechnung in CII XML

curl --location '<https://api.finax.dev/v1/xml/cii/>' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ••••••' \
--data-raw '{
    "invoice_number": "33445566",
    "invoice_issue_date": "2019-08-24",
    "invoice_type_code": 380,
    "invoice_currency_code": "EUR",
    "buyer_reference": "abs1234",
    "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
    "seller": {
        "name": "Full Formal Seller Name LTD.",
        "vat_identifier": "DE-123",
        "identifier": [
            {
                "scheme_identifier": "0094",
                "value": "Full Formal Seller Name LTD."
            }
        ],
        "electronic_address": {
            "value": "DE123456789",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "city": "Sun City",
            "post_code": "12345",
            "country_code": "AD"
        },
        "contact": {
            "point": "Jens Jensen",
            "telephone_number": "876 654 321",
            "email_address": "jens.j@buyer.se"
        }
    },
    "buyer": {
        "name": "Buyer Full Name AS",
        "electronic_address": {
            "value": "DE987654321",
            "scheme_identifier": "9930"
        },
        "postal_address": {
            "city": "Moon City",
            "post_code": "12345",
            "country_code": "AD"
        }
    },
    "payment_instructions": {
        "payment_means_type_code": "30",
        "credit_transfer": [
            {
                "payment_account_identifier": "NO99991122222"
            }
        ]
    },
    "document_totals": {
        "sum_of_invoice_line_net_amount": 2145,
        "invoice_total_amount_without_vat": 2145,
        "invoice_total_amount_with_vat": 2681.25,
        "invoice_total_vat_amount": 536.25,
        "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
        }
    ],
    "invoice_line": [
        {
            "invoice_line_identifier": "12",
            "invoiced_quantity": 100,
            "invoiced_quantity_unit_of_measure_code": "H87",
            "invoice_line_net_amount": 2145,
            "price_details": {
                "item_net_price": 21.45,
                "item_price_discount": 100,
                "item_gross_price": 121.45
            },
            "line_vat_information": {
                "invoiced_item_vat_category_code": "S",
                "invoiced_item_vat_rate": 25
            },
            "item_information": {
                "name": "Item name"
            }
        }
    ]
}'

Die Antwort ist jeweils das entsprechende XML, welches 1-zu-1 in eine Datei geschrieben und versendet werden kann:

<rsm:CrossIndustryInvoice xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100" xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100" xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100" xmlns:qdt="urn:un:unece:uncefact:data:standard:QualifiedDataType:100">
    <rsm:ExchangedDocumentContext>
        <ram:BusinessProcessSpecifiedDocumentContextParameter>
            <ram:ID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</ram:ID>
        </ram:BusinessProcessSpecifiedDocumentContextParameter>
        <ram:GuidelineSpecifiedDocumentContextParameter>
            <ram:ID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</ram:ID>
        </ram:GuidelineSpecifiedDocumentContextParameter>
    </rsm:ExchangedDocumentContext>
    <rsm:ExchangedDocument>
        <ram:ID>33445566</ram:ID>
        <ram:TypeCode>380</ram:TypeCode>
        <ram:IssueDateTime>
            <udt:DateTimeString format="102">20190824</udt:DateTimeString>
        </ram:IssueDateTime>
    </rsm:ExchangedDocument>
    <rsm:SupplyChainTradeTransaction>
        <ram:IncludedSupplyChainTradeLineItem>
            <ram:AssociatedDocumentLineDocument>
                <ram:LineID>12</ram:LineID>
            </ram:AssociatedDocumentLineDocument>
            <ram:SpecifiedTradeProduct>
                <ram:Name>Item name</ram:Name>
            </ram:SpecifiedTradeProduct>
            <ram:SpecifiedLineTradeAgreement>
                <ram:GrossPriceProductTradePrice>
                    <ram:ChargeAmount>121.45</ram:ChargeAmount>
                    <ram:AppliedTradeAllowanceCharge>
                        <ram:ChargeIndicator>
                            <udt:Indicator>false</udt:Indicator>
                        </ram:ChargeIndicator>
                        <ram:ActualAmount>100</ram:ActualAmount>
                    </ram:AppliedTradeAllowanceCharge>
                </ram:GrossPriceProductTradePrice>
                <ram:NetPriceProductTradePrice>
                    <ram:ChargeAmount>21.45</ram:ChargeAmount>
                </ram:NetPriceProductTradePrice>
            </ram:SpecifiedLineTradeAgreement>
            <ram:SpecifiedLineTradeDelivery>
                <ram:BilledQuantity unitCode="H87">100</ram:BilledQuantity>
            </ram:SpecifiedLineTradeDelivery>
            <ram:SpecifiedLineTradeSettlement>
                <ram:ApplicableTradeTax>
                    <ram:TypeCode>VAT</ram:TypeCode>
                    <ram:CategoryCode>S</ram:CategoryCode>
                    <ram:RateApplicablePercent>25</ram:RateApplicablePercent>
                </ram:ApplicableTradeTax>
                <ram:SpecifiedTradeSettlementLineMonetarySummation>
                    <ram:LineTotalAmount>2145</ram:LineTotalAmount>
                </ram:SpecifiedTradeSettlementLineMonetarySummation>
            </ram:SpecifiedLineTradeSettlement>
        </ram:IncludedSupplyChainTradeLineItem>
        <ram:ApplicableHeaderTradeAgreement>
            <ram:BuyerReference>abs1234</ram:BuyerReference>
            <ram:SellerTradeParty>
                <ram:GlobalID schemeID="0094">Full Formal Seller Name LTD.</ram:GlobalID>
                <ram:Name>Full Formal Seller Name LTD.</ram:Name>
                <ram:DefinedTradeContact>
                    <ram:PersonName>Jens Jensen</ram:PersonName>
                    <ram:TelephoneUniversalCommunication>
                        <ram:CompleteNumber>876 654 321</ram:CompleteNumber>
                    </ram:TelephoneUniversalCommunication>
                    <ram:EmailURIUniversalCommunication>
                        <ram:URIID>jens.j@buyer.se</ram:URIID>
                    </ram:EmailURIUniversalCommunication>
                </ram:DefinedTradeContact>
                <ram:PostalTradeAddress>
                    <ram:PostcodeCode>12345</ram:PostcodeCode>
                    <ram:CityName>Sun City</ram:CityName>
                    <ram:CountryID>AD</ram:CountryID>
                </ram:PostalTradeAddress>
                <ram:URIUniversalCommunication>
                    <ram:URIID schemeID="9930">DE123456789</ram:URIID>
                </ram:URIUniversalCommunication>
                <ram:SpecifiedTaxRegistration>
                    <ram:ID schemeID="VA">DE-123</ram:ID>
                </ram:SpecifiedTaxRegistration>
            </ram:SellerTradeParty>
            <ram:BuyerTradeParty>
                <ram:Name>Buyer Full Name AS</ram:Name>
                <ram:PostalTradeAddress>
                    <ram:PostcodeCode>12345</ram:PostcodeCode>
                    <ram:CityName>Moon City</ram:CityName>
                    <ram:CountryID>AD</ram:CountryID>
                </ram:PostalTradeAddress>
                <ram:URIUniversalCommunication>
                    <ram:URIID schemeID="9930">DE987654321</ram:URIID>
                </ram:URIUniversalCommunication>
            </ram:BuyerTradeParty>
        </ram:ApplicableHeaderTradeAgreement>
        <ram:ApplicableHeaderTradeDelivery/>
        <ram:ApplicableHeaderTradeSettlement>
            <ram:InvoiceCurrencyCode>EUR</ram:InvoiceCurrencyCode>
            <ram:SpecifiedTradeSettlementPaymentMeans>
                <ram:TypeCode>30</ram:TypeCode>
                <ram:PayeePartyCreditorFinancialAccount>
                    <ram:IBANID>NO99991122222</ram:IBANID>
                </ram:PayeePartyCreditorFinancialAccount>
            </ram:SpecifiedTradeSettlementPaymentMeans>
            <ram:ApplicableTradeTax>
                <ram:CalculatedAmount>536.25</ram:CalculatedAmount>
                <ram:TypeCode>VAT</ram:TypeCode>
                <ram:BasisAmount>2145</ram:BasisAmount>
                <ram:CategoryCode>S</ram:CategoryCode>
                <ram:RateApplicablePercent>25</ram:RateApplicablePercent>
            </ram:ApplicableTradeTax>
            <ram:SpecifiedTradePaymentTerms>
                <ram:Description>#SKONTO#TAGE=14#PROZENT=2.25#
</ram:Description>
            </ram:SpecifiedTradePaymentTerms>
            <ram:SpecifiedTradeSettlementHeaderMonetarySummation>
                <ram:LineTotalAmount>2145</ram:LineTotalAmount>
                <ram:TaxBasisTotalAmount>2145</ram:TaxBasisTotalAmount>
                <ram:TaxTotalAmount currencyID="EUR">536.25</ram:TaxTotalAmount>
                <ram:GrandTotalAmount>2681.25</ram:GrandTotalAmount>
                <ram:DuePayableAmount>2681.25</ram:DuePayableAmount>
            </ram:SpecifiedTradeSettlementHeaderMonetarySummation>
        </ram:ApplicableHeaderTradeSettlement>
    </rsm:SupplyChainTradeTransaction>
</rsm:CrossIndustryInvoice>

Dieses XML kann nun via E-Mail, Peppol oder entsprechende Portale einfach an den Rechnungsempfänger gesendet werden.

Wie sich hingegen XRechnungen einlesen lassen haben wir vor kurzem hier beschrieben.

Fazit

Das Erstellen von XRechnungen in den geläufigen Formaten stellt sich mit der finaX API als sehr einfach heraus. finaX kümmert sich um die Validation und Instandhaltung entsprechend der Spezifikation der KoSIT – Sie erstellen mit Hilfe der finaX XRechnung API moderne E-Rechnungen. Für eventuelle Updates stellen wir Guides zu Verfügung und informieren Sie frühzeitig über bevorstehende Änderungen.

XRechnung erstellen – JSON Minimalbeispiel

Rechnung als JSON Struktur

XRechnung XML via Rest-API

Fazit

Produkt

Allgemein

Rechtliches