JSON-Rechnungsfelder zu Facturae XML (3.2.2)

Diese Anleitung beschreibt die Zuordnung der B2Brouter Invoice API-Felder und der entsprechenden EN 16931 Business Terms (BT) zu XML-Pfaden in Facturae 3.2.2. Der Übersichtlichkeit halber werden XPaths ohne Namespace-Präfixe dargestellt.

Zuordnung auf Header-Ebene

BT	Business Term	API-Feld (B2Brouter)	Facturae XPath
BT-1	Rechnungsnummer	invoice.number	Invoices/Invoice/InvoiceHeader/InvoiceNumber
—	Rechnungsserie	invoice.series_code	Invoices/Invoice/InvoiceHeader/InvoiceSeriesCode
—	Dokumenttyp	(abgeleitet)	Invoices/Invoice/InvoiceHeader/InvoiceDocumentType
—	Rechnungsklasse	(abgeleitet)	Invoices/Invoice/InvoiceHeader/InvoiceClass
BT-2	Ausstellungsdatum	invoice.date	Invoices/Invoice/InvoiceIssueData/IssueDate
BT-7	Leistungsdatum	invoice.tax_point_date (bevorzugt) oder invoice.delivery_date (Fallback)	Invoices/Invoice/InvoiceIssueData/OperationDate
BT-5	Währung	invoice.currency	Invoices/Invoice/InvoiceIssueData/InvoiceCurrencyCode
—	Sprache	invoice.language	Invoices/Invoice/InvoiceIssueData/LanguageName
—	Wechselkurs	invoice.exchange_rate	Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRate
—	Wechselkursdatum	invoice.exchange_date	Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRateDate
BT-22	Hinweis (Header)	invoice.extra_info	Invoices/Invoice/AdditionalData/InvoiceAdditionalInformation
—	Rechtshinweise	invoice.legal_literals	Invoices/Invoice/LegalLiterals/LegalReference

Hinweise:

• ExchangeRateDetails wird nur ausgegeben, wenn die Rechnungswährung von EUR abweicht. exchange_rate und exchange_date können über die API gesetzt werden; wenn nicht angegeben, werden sie aus den Konto-/Systemeinstellungen abgeleitet.
• Wenn sowohl tax_point_date als auch delivery_date vorhanden sind, wird delivery_date an InvoiceAdditionalInformation angehängt.
• Mehrere Felder werden in InvoiceAdditionalInformation zusammengefasst (siehe Zusätzliche Informationsfelder).

Zahlung

BT	Business Term	API-Feld (B2Brouter)	Facturae XPath
BT-9	Fälligkeitsdatum	invoice.due_date	Invoices/Invoice/PaymentDetails/Installment/InstallmentDueDate
—	Ratenbetrag	(berechnet)	.../Installment/InstallmentAmount
BT-81	Zahlungsmittel	invoice.payment_method	.../Installment/PaymentMeans
BT-82	Zahlungsmitteltext	invoice.payment_method_text	.../Installment/CollectionAdditionalInformation
BT-84	Bankverbindung Verkäufer (IBAN)	invoice.bank_account.iban	.../Installment/AccountToBeCredited/IBAN
BT-86	Bankverbindung Verkäufer (BIC)	invoice.bank_account.bic	.../Installment/AccountToBeCredited/BIC
BT-84	Bankverbindung Verkäufer (Nummer, kein IBAN)	invoice.bank_account.number	.../Installment/AccountToBeCredited/AccountNumber
BT-91	Bankverbindung Käufer (IBAN, Lastschrift)	invoice.contact_iban	.../Installment/AccountToBeDebited/IBAN
—	Bankverbindung Käufer (Nummer, kein IBAN)	invoice.contact_bank_account_number	.../Installment/AccountToBeDebited/AccountNumber
—	Bankverbindung Käufer (BIC, Lastschrift)	invoice.contact_bic	.../Installment/AccountToBeDebited/BIC
BT-10	Käuferreferenz	invoice.buyer_reference	.../Installment/DebitReconciliationReference
—	Zahlungsabgleichsreferenz	invoice.payment_reconciliation_ref	.../Installment/PaymentReconciliationReference

