Invoice Field Mapping Guide (B2Brouter API ↔ Business Terms ↔ Facturae XPath)

This guide maps the B2Brouter Invoice API fields and the corresponding EN 16931 Business Terms (BT) to XML paths in Facturae 3.2.2. For clarity, XPaths are shown without namespace prefixes.

Header-Level Mapping

BT	Business Term	API Field (B2Brouter)	Facturae XPath
BT-1	Invoice number	`invoice.number`	`Invoices/Invoice/InvoiceHeader/InvoiceNumber`
—	Invoice series	`invoice.series_code`	`Invoices/Invoice/InvoiceHeader/InvoiceSeriesCode`
—	Document type	(derived)	`Invoices/Invoice/InvoiceHeader/InvoiceDocumentType`
—	Invoice class	(derived)	`Invoices/Invoice/InvoiceHeader/InvoiceClass`
BT-2	Issue Date	`invoice.date`	`Invoices/Invoice/InvoiceIssueData/IssueDate`
BT-7	Operation Date	`invoice.tax_point_date` (preferred) or `invoice.delivery_date` (fallback)	`Invoices/Invoice/InvoiceIssueData/OperationDate`
BT-5	Currency	`invoice.currency`	`Invoices/Invoice/InvoiceIssueData/InvoiceCurrencyCode`
—	Language	`invoice.language`	`Invoices/Invoice/InvoiceIssueData/LanguageName`
—	Exchange Rate	`invoice.exchange_rate`	`Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRate`
—	Exchange Rate Date	`invoice.exchange_date`	`Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRateDate`
BT-22	Note (Header)	`invoice.extra_info`	`Invoices/Invoice/AdditionalData/InvoiceAdditionalInformation`
—	Legal literals	`invoice.legal_literals`	`Invoices/Invoice/LegalLiterals/LegalReference`
Notes:

ExchangeRateDetails is only emitted when the invoice currency differs from EUR. exchange_rate and exchange_date can be set via the API; when not provided, they are derived from account/system settings.
If both tax_point_date and delivery_date are present, delivery_date is appended to InvoiceAdditionalInformation.
Several fields are packed into InvoiceAdditionalInformation (see Additional Information Fields).

Payment

BT	Business Term	API Field (B2Brouter)	Facturae XPath
BT-9	Due Date	`invoice.due_date`	`Invoices/Invoice/PaymentDetails/Installment/InstallmentDueDate`
—	Installment Amount	(calculated)	`.../Installment/InstallmentAmount`
BT-81	Payment means	`invoice.payment_method`	`.../Installment/PaymentMeans`
BT-82	Payment means text	`invoice.payment_method_text`	`.../Installment/CollectionAdditionalInformation`
BT-84	Seller bank account (IBAN)	`invoice.bank_account.iban`	`.../Installment/AccountToBeCredited/IBAN`
BT-86	Seller bank account (BIC)	`invoice.bank_account.bic`	`.../Installment/AccountToBeCredited/BIC`
BT-84	Seller bank account (number, non-IBAN)	`invoice.bank_account.number`	`.../Installment/AccountToBeCredited/AccountNumber`
BT-91	Buyer bank account (IBAN, direct debit)	`invoice.contact_iban`	`.../Installment/AccountToBeDebited/IBAN`
—	Buyer bank account (number, non-IBAN)	`invoice.contact_bank_account_number`	`.../Installment/AccountToBeDebited/AccountNumber`
—	Buyer bank account (BIC, direct debit)	`invoice.contact_bic`	`.../Installment/AccountToBeDebited/BIC`
BT-10	Buyer Reference	`invoice.buyer_reference`	`.../Installment/DebitReconciliationReference`
—	Payment Reconciliation Reference	`invoice.payment_reconciliation_ref`	`.../Installment/PaymentReconciliationReference`
Notes:

PaymentDetails/Installment is emitted only when payment/terms are defined.
contact_bank_account_number and payment_reconciliation_ref are not currently in the API permitted params; they are populated from stored contact/invoice data.

References & Periods

Header-level commercial references (InvoiceIssueData):

BT	Business Term	API Field (B2Brouter)	Facturae XPath
BT-13	Purchase Order Reference	`invoice.ponumber`	`Invoices/Invoice/InvoiceIssueData/ReceiverTransactionReference`
BT-11	File reference	`invoice.file_reference`	`Invoices/Invoice/InvoiceIssueData/FileReference`
—	Receiver contract reference	`invoice.receiver_contract_reference`	`Invoices/Invoice/InvoiceIssueData/ReceiverContractReference`

Invoicing period (Header):

BT	Business Term	API Field	Facturae XPath
BT-73	Invoicing Period Start	`invoice.invoicing_period_start`	`Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/StartDate`
BT-74	Invoicing Period End	`invoice.invoicing_period_end`	`Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/EndDate`

Corrective invoices (rectified):

BT	Field	API Field	Facturae XPath
—	Method	(derived from `invoice.amended_number`)	`Invoices/Invoice/InvoiceHeader/Corrective/CorrectionMethod`
—	Method description	(derived)	`.../Corrective/CorrectionMethodDescription`
—	Reason code	`invoice.amend_reason` (defaults to `'16'`)	`.../Corrective/ReasonCode`
—	Reason description	(derived from `amend_reason` translation)	`.../Corrective/ReasonDescription`
—	Additional reason description	`invoice.extra_info`	`.../Corrective/AdditionalReasonDescription`
BT-25	Corrected invoice number	`invoice.amended_number`	`.../Corrective/InvoiceNumber` (+ `.../InvoiceSeriesCode` if applicable)
BT-26	Corrected invoice date	`invoice.amended_date`	`.../Corrective/InvoiceIssueDate` (3.2.2 only)
—	Tax period start	`invoice.amended_invoicing_period_start`	`.../Corrective/TaxPeriod/StartDate`
—	Tax period end	`invoice.amended_invoicing_period_end`	`.../Corrective/TaxPeriod/EndDate`
Notes:

CorrectionMethod is computed: '03' if amended_number == '?', otherwise '02'.

Parties Mapping (Issued Invoice)

If the invoice is received, swap SellerParty and BuyerParty.

Seller Party (Issuer)

BT	Business Term	API Field	Facturae XPath
BT-27	Seller Name	`account.name`	`Parties/SellerParty/LegalEntity/CorporateName` (or `Individual/Name` + `FirstSurname`)
BT-31	Seller VAT ID	`account.tin_value`	`Parties/SellerParty/TaxIdentification/TaxIdentificationNumber`
—	Party Identification	`invoice.party_identification`	`Parties/SellerParty/PartyIdentification`
BT-35	Seller Street	`account.address`	`Parties/SellerParty/LegalEntity/AddressInSpain/Address` (or `OverseasAddress/Address`)
BT-38	Seller Postal Code	`account.postalcode`	`Parties/SellerParty/LegalEntity/AddressInSpain/PostCode`
BT-37	Seller City	`account.city`	`Parties/SellerParty/LegalEntity/AddressInSpain/Town`
BT-39	Seller Province	`account.province`	`Parties/SellerParty/LegalEntity/AddressInSpain/Province`
BT-40	Seller Country	`account.country`	`Parties/SellerParty/LegalEntity/AddressInSpain/CountryCode` (ISO3)
BT-43	Seller Email	`account.email`	`Parties/SellerParty/LegalEntity/ContactDetails/ElectronicMail`
BT-42	Seller Phone	`account.phone`	`Parties/SellerParty/LegalEntity/ContactDetails/Telephone`
—	Seller Website	`account.website`	`Parties/SellerParty/LegalEntity/ContactDetails/WebAddress`
BT-41	Seller Contact Person	`account.contact_person`	`Parties/SellerParty/LegalEntity/ContactDetails/ContactPersons`

Buyer Party (Receiver)

BT	Business Term	API Field	Facturae XPath
BT-44	Buyer Name	`invoice.contact.name`	`Parties/BuyerParty/LegalEntity/CorporateName` (or `Individual/...`)
BT-48	Buyer VAT ID	`invoice.contact.tin_value`	`Parties/BuyerParty/TaxIdentification/TaxIdentificationNumber`
BT-50	Buyer Street	`invoice.contact.address`	`Parties/BuyerParty/LegalEntity/AddressInSpain/Address`
BT-53	Buyer Postal Code	`invoice.contact.postalcode`	`Parties/BuyerParty/LegalEntity/AddressInSpain/PostCode`
BT-52	Buyer City	`invoice.contact.city`	`Parties/BuyerParty/LegalEntity/AddressInSpain/Town`
BT-54	Buyer Province	`invoice.contact.province`	`Parties/BuyerParty/LegalEntity/AddressInSpain/Province`
BT-55	Buyer Country	`invoice.contact.country`	`Parties/BuyerParty/LegalEntity/AddressInSpain/CountryCode`
BT-58	Buyer Email	`invoice.contact.email`	`Parties/BuyerParty/LegalEntity/ContactDetails/ElectronicMail`
BT-57	Buyer Phone	`invoice.contact.phone`	`Parties/BuyerParty/LegalEntity/ContactDetails/Telephone`
BT-56	Buyer Contact Person	`invoice.contact.contact_person`	`Parties/BuyerParty/LegalEntity/ContactDetails/ContactPersons`
—	Additional Contact Details	`invoice.contact_additional_details`	`Parties/BuyerParty/LegalEntity/ContactDetails/AdditionalContactDetails`
Notes:

Use AddressInSpain vs OverseasAddress depending on the country.
PartyIdentification is only emitted when the value is a numeric string up to 10 digits.
contact.phone, contact.contact_person, and contact_additional_details are not settable via the invoice API contact params; they are read from the stored Contact record.

Administrative Centres (Spanish Public Sector)

For invoicing Spanish public administrations (FACe), administrative centres can be set with DIR3 codes:

Field	API Field	Facturae XPath
Accounting Office	`invoice.oc`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='01']/CentreCode`
Management Body	`invoice.og`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='02']/CentreCode`
Processing Unit	`invoice.ut`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='03']/CentreCode`
Proposing Body	`invoice.op`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='04']/CentreCode`
Delivery Location ID	`invoice.delivery_location_id`	Used as `CentreCode` for role 04 when `op` is not set
Centre 1-3 Names	`invoice.cin1_name` ... `invoice.cin3_name`	`AdministrativeCentre[RoleTypeCode='01'-'03']/Name`
Centre 4 Name	`invoice.cin4_name`	`AdministrativeCentre[RoleTypeCode='04']/Name`
Notes:

Each administrative centre also carries the address and contact details from the buyer party.
Delivery address fields (delivery_address, delivery_city, delivery_province, delivery_postalcode) populate the address of the RoleTypeCode 04 centre.

Taxes & Totals (Header)

BT	Business Term	API Field	Facturae XPath
BT-110	VAT total (Outputs)	(calculated)	`Invoices/Invoice/InvoiceTotals/TotalTaxOutputs` + details in `Invoices/Invoice/TaxesOutputs/Tax`
—	Withheld (header)	`invoice.amounts_withheld_reason`, `invoice.withheld_percent`	`Invoices/Invoice/InvoiceTotals/AmountsWithheld/(WithholdingReason\|WithholdingRate\|WithholdingAmount)`
—	Gross amount before taxes	(calculated)	`Invoices/Invoice/InvoiceTotals/TotalGrossAmountBeforeTaxes`
BT-92	Header Allowance Amount	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}`	`Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountAmount`
BT-94	Header Allowance Percent	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}`	`Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountRate`
BT-97	Header Allowance Reason	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}`	`Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountReason`
BT-99	Header Charge Amount	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}`	`Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeAmount`
BT-104	Header Charge Reason	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}`	`Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeReason`
BT-113	Prepaid Amount	`invoice.payments_on_account`	`Invoices/Invoice/InvoiceTotals/PaymentsOnAccount/PaymentOnAccount/PaymentOnAccountAmount`
—	Invoice total (payable)	(calculated)	`Invoices/Invoice/InvoiceTotals/InvoiceTotal`
—	Outstanding	(calculated)	`Invoices/Invoice/InvoiceTotals/TotalOutstandingAmount`
—	Executable	(calculated)	`Invoices/Invoice/InvoiceTotals/TotalExecutableAmount`
—	Reimbursable Expenses	(from charges marked as reimbursable)	`Invoices/Invoice/InvoiceTotals/ReimbursableExpenses/ReimbursableExpense`
—	Total Reimbursable Expenses	(calculated)	`Invoices/Invoice/InvoiceTotals/TotalReimbursableExpenses`
Notes:

TaxesOutputs/Tax/TaxTypeCode identifies the tax (e.g. 01 for VAT).

Invoice Line-Level Mapping

All attributes below are properties of objects in: invoice.invoice_lines_attributes[].

BT	Business Term	API Field (line)	Facturae XPath
BT-153	Item name/description	`description`	`Invoices/Invoice/Items/InvoiceLine/ItemDescription`
BT-129	Invoiced quantity	`quantity`	`.../Quantity`
BT-130	Unit of measure	`unit`	`.../UnitOfMeasure`
BT-146	Price amount (unit)	`price`	`.../UnitPriceWithoutTax`
BT-131	Line extension amount	`extension_amount` (or calculated)	`.../GrossAmount` (or `.../TotalCost`)
BT-155	Seller Item ID	`article_code`	`.../ArticleCode` (Facturae 3.2 only)
BT-154	Item notes	`notes`	`.../AdditionalLineItemInformation`
BT-132	Buyer line reference	`sequence_number`	`.../SequenceNumber`
BT-128	Receiver transaction reference	`ponumber` (fallback: `invoice.ponumber`)	`.../ReceiverTransactionReference`
—	File reference	`file_reference` (fallback: `invoice.file_reference`)	`.../FileReference`
—	File date	`file_date`	`.../FileDate`
—	Delivery note number	`delivery_note_number` (fallback: `invoice.delivery_note_number`)	`.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteNumber`
—	Delivery note date	`delivery_note_date` (fallback: `invoice.delivery_note_date`)	`.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteDate`
—	Issuer contract reference	(from `invoice.contract_number`)	`.../IssuerContractReference`
—	Issuer contract date	`invoice.issuer_contract_date`	`.../IssuerContractDate`
—	Issuer transaction reference	`issuer_transaction_reference`	`.../IssuerTransactionReference`
—	Issuer transaction date	`issuer_transaction_date`	`.../IssuerTransactionDate`
—	Receiver contract reference	`receiver_contract_reference` (fallback: `invoice.receiver_contract_reference`)	`.../ReceiverContractReference`
—	Receiver contract date	`receiver_contract_date`	`.../ReceiverContractDate`
—	Receiver transaction date	`receiver_transaction_date`	`.../ReceiverTransactionDate`
BT-134	Line Invoicing Period Start	`invoicing_period_start`	`.../LineItemPeriod/StartDate`
BT-135	Line Invoicing Period End	`invoicing_period_end`	`.../LineItemPeriod/EndDate`
BT-151	Tax type code (per line)	`taxes_attributes[].category`	`.../TaxesOutputs/Tax/TaxTypeCode`
BT-152	Tax percent (per line)	`taxes_attributes[].percent`	`.../TaxesOutputs/Tax/TaxRate`
BT-120	Tax exemption/non-subject reason	`taxes_attributes[].comment`	`.../SpecialTaxableEvent/SpecialTaxableEventReason`
—	Tax exemption/non-subject code	(derived: `'02'` if category `NS`, else `'01'`)	`.../SpecialTaxableEvent/SpecialTaxableEventCode`
BT-136	Line Allowance Amount	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}`	`.../DiscountsAndRebates/Discount/DiscountAmount`
BT-138	Line Allowance Percent	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}`	`.../DiscountsAndRebates/Discount/DiscountRate`
BT-139	Line Allowance Reason	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}`	`.../DiscountsAndRebates/Discount/DiscountReason`
BT-141	Line Charge Amount	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}`	`.../Charges/Charge/ChargeAmount`
BT-144	Line Charge Reason	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}`	`.../Charges/Charge/ChargeReason`
Notes:

Several line-level fields are packed into AdditionalLineItemInformation: article_code2, classification_code, article_code_buyer, contact_reference.
issuer_contract_date is not in the API permitted params; it is derived from stored data.

Additional Information Fields

Several fields that have dedicated XML elements in UBL/CII are packed into InvoiceAdditionalInformation in Facturae. These are appended to invoice.extra_info:

BT	API Field	Prefix 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` (when `tax_point_date` is also present)	"Delivery date:"

Factoring Assignment Data

For invoice factoring (cession of credit), the following fields populate the FactoringAssignmentData block:

Field	API Field	Facturae XPath
Assignee tax ID	`invoice.fa_taxcode`	`FactoringAssignmentData/Assignee/TaxIdentification/TaxIdentificationNumber`
Assignee name	`invoice.fa_name`	`FactoringAssignmentData/Assignee/LegalEntity/CorporateName`
Assignee address	`invoice.fa_address`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Address`
Assignee postal code	`invoice.fa_postcode`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/PostCode`
Assignee city	`invoice.fa_town`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Town`
Assignee province	`invoice.fa_province`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Province`
Assignee country	`invoice.fa_country`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/CountryCode`
Payment due date	`invoice.fa_duedate`	`FactoringAssignmentData/PaymentDetails/Installment/InstallmentDueDate`
Payment amount	`invoice.fa_import`	`FactoringAssignmentData/PaymentDetails/Installment/InstallmentAmount`
Payment method	`invoice.fa_payment_method`	`FactoringAssignmentData/PaymentDetails/Installment/PaymentMeans`
Assignee IBAN	`invoice.fa_iban`	`FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/IBAN`
Assignee BIC	`invoice.fa_bic`	`FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BIC`
Factoring clauses	`invoice.fa_clauses`	`FactoringAssignmentData/FactoringAssignmentClauses`
Additional info	`invoice.fa_info`	`FactoringAssignmentData/Assignee/LegalEntity/ContactDetails/AdditionalContactDetails`
Bank Code	`invoice.fa_bank_code`	`FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BankCode`