Champs de facture JSON vers XML UBL (EN 16931 / Peppol BIS 3.0)

Ce guide détaille le mapping entre les champs de l’Invoice API de B2Brouter, les Business Terms (BT) correspondants tels que définis par la norme européenne de facturation électronique (EN 16931), et les chemins XML dans le modèle UBL 2.1 (y compris Peppol BIS Billing 3.0).

Mapping au niveau de l’en-tête

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-1	Invoice number	invoice.number	cbc:ID
BT-2	Invoice Issue Date	invoice.date	cbc:IssueDate
BT-3	Invoice Type Code	invoice.type_code (api 2026-03-02)	cbc:InvoiceTypeCode (or cbc:CreditNoteTypeCode)
BT-5	Document Currency	invoice.currency	cbc:DocumentCurrencyCode
BT-6	Tax Currency Code	invoice.contact.currency	cbc:TaxCurrencyCode
BT-7	Tax Point Date	invoice.tax_point_date	cbc:TaxPointDate
BT-9	Payment Due Date	invoice.due_date	cbc:DueDate
BT-10	Buyer Reference	invoice.buyer_reference	cbc:BuyerReference
BT-19	Accounting Cost	invoice.buyer_accounting_reference	cbc:AccountingCost
BT-22	Note (Header)	invoice.extra_info	cbc:Note

Remarques :

• BT-6 : émis uniquement lorsque la devise du contact acheteur diffère de la devise de la facture (BT-5) et que des montants de taxe dans cette devise sont présents. Lorsqu’il est défini, un second bloc cac:TaxTotal est rendu avec des montants dans cette devise.

Références et périodes

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-13	Purchase Order Reference	invoice.ponumber	cac:OrderReference/cbc:ID
BT-14	Sales Order Reference	invoice.sales_order_reference	cac:OrderReference/cbc:SalesOrderID
BT-12	Contract Reference	invoice.contract_number	cac:ContractDocumentReference/cbc:ID
BT-15	Receiving Advice Reference	invoice.receiving_advice_reference	cac:ReceiptDocumentReference/cbc:ID
BT-16	Despatch Advice Reference	invoice.delivery_note_number	cac:DespatchDocumentReference/cbc:ID
BT-25	Preceding Invoice Ref	invoice.amended_number	cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID
BT-26	Preceding Invoice Date	invoice.amended_date	cac:BillingReference/cac:InvoiceDocumentReference/cbc:IssueDate
BT-73	Invoicing Period Start	invoice.invoicing_period_start	cac:InvoicePeriod/cbc:StartDate
BT-74	Invoicing Period End	invoice.invoicing_period_end	cac:InvoicePeriod/cbc:EndDate
BT-11	Project Reference	invoice.file_reference	cac:ProjectReference/cbc:ID
—	Originator Document Ref	invoice.lot_reference	cac:OriginatorDocumentReference/cbc:ID

Remarques :

• Pour les avoirs, file_reference (BT-11) est émis comme cac:AdditionalDocumentReference/cbc:ID au lieu de cac:ProjectReference/cbc:ID.

Mapping des parties

Ce mapping est décrit pour une facture émise ; si vous souhaitez mapper une facture reçue, inversez AccountingSupplierParty et AccountingCustomerParty.

Self-billing (IssuedSelfInvoice / ReceivedSelfInvoice) : dans l’auto-facturation, l’acheteur émet la facture au nom du fournisseur ; les rôles des parties dans le XML sont donc inversés par rapport aux champs API. Pour un IssuedSelfInvoice, les données account apparaissent dans AccountingCustomerParty (votre entreprise est l’acheteur) et les données invoice.contact apparaissent dans AccountingSupplierParty (le contact est le fournisseur). Il en va de même symétriquement pour ReceivedSelfInvoice.

Seller Party

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-34	Seller Endpoint ID	account.pin_value	cac:AccountingSupplierParty/cac:Party/cbc:EndpointID @schemeID
BT-27	Seller Legal Name	account.name	cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName
BT-31	Seller VAT Identifier	account.tin_value	cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID
BT-35	Seller Address Street	account.address	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:StreetName
BT-36	Seller Address Street 2	account.address2	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName
BT-37	Seller Address City	account.city	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CityName
BT-38	Seller Address Postal Code	account.postalcode	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:PostalZone
BT-39	Seller Province	account.province	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity
BT-40	Seller Country	account.country	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode
BT-41	Seller Contact Name	account.contact_person	cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Name
BT-42	Seller Contact Phone	account.phone	cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Telephone
BT-43	Seller Contact Email	account.email	cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:ElectronicMail