Hinweise:

• PaymentDetails/Installment wird nur ausgegeben, wenn Zahlungskonditionen definiert sind.

Referenzen & Zeiträume

Kaufmännische Referenzen auf Header-Ebene (InvoiceIssueData):

BT	Business Term	API-Feld (B2Brouter)	Facturae XPath
BT-13	Bestellreferenz	invoice.ponumber	Invoices/Invoice/InvoiceIssueData/ReceiverTransactionReference
BT-11	Dateireferenz	invoice.file_reference	Invoices/Invoice/InvoiceIssueData/FileReference
—	Vertragsreferenz des Empfängers	invoice.receiver_contract_reference	Invoices/Invoice/InvoiceIssueData/ReceiverContractReference

Rechnungszeitraum (Header):

BT	Business Term	API-Feld	Facturae XPath
BT-73	Beginn Rechnungszeitraum	invoice.invoicing_period_start	Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/StartDate
BT-74	Ende Rechnungszeitraum	invoice.invoicing_period_end	Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/EndDate

Korrekturrechnungen (berichtigte Rechnungen):

BT	Feld	API-Feld	Facturae XPath
—	Methode	(abgeleitet aus invoice.amended_number)	Invoices/Invoice/InvoiceHeader/Corrective/CorrectionMethod
—	Methodenbeschreibung	(abgeleitet)	.../Corrective/CorrectionMethodDescription
—	Grundcode	invoice.amend_reason (Standard: '16')	.../Corrective/ReasonCode
—	Grundbeschreibung	(abgeleitet aus amend_reason-Übersetzung)	.../Corrective/ReasonDescription
—	Zusätzliche Grundbeschreibung	invoice.extra_info	.../Corrective/AdditionalReasonDescription
BT-25	Nummer der korrigierten Rechnung	invoice.amended_number	.../Corrective/InvoiceNumber (+ .../InvoiceSeriesCode falls zutr.)
BT-26	Datum der korrigierten Rechnung	invoice.amended_date	.../Corrective/InvoiceIssueDate (nur 3.2.2)
—	Beginn Steuerzeitraum	invoice.amended_invoicing_period_start	.../Corrective/TaxPeriod/StartDate
—	Ende Steuerzeitraum	invoice.amended_invoicing_period_end	.../Corrective/TaxPeriod/EndDate

Hinweise:

• CorrectionMethod wird berechnet: '03' wenn amended_number == '?', sonst '02'.

Zuordnung der Parteien (ausgestellte Rechnung)

Bei einer empfangenen Rechnung sind SellerParty und BuyerParty zu vertauschen.

Verkäuferpartei (Aussteller)

BT	Business Term	API-Feld	Facturae XPath
BT-27	Name des Verkäufers	account.name	Parties/SellerParty/LegalEntity/CorporateName (oder Individual/Name + FirstSurname)
BT-31	USt-IdNr. des Verkäufers	account.tin_value	Parties/SellerParty/TaxIdentification/TaxIdentificationNumber
—	Parteiidentifikation	invoice.party_identification	Parties/SellerParty/PartyIdentification
BT-35	Straße des Verkäufers	account.address	Parties/SellerParty/LegalEntity/AddressInSpain/Address (oder OverseasAddress/Address)
BT-38	PLZ des Verkäufers	account.postalcode	Parties/SellerParty/LegalEntity/AddressInSpain/PostCode
BT-37	Stadt des Verkäufers	account.city	Parties/SellerParty/LegalEntity/AddressInSpain/Town
BT-39	Provinz des Verkäufers	account.province	Parties/SellerParty/LegalEntity/AddressInSpain/Province
BT-40	Land des Verkäufers	account.country	Parties/SellerParty/LegalEntity/AddressInSpain/CountryCode (ISO3)
BT-43	E-Mail des Verkäufers	account.email	Parties/SellerParty/LegalEntity/ContactDetails/ElectronicMail
BT-42	Telefon des Verkäufers	account.phone	Parties/SellerParty/LegalEntity/ContactDetails/Telephone
—	Website des Verkäufers	account.website	Parties/SellerParty/LegalEntity/ContactDetails/WebAddress
BT-41	Ansprechpartner Verkäufer	account.contact_person	Parties/SellerParty/LegalEntity/ContactDetails/ContactPersons

