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.
| 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 are not settable via the API; 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).
| 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.
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'.
If the invoice is received, swap SellerParty and BuyerParty.
| 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 |
| 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.
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.
| 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 | invoice.discount_amount | Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountAmount |
| BT-94 | Header Allowance Percent | invoice.discount_percent | Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountRate |
| BT-97 | Header Allowance Reason | invoice.discount_text | Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountReason |
| BT-99 | Header Charge Amount | invoice.charge_amount | Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeAmount |
| BT-104 | Header Charge Reason | invoice.charge_reason | 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).
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 | discount_amount | .../DiscountsAndRebates/Discount/DiscountAmount |
| BT-138 | Line Allowance Percent | discount_percent | .../DiscountsAndRebates/Discount/DiscountRate |
| BT-139 | Line Allowance Reason | discount_text | .../DiscountsAndRebates/Discount/DiscountReason |
| BT-141 | Line Charge Amount | charge_amount | .../Charges/Charge/ChargeAmount |
| BT-144 | Line Charge Reason | charge_reason | .../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.
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:" |
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 |