Buyer Party

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-49	Buyer Endpoint ID	invoice.contact.pin_value	cac:AccountingCustomerParty/cac:Party/cbc:EndpointID @schemeID
BT-44	Buyer Legal Name	invoice.contact.name	cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName
BT-45	Buyer Trade Name	invoice.contact.name	cac:AccountingCustomerParty/cac:Party/cac:PartyName/cbc:Name
BT-48	Buyer VAT Identifier	invoice.contact.tin_value	cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID
BT-50	Buyer Address Street	invoice.contact.address	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:StreetName
BT-51	Buyer Address Street 2	invoice.contact.address2	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName
BT-52	Buyer Address City	invoice.contact.city	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CityName
BT-53	Buyer Address Postal Code	invoice.contact.postalcode	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:PostalZone
BT-54	Buyer Province	invoice.contact.province	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity
BT-55	Buyer Country	invoice.contact.country	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode
BT-56	Buyer Contact Name	invoice.contact.contact_person	cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Name
BT-57	Buyer Contact Phone	invoice.contact.phone	cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Telephone
BT-58	Buyer Contact Email	invoice.contact.email	cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail

Delivery

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-72	Delivery Date	invoice.delivery_date	cac:Delivery/cbc:ActualDeliveryDate
BT-71	Delivery Location ID	invoice.delivery_location_id	cac:Delivery/cac:DeliveryLocation/cbc:ID
BT-75	Delivery Address Street	invoice.delivery_address	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:StreetName
BT-76	Delivery Address Street 2	invoice.delivery_address2	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:AdditionalStreetName
BT-77	Delivery City	invoice.delivery_city	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CityName
BT-78	Delivery Postal Code	invoice.delivery_postalcode	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:PostalZone
BT-79	Delivery Province	invoice.delivery_province	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CountrySubentity
BT-80	Delivery Country	invoice.delivery_country	cac:Delivery/cac:DeliveryLocation/cac:Address/cac:Country/cbc:IdentificationCode
BT-70	Delivery Party Name	invoice.delivery_party_name	cac:Delivery/cac:DeliveryParty/cac:PartyName/cbc:Name

Payment

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-81	Payment Means Code	invoice.payment_method	cac:PaymentMeans/cbc:PaymentMeansCode @listID='UNCL4461'
BT-82	Payment Means Text	invoice.payment_method_text	cac:PaymentMeans/cbc:PaymentMeansCode @name
BT-83	Remittance Information	invoice.remittance_information	cac:PaymentMeans/cbc:PaymentID
BT-84	Payee Bank Account IBAN	invoice.bank_account.iban	cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID
BT-84-0	Payee Bank Account Number	invoice.bank_account.number	cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID (fallback when no IBAN)
BT-85	Payee Bank Account Name	invoice.bank_account.name	cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:Name (currently not rendered)
BT-86	Payee Bank Account BIC	invoice.bank_account.bic	cac:PaymentMeans/cac:PayeeFinancialAccount/cac:FinancialInstitutionBranch/cbc:ID
BT-87	Card Account Number	invoice.card_account_attributes.account_number	cac:PaymentMeans/cac:CardAccount/cbc:PrimaryAccountNumberID
BT-87-0	Card Account Holder Name	invoice.card_account_attributes.holder_name	cac:PaymentMeans/cac:CardAccount/cbc:HolderName
BT-88	Card Account Network ID	invoice.card_account_attributes.network	cac:PaymentMeans/cac:CardAccount/cbc:NetworkID
BT-20	Payment Terms	invoice.payment_terms	cac:PaymentTerms/cbc:Note
BT-89	Mandate Reference (SEPA DD only)	invoice.mandate_reference_identifier	cac:PaymentMeans/cac:PaymentMandate/cbc:ID
BT-90	Creditor Reference (SEPA DD)	invoice.bank_assigned_creditor_reference	cac:AccountingSupplierParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID='SEPA'
BT-91	Debtor Account IBAN (SEPA DD)	invoice.contact_iban	cac:PaymentMeans/cac:PaymentMandate/cac:PayerFinancialAccount/cbc:ID