Käuferpartei (Empfänger)

BT	Business Term	API-Feld	Facturae XPath
BT-44	Name des Käufers	invoice.contact.name	Parties/BuyerParty/LegalEntity/CorporateName (oder Individual/...)
BT-48	USt-IdNr. des Käufers	invoice.contact.tin_value	Parties/BuyerParty/TaxIdentification/TaxIdentificationNumber
BT-50	Straße des Käufers	invoice.contact.address	Parties/BuyerParty/LegalEntity/AddressInSpain/Address
BT-53	PLZ des Käufers	invoice.contact.postalcode	Parties/BuyerParty/LegalEntity/AddressInSpain/PostCode
BT-52	Stadt des Käufers	invoice.contact.city	Parties/BuyerParty/LegalEntity/AddressInSpain/Town
BT-54	Provinz des Käufers	invoice.contact.province	Parties/BuyerParty/LegalEntity/AddressInSpain/Province
BT-55	Land des Käufers	invoice.contact.country	Parties/BuyerParty/LegalEntity/AddressInSpain/CountryCode
BT-58	E-Mail des Käufers	invoice.contact.email	Parties/BuyerParty/LegalEntity/ContactDetails/ElectronicMail
BT-57	Telefon des Käufers	invoice.contact.phone	Parties/BuyerParty/LegalEntity/ContactDetails/Telephone
BT-56	Ansprechpartner Käufer	invoice.contact.contact_person	Parties/BuyerParty/LegalEntity/ContactDetails/ContactPersons
—	Weitere Kontaktdaten	invoice.contact_additional_details	Parties/BuyerParty/LegalEntity/ContactDetails/AdditionalContactDetails

Hinweise:

• Verwende AddressInSpain oder OverseasAddress je nach Land.
• PartyIdentification wird nur ausgegeben, wenn der Wert eine numerische Zeichenkette mit bis zu 10 Stellen ist.

Verwaltungszentren (Spanischer öffentlicher Sektor)

Für die Rechnungsstellung an spanische Behörden (FACe) können Verwaltungszentren mit DIR3-Codes angegeben werden:

Feld	API-Feld	Facturae XPath
Buchhaltungsstelle	invoice.oc	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='01']/CentreCode
Verwaltungsorgan	invoice.og	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='02']/CentreCode
Bearbeitungseinheit	invoice.ut	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='03']/CentreCode
Vorschlagendes Organ	invoice.op	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='04']/CentreCode
Lieferort-ID	invoice.delivery_location_id	Wird als CentreCode für Rolle 04 verwendet, wenn op nicht gesetzt ist
Namen Zentrum 1–3	invoice.cin1_name … invoice.cin3_name	AdministrativeCentre[RoleTypeCode='01'-'03']/Name
Name Zentrum 4	invoice.cin4_name	AdministrativeCentre[RoleTypeCode='04']/Name

Hinweise:

• Jedes Verwaltungszentrum enthält auch die Adress- und Kontaktdaten der Käuferpartei.
• Lieferadressfelder (delivery_address, delivery_city, delivery_province, delivery_postalcode) befüllen die Adresse des Zentrums mit RoleTypeCode 04.

Steuern & Gesamtbeträge (Header)

BT	Business Term	API-Feld	Facturae XPath
BT-110	MwSt.-Gesamtbetrag (Ausgaben)	(berechnet)	Invoices/Invoice/InvoiceTotals/TotalTaxOutputs + Details in Invoices/Invoice/TaxesOutputs/Tax
—	Einbehalt (Header)	invoice.amounts_withheld_reason, invoice.withheld_percent	Invoices/Invoice/InvoiceTotals/AmountsWithheld/(WithholdingReason|WithholdingRate|WithholdingAmount)
—	Bruttobetrag vor Steuern	(berechnet)	Invoices/Invoice/InvoiceTotals/TotalGrossAmountBeforeTaxes
BT-92	Rabattbetrag (Header)	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountAmount
BT-94	Rabattprozentsatz (Header)	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountRate
BT-97	Rabattgrund (Header)	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountReason
BT-99	Zuschlagsbetrag (Header)	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeAmount
BT-104	Zuschlagsgrund (Header)	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeReason
BT-113	Vorauszahlungsbetrag	invoice.payments_on_account	Invoices/Invoice/InvoiceTotals/PaymentsOnAccount/PaymentOnAccount/PaymentOnAccountAmount
—	Rechnungsgesamtbetrag (zahlbar)	(berechnet)	Invoices/Invoice/InvoiceTotals/InvoiceTotal
—	Ausstehender Betrag	(berechnet)	Invoices/Invoice/InvoiceTotals/TotalOutstandingAmount
—	Vollstreckbarer Betrag	(berechnet)	Invoices/Invoice/InvoiceTotals/TotalExecutableAmount

Hinweise:

• TaxesOutputs/Tax/TaxTypeCode identifiziert die Steuer (z. B. 01 für MwSt.).

Zuordnung auf Rechnungspositionsebene

Alle nachfolgenden Attribute sind Eigenschaften von Objekten in: invoice.invoice_lines_attributes[].

BT	Business Term	API-Feld (Position)	Facturae XPath
BT-153	Artikelname/-beschreibung	description	Invoices/Invoice/Items/InvoiceLine/ItemDescription
BT-129	Berechnete Menge	quantity	.../Quantity
BT-130	Maßeinheit	unit	.../UnitOfMeasure
BT-146	Einzelpreis (netto)	price	.../UnitPriceWithoutTax
BT-131	Positionsbetrag	extension_amount (oder berechnet)	.../GrossAmount (oder .../TotalCost)
BT-155	Artikelnummer (Verkäufer)	article_code	.../ArticleCode (nur Facturae 3.2)
BT-154	Positionshinweis	notes	.../AdditionalLineItemInformation
BT-132	Käuferzeilenreferenz	sequence_number	.../SequenceNumber
BT-128	Transaktionsreferenz Empfänger	ponumber (Fallback: invoice.ponumber)	.../ReceiverTransactionReference
—	Dateireferenz	file_reference (Fallback: invoice.file_reference)	.../FileReference
—	Dateidatum	file_date	.../FileDate
—	Lieferscheinnummer	delivery_note_number (Fallback: invoice.delivery_note_number)	.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteNumber
—	Lieferscheindatum	delivery_note_date (Fallback: invoice.delivery_note_date)	.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteDate
—	Vertragsreferenz Aussteller	(aus invoice.contract_number)	.../IssuerContractReference
—	Vertragsdatum Aussteller	invoice.issuer_contract_date	.../IssuerContractDate
—	Transaktionsreferenz Aussteller	issuer_transaction_reference	.../IssuerTransactionReference
—	Transaktionsdatum Aussteller	issuer_transaction_date	.../IssuerTransactionDate
—	Vertragsreferenz Empfänger	receiver_contract_reference (Fallback: invoice.receiver_contract_reference)	.../ReceiverContractReference
—	Vertragsdatum Empfänger	receiver_contract_date	.../ReceiverContractDate
—	Transaktionsdatum Empfänger	receiver_transaction_date	.../ReceiverTransactionDate
BT-134	Beginn Abrechnungszeitraum (Position)	invoicing_period_start	.../LineItemPeriod/StartDate
BT-135	Ende Abrechnungszeitraum (Position)	invoicing_period_end	.../LineItemPeriod/EndDate
BT-151	Steuertypcode (je Position)	taxes_attributes[].category	.../TaxesOutputs/Tax/TaxTypeCode
BT-152	Steuerprozentsatz (je Position)	taxes_attributes[].percent	.../TaxesOutputs/Tax/TaxRate
BT-120	Steuerbefreiungsgrund	taxes_attributes[].comment	.../SpecialTaxableEvent/SpecialTaxableEventReason
—	Steuerbefreiungscode	(abgeleitet: '02' wenn Kategorie NS, sonst '01')	.../SpecialTaxableEvent/SpecialTaxableEventCode
BT-136	Rabattbetrag (Position)	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	.../DiscountsAndRebates/Discount/DiscountAmount
BT-138	Rabattprozentsatz (Position)	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	.../DiscountsAndRebates/Discount/DiscountRate
BT-139	Rabattgrund (Position)	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	.../DiscountsAndRebates/Discount/DiscountReason
BT-141	Zuschlagsbetrag (Position)	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	.../Charges/Charge/ChargeAmount
BT-144	Zuschlagsgrund (Position)	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	.../Charges/Charge/ChargeReason

Hinweise:

• Mehrere Felder auf Positionsebene werden in AdditionalLineItemInformation zusammengefasst: article_code2, classification_code, article_code_buyer, contact_reference.

Zusätzliche Informationsfelder

Mehrere Felder, die in UBL/CII eigene XML-Elemente haben, werden in Facturae in InvoiceAdditionalInformation zusammengefasst. Sie werden an invoice.extra_info angehängt:

BT	API-Feld	Präfix in AdditionalInformation
BT-14	invoice.sales_order_reference	”Sales order reference:“
BT-15	invoice.receiving_advice_reference	”Receiving advice reference:“
BT-20	invoice.payment_terms	”Payment terms:“
BT-83	invoice.remittance_information	”Remittance information:“
BT-90	invoice.bank_assigned_creditor_reference	”Bank assigned creditor reference:“
BT-89	invoice.mandate_reference_identifier	”Mandate reference identifier:“
BT-19	invoice.buyer_accounting_reference	”Buyer accounting reference:“
BT-72	invoice.delivery_date (wenn tax_point_date ebenfalls vorhanden)	“Delivery date:“

Factoringabtretungsdaten

Für Rechnungsfactoring (Forderungsabtretung) befüllen folgende Felder den Block FactoringAssignmentData:

Feld	API-Feld	Facturae XPath
Steuer-ID des Abtretungsempfängers	invoice.fa_taxcode	FactoringAssignmentData/Assignee/TaxIdentification/TaxIdentificationNumber
Name des Abtretungsempfängers	invoice.fa_name	FactoringAssignmentData/Assignee/LegalEntity/CorporateName
Adresse des Abtretungsempfängers	invoice.fa_address	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Address
PLZ des Abtretungsempfängers	invoice.fa_postcode	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/PostCode
Stadt des Abtretungsempfängers	invoice.fa_town	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Town
Provinz des Abtretungsempfängers	invoice.fa_province	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Province
Land des Abtretungsempfängers	invoice.fa_country	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/CountryCode
Zahlungsfälligkeitsdatum	invoice.fa_duedate	FactoringAssignmentData/PaymentDetails/Installment/InstallmentDueDate
Zahlungsbetrag	invoice.fa_import	FactoringAssignmentData/PaymentDetails/Installment/InstallmentAmount
Zahlungsmethode	invoice.fa_payment_method	FactoringAssignmentData/PaymentDetails/Installment/PaymentMeans
IBAN des Abtretungsempfängers	invoice.fa_iban	FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/IBAN
BIC des Abtretungsempfängers	invoice.fa_bic	FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BIC
Factoringklauseln	invoice.fa_clauses	FactoringAssignmentData/FactoringAssignmentClauses
Zusätzliche Informationen	invoice.fa_info	FactoringAssignmentData/Assignee/LegalEntity/ContactDetails/AdditionalContactDetails
Bankleitzahl	invoice.fa_bank_code	FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BankCode