Champs de facture JSON vers XML Facturae (3.2.2)

Ce guide mappe les champs de l’Invoice API de B2Brouter et les Business Terms (BT) EN 16931 correspondants vers les chemins XML de Facturae 3.2.2. Pour plus de clarté, les XPaths sont affichés sans préfixes d’espace de noms.

Mapping au niveau de l’en-tête

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

Remarques :

• ExchangeRateDetails n’est émis que lorsque la devise de la facture diffère de l’EUR. exchange_rate et exchange_date peuvent être définis via l’API ; lorsqu’ils ne le sont pas, ils sont dérivés des paramètres du compte/système.
• Si tax_point_date et delivery_date sont tous deux présents, delivery_date est ajouté à InvoiceAdditionalInformation.
• Plusieurs champs sont regroupés dans InvoiceAdditionalInformation (voir 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

Remarques :

• PaymentDetails/Installment n’est émis que lorsque des informations de paiement / conditions sont définies.

Références et périodes

Références commerciales au niveau de l’en-tête (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

Période de facturation (en-tête) :

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

Factures rectificatives :

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

Remarques :

• CorrectionMethod est calculé : '03' si amended_number == '?', sinon '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

Remarques :

• Utilisez AddressInSpain ou OverseasAddress en fonction du pays.
• PartyIdentification n’est émis que lorsque la valeur est une chaîne numérique de 10 chiffres maximum.

Administrative Centres (Spanish Public Sector)

Pour la facturation aux administrations publiques espagnoles (FACe), les centres administratifs peuvent être définis avec des codes DIR3 :

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

Remarques :

• Chaque centre administratif porte également l’adresse et les coordonnées de la partie acheteuse.
• Les champs d’adresse de livraison (delivery_address, delivery_city, delivery_province, delivery_postalcode) alimentent l’adresse du centre RoleTypeCode 04.

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

Remarques :

• TaxesOutputs/Tax/TaxTypeCode identifie la taxe (par exemple 01 pour TVA).

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

Remarques :

• Several line-level fields are packed into AdditionalLineItemInformation: article_code2, classification_code, article_code_buyer, contact_reference.

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