Totals & Taxes

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-106	Line Net Amount Total	(calculated)	cac:LegalMonetaryTotal/cbc:LineExtensionAmount
BT-109	Tax Exclusive Amount	(calculated)	cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount
BT-107	Allowance Total Amount	(calculated)	cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount
BT-108	Charge Total Amount	(calculated)	cac:LegalMonetaryTotal/cbc:ChargeTotalAmount
BT-112	Tax Inclusive Amount	(calculated)	cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount
BT-113	Total Prepaid Amount	invoice.payments_on_account	cac:LegalMonetaryTotal/cbc:PrepaidAmount
BT-114	Rounding Amount	(from invoice adjustment)	cac:LegalMonetaryTotal/cbc:PayableRoundingAmount
BT-115	Amount Due for Payment	invoice.payable_amount	cac:LegalMonetaryTotal/cbc:PayableAmount
BT-110	Invoice Total VAT Amount	(calculated)	cac:TaxTotal/cbc:TaxAmount
BT-116	VAT Category Taxable Amount	(calculated from lines)	cac:TaxTotal/cac:TaxSubtotal/cbc:TaxableAmount
BT-117	VAT Category Tax Amount	(calculated from lines)	cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount
—	Withheld Amount	invoice.withheld_percent	cac:AllowanceCharge/cbc:Amount
—	Withheld Reason	invoice.amounts_withheld_reason	cac:AllowanceCharge/cbc:AllowanceChargeReason

Header Allowances & Charges

BT	Business Term	API Field (B2Brouter)	UBL XPath
BT-92	Allowance Amount	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount
BT-93	Allowance Base Amount	(calculated when percent-based)	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:BaseAmount
BT-94	Allowance Percent	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric
BT-97	Allowance Reason	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason
BT-99	Charge Amount	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount
BT-100	Charge Base Amount	(calculated when percent-based)	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:BaseAmount
BT-101	Charge Percent	allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X}	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric
BT-104	Charge Reason	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason
BT-102	Apply Tax To Allowance/Charge	allowance_charges_attributes[]{apply_taxes: true}	cac:AllowanceCharge/cac:TaxCategory

Invoice Line-Level Mapping

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

BT	Business Term	API Field (invoice line)	UBL XPath
BT-126	Invoice Line ID	position	cac:InvoiceLine/cbc:ID
BT-129	Invoiced Quantity	quantity	cac:InvoiceLine/cbc:InvoicedQuantity
BT-130	Invoiced Quantity (Unit)	unit	cac:InvoiceLine/cbc:InvoicedQuantity @unitCode
BT-131	Line Extension Amount	extension_amount (or calculated)	cac:InvoiceLine/cbc:LineExtensionAmount
BT-146	Price Amount	price	cac:InvoiceLine/cac:Price/cbc:PriceAmount
BT-153	Item Name	description	cac:InvoiceLine/cac:Item/cbc:Name
BT-154	Item Description	notes	cac:InvoiceLine/cac:Item/cbc:Description
BT-155	Seller Item ID	article_code	cac:InvoiceLine/cac:Item/cac:SellersItemIdentification/cbc:ID
BT-156	Buyer Item ID	article_code_buyer	cac:InvoiceLine/cac:Item/cac:BuyersItemIdentification/cbc:ID
BT-157	Standard Item ID	article_code2	cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID
BT-157-1	Standard Item ID Scheme	article_code2_scheme	cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID (defaults to 0160)
BT-158	Classification Code	classification_code	cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID
BT-158-1	Classification Code Scheme	classification_code_scheme	cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID
BT-151	VAT Category (per line)	taxes_attributes[].category	cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:ID
BT-152	VAT Percent (per line)	taxes_attributes[].percent	cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent
BT-120	Tax Exemption Reason	taxes_attributes[].comment	cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:TaxExemptionReason
BT-160	Additional Item Property Name	additional_item_properties_attributes[].name	cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Name
BT-161	Additional Item Property Value	additional_item_properties_attributes[].value	cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Value
BT-133	Buyer Accounting Reference	contact_reference	cac:InvoiceLine/cbc:AccountingCost
BT-134	Invoicing Line Period Start	invoicing_period_start	cac:InvoiceLine/cac:InvoicePeriod/cbc:StartDate
BT-135	Invoicing Line Period End	invoicing_period_end	cac:InvoiceLine/cac:InvoicePeriod/cbc:EndDate
BT-136	Line Allowance Amount	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount
BT-138	Line Allowance Percent	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric
BT-139	Line Allowance Reason	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason
BT-141	Line Charge Amount	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount
BT-143	Line Charge Percent	allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric
BT-144	Line Charge Reason	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason
BT-128	Purchase Order Reference (line)	invoice_lines_attributes[].ponumber	cac:InvoiceLine/cac:DocumentReference/cbc:ID
BT-132	PO Line Reference	invoice_lines_attributes[].sequence_number	cac:InvoiceLine/cac:OrderLineReference/cbc:LineID