XRechnung zu PDF Umwandlung
In der neuen Version der finaX API 1.4.19 steht eine neue, experimentelle Funktion zu Verfügung – die Erstellung von ZUGFeRD PDF Dateien aus XRechnungsdaten – UBL, CII oder finaX JSON. In diesem Artikel erklären wir die Funktionsweise und warum die Funktion (noch!) experimentell ist. Mit den neuen Funktionen lassen sich Daten aus CII und UBL einfach als PDF visualisieren.
Schnell ausprobieren? Kostenlosen Testschlüssel holen und mit unserer Postman Collection starten!
XRechnung visualisieren
Der XRechnung Standard sieht in erster Linie 3 Formate vor – UBL, CII und jüngst ZUGFeRD. Ein Problem, welchem sich viele Softwarehersteller ausgesetzt sehen, ist die Visualisierung der Eingangsrechnung im UBL oder CII Format. Beide Formate sind XML und für Endverbraucher nicht verständlich. In den letzten Monaten haben wir bei finaX eine Lösung entwickelt, welche es erlaubt aus den strukturierten Daten UBL, CII oder JSON eine neutrale PDF Darstellung der beinhalteten Daten zu erzeugen. Das resultierende PDF ist PDF/A konform, was Voraussetzung des ZUGFeRD-Standards ist.
UBL oder CII zu Zugferd PDF
Um ein UBL oder CII XML zu visualisieren kann einer der beiden Endpunkte https://api.finax.dev/v1/pdf/ubl oder https://api.finax.dev/v1/pdf/cii verwendet werden. Um Zugriff auf die API zu bekommen einfach hier einen 14 Tage gültigen Testschlüssel erstellen.
An die API muss lediglich ein einfacher HTTP POST Request gesendet werden, welcher folgenden Payload beinhaltet (CII):
{
"xml": "<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>Full11 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>",
"config": {
"intro_text": "Sehr geehrte Damen und Herren,\\n\\nIch bedanke mich für die gute Zusammenarbeit stelle Ihnen vereinbarungsgemäß folgende Leistungen in Rechnung.",
"outro_text": "Bitte überweisen Sie den Rechnungsbetrag ohne Abzüge auf das angegebene Bankkonto.",
"file_name": "invoice.pdf"
}
}
XML beinhaltet das UBL oder CII – je nach Endpunkt. Via des config Objektes lässt sich ein Einleitungstext, ein Abschlusstext und der Dateiname der zu erzeugenden Datei konfigurieren. Die genaue Beschreibung der Endpunkte steht unter https://docs.finax.dev/#tag/Experimental zur Verfügung.
JSON zu Zugferd PDF
Auch die Erzeugung eines neutralen Zugferd PDF via JSON ist einfach über den finaX API Endpunkt https://api.finax.dev/v1/pdf/json abzubilden. Der Payload für den HTTP POST Request sieht folgendermaßen aus:
{
"invoice": {
"invoice_number": "33445566",
"invoice_issue_date": "2019-08-24",
"invoice_type_code": 380,
"invoice_currency_code": "EUR",
"value_added_tax_point_date": "2019-08-24",
"buyer_reference": "abs1234",
"payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
"invoice_note": [
{
"invoice_note": "Please note our new phone number 33 44 55 66",
"invoice_note_subject_code": "INV"
}
],
"seller": {
"name": "Full Formal Seller Name LTD.",
"trading_name": "Seller Business Name AS",
"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",
"identifier": {
"scheme_identifier": "0094",
"value": "SE8765456787"
},
"legal_registration_identifier": {
"scheme_identifier": "0094",
"value": "5560104525"
},
"vat_identifier": "SE8765456787",
"electronic_address": {
"value": "DE987654321",
"scheme_identifier": "9930"
},
"postal_address": {
"city": "Moon City",
"post_code": "12345",
"country_code": "AD"
},
"contact": {
"point": "Jens Jensen",
"telephone_number": "876 654 321",
"email_address": "jens.j@buyer.se"
}
},
"payment_instructions": {
"payment_means_type_code": "30",
"payment_means_text": "Credit transfer",
"remittance_information": "432948234234234",
"credit_transfer": [
{
"payment_account_identifier": "NO99991122222",
"payment_account_name": "Payment Account",
"payment_service_provider_identifier": "SSKMDEMMXXX"
}
]
},
"document_totals": {
"sum_of_invoice_line_net_amount": 2145,
"sum_of_allowances_on_document_level": 0,
"sum_of_charges_on_document_level": 0,
"invoice_total_amount_without_vat": 2145,
"invoice_total_vat_amount": 536.25,
"invoice_total_vat_amount_in_accounting_currency": 536.25,
"invoice_total_amount_with_vat": 2681.25,
"paid_amount": 1000,
"rounding_amount": 0,
"amount_due_for_payment": 1681.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",
"invoice_line_note": "New article number 12345",
"invoice_line_object_identifier": {
"scheme_identifier": "AAA",
"value": "AB1345"
},
"invoiced_quantity": 100,
"invoiced_quantity_unit_of_measure_code": "H87",
"invoice_line_net_amount": 2145,
"referenced_purchase_order_line_reference": "3",
"invoice_line_buyer_accounting_reference": "1287:65464",
"invoice_line_period": {
"invoice_line_period_start_date": "2019-08-24",
"invoice_line_period_end_date": "2019-08-24"
},
"invoice_line_allowances": {
"amount": 200,
"base_amount": 1000,
"percentage": 20,
"reason": "Discount",
"reason_code": "95"
},
"invoice_line_charges": {
"amount": 200,
"base_amount": 1000,
"percentage": 20,
"reason": "Overtime",
"reason_code": "ABD"
},
"price_details": {
"item_net_price": 21.45,
"item_price_discount": 100,
"item_gross_price": 121.45,
"item_price_base_quantity": 1,
"item_price_base_quantity_unit_of_measure_code": "H87"
},
"line_vat_information": {
"invoiced_item_vat_category_code": "S",
"invoiced_item_vat_rate": 25
},
"item_information": {
"name": "Item name",
"description": "Long description of the item on the invoice line",
"sellers_identifier": "9873242",
"buyers_identifier": "123455",
"standard_identifier": {
"scheme_identifier": "0002",
"value": "string"
},
"classification_identifier": [
{
"scheme_identifier": "AA",
"value": "string"
}
],
"country_of_origin": "DE",
"item_attributes": [
{
"name": "Color",
"value": "Black"
}
]
}
}
]
},
"config": {
"intro_text": "Sehr geehrte Damen und Herren,\\n\\nIch bedanke mich für die gute Zusammenarbeit stelle Ihnen vereinbarungsgemäß folgende Leistungen in Rechnung.",
"outro_text": "Bitte überweisen Sie den Rechnungsbetrag ohne Abzüge auf das angegebene Bankkonto.",
"file_name": "invoice.pdf"
}
}
Neben dem vorher genannten config Objekt, werden die Rechnungsdaten hier im invoice Objekt hinterlegt.
Anmerkungen
Datum: 04.10.2024
Aktuell werden noch nicht alle Felder des XRechnungs-Standard visualisiert. Die aus unserer Sicht relevantesten Felder sind allerdings bereits abgebildet (Verkäufer, Käufer, Zahlungsinformationen, Bestellpositionen etc.). Ein Auflistung der unterstützten und nicht unterstützten Felder findet sich hier:
https://docs.finax.dev/#tag/Experimental
Wir arbeiten daran, alle relevanten Felder abzubilden und werden die Liste Stück für Stück aktualisieren. Unsere Roadmap sieht vor das Feature im Januar 2025 von “experimentell” auf “stabil” umzustellen.
Dafür brauchen wir Feedback. Wir freuen uns über jede Art von konstruktivem Feedback, Ideen oder Anmerkungen. Einfach per Mail an kontakt@finax.dev.
Fazit
Ein PDF aus CII, UBL oder JSON zu erstellen wird mit der API von finaX ein Kinderspiel. Eingangsrechnungen oder Ausgangsrechnungen – ganz egal, die finaX API ermöglicht eine einfache Visualisierung, egal für welchen Zweck.