Camps JSON de factura a XML UBL (EN 16931 / Peppol BIS 3.0)

Aquesta guia detalla el mapeig entre els camps de la B2Brouter Invoice API, els corresponents Business Terms (BT) definits per l’estàndard europeu de facturació electrònica (EN 16931) i les rutes XML del model UBL 2.1 (incloent-hi Peppol BIS Billing 3.0).

Mapeig a nivell de capçalera

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-1	Número de factura	invoice.number	cbc:ID
BT-2	Data d’emissió	invoice.date	cbc:IssueDate
BT-3	Codi de tipus de factura	invoice.type_code	cbc:InvoiceTypeCode (o cbc:CreditNoteTypeCode)
BT-5	Moneda del document	invoice.currency	cbc:DocumentCurrencyCode
BT-6	Codi de moneda fiscal	invoice.tax_currency_code	cbc:TaxCurrencyCode
BT-7	Data del punt d’impost	invoice.tax_point_date	cbc:TaxPointDate
BT-9	Data de venciment	invoice.due_date	cbc:DueDate
BT-10	Referència del comprador	invoice.buyer_reference	cbc:BuyerReference
BT-19	Centre de cost comptable	invoice.buyer_accounting_reference	cbc:AccountingCost
BT-22	Nota (capçalera)	invoice.extra_info	cbc:Note

Notes:

• BT-6 només s’emet si s’informa invoice.tax_currency_code; la moneda del contacte comprador no l’estableix. Envia’l juntament amb invoice.tax_amount_in_tax_currency (BT-111), que es renderitza en un segon bloc cac:TaxTotal en aquesta moneda. Si només envies el codi, la factura es crea però no supera la validació Peppol (BR-53, PEPPOL-EN16931-R054, PEPPOL-EN16931-R055). Si només envies l’import, s’ignora.

Referències i períodes

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-13	Referència de comanda de compra	invoice.ponumber	cac:OrderReference/cbc:ID
BT-14	Referència de comanda de venda	invoice.sales_order_reference	cac:OrderReference/cbc:SalesOrderID
BT-12	Referència de contracte	invoice.contract_number	cac:ContractDocumentReference/cbc:ID
BT-15	Referència d’albarà de recepció	invoice.receiving_advice_reference	cac:ReceiptDocumentReference/cbc:ID
BT-16	Referència d’albarà d’expedició	invoice.delivery_note_number	cac:DespatchDocumentReference/cbc:ID
BT-25	Referència de factura precedent	invoice.amended_number	cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID
BT-26	Data de la factura precedent	invoice.amended_date	cac:BillingReference/cac:InvoiceDocumentReference/cbc:IssueDate
BT-73	Inici del període de facturació	invoice.invoicing_period_start	cac:InvoicePeriod/cbc:StartDate
BT-74	Fi del període de facturació	invoice.invoicing_period_end	cac:InvoicePeriod/cbc:EndDate
BT-11	Referència de projecte	invoice.file_reference	cac:ProjectReference/cbc:ID
—	Referència de document originador	invoice.lot_reference	cac:OriginatorDocumentReference/cbc:ID

Notes:

• Per a notes de crèdit, file_reference s’emet com a cac:AdditionalDocumentReference/cbc:ID en lloc de cac:ProjectReference/cbc:ID.

Mapeig de parts

Aquest mapeig està descrit per a una factura emesa; si vols mapar una factura rebuda, intercanvia AccountingSupplierParty i AccountingCustomerParty.

Self-billing (IssuedSelfInvoice / ReceivedSelfInvoice): en self-billing, el comprador emet la factura en nom del proveïdor, de manera que els rols de les parts a l’XML s’inverteixen respecte dels camps de l’API.

Part venedora

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-34	Endpoint ID del venedor	account.pin_value	cac:AccountingSupplierParty/cac:Party/cbc:EndpointID @schemeID
BT-27	Nom legal del venedor	account.name	cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName
BT-31	Identificador IVA del venedor	account.tin_value	cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID
BT-35	Carrer del venedor	account.address	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:StreetName
BT-36	Carrer 2 del venedor	account.address2	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName
BT-37	Ciutat del venedor	account.city	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CityName
BT-38	Codi postal del venedor	account.postalcode	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:PostalZone
BT-39	Província del venedor	account.province	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity
BT-40	País del venedor	account.country	cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode
BT-41	Nom de contacte del venedor	account.contact_person	cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Name
BT-42	Telèfon del venedor	account.phone	cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Telephone
BT-43	Correu del venedor	account.email	cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:ElectronicMail

Part compradora

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-49	Endpoint ID del comprador	invoice.contact.pin_value	cac:AccountingCustomerParty/cac:Party/cbc:EndpointID @schemeID
BT-46	Identificador del comprador	invoice.contact.party_identification	cac:AccountingCustomerParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID
BT-47	Identificador de registre legal del comprador	invoice.contact.cin_value (cin_scheme)	cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID @schemeID
BT-44	Nom legal del comprador	invoice.contact.name	cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName
BT-45	Nom comercial del comprador	invoice.contact.name	cac:AccountingCustomerParty/cac:Party/cac:PartyName/cbc:Name
BT-48	Identificador IVA del comprador	invoice.contact.tin_value	cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID
BT-50	Carrer del comprador	invoice.contact.address	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:StreetName
BT-51	Carrer 2 del comprador	invoice.contact.address2	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName
BT-52	Ciutat del comprador	invoice.contact.city	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CityName
BT-53	Codi postal del comprador	invoice.contact.postalcode	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:PostalZone
BT-54	Província del comprador	invoice.contact.province	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity
BT-55	País del comprador	invoice.contact.country	cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode
BT-56	Nom de contacte del comprador	invoice.contact.contact_person	cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Name
BT-57	Telèfon del comprador	invoice.contact.phone	cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Telephone
BT-58	Correu del comprador	invoice.contact.email	cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail

Notes:

• BT-46: l’atribut @schemeID només s’emet, amb el valor 0009, quan l’identificador coincideix amb el SIRET d’establiment del contacte; en la resta de casos l’element no porta @schemeID. Als perfils francesos (FRCIUS i extensió FR) el BT-46 no surt de party_identification: s’emet el SIRET del contacte amb schemeID="0009" i, si el contacte en té, el code service amb schemeID="0224".
• BT-47: l’atribut @schemeID és el codi ICD de cin_scheme. Si el contacte no té cin_value, s’emet pin_value i, si tampoc n’hi ha, tin_value. Per a un contacte francès l’identificador legal és el SIREN: un sufix (8040) o un code routage (0224) desats com a cin_value es resolen al SIREN sota 0002; un SIRET (0009) es resol al SIREN si el contacte és una oficina i, als perfils francesos, sempre.
• BT-31 i BT-48: cac:PartyTaxScheme/cac:TaxScheme/cbc:ID surt de l’esquema de l’identificador: VAT (o GST per als esquemes GST) quan l’esquema és taxcode. Si la part no té tin_value, s’hi escriu el cin_value. Si l’esquema del CIN no és taxcode (per exemple un GLN, 0088), el codi és ZZZ i el document no porta l’identificador d’IVA. Si la part no té ni TIN ni CIN, el bloc cac:PartyTaxScheme no surt. Tampoc no surt quan la factura porta un impost de categoria O. Perquè el document porti el número d’IVA del comprador, desa’l a tin_value del contacte amb un esquema taxcode (vegeu Esquemes). Només el porten els documents generats després del canvi.

Direcció d’importació

Quan es puja o es rep un fitxer UBL, l’importador llegeix el comprador de cac:AccountingCustomerParty/cac:Party així:

• cbc:EndpointID i el seu @schemeID passen a pin_value i pin_scheme tal com venen. Un endpoint amb schemeID="EM" (correu electrònic) no es llegeix, i un endpoint igual a l’adreça Peppol del teu propi compte es descarta.
• cac:PartyLegalEntity/cbc:CompanyID i el seu @schemeID passen a cin_value i cin_scheme. Un CompanyID que repeteix el número d’IVA es descarta.
• Si el fitxer no porta CompanyID, l’EndpointID omple el CIN només quan el seu esquema és un identificador d’empresa (per exemple 0002 o 0009), mai quan és un esquema d’encaminament (0224, 0225, 8040). D’un endpoint 0225 se’n deriva el SIREN inicial, que passa a cin_value sota 0002.
• cac:PartyIdentification/cbc:ID passa a party_identification (BT-46); si n’hi ha més d’un, té prioritat el que porta un esquema d’identificador d’empresa (un SIRET sota 0009) i després el que no porta @schemeID. Un SIRET sota 0009 també omple el CIN si encara és buit.

Les quatre composicions d’encaminament franceses (SIREN, SIREN_SIRET, SIREN_SIRET_CodeRoutage, SIREN_Suffix) viatgen com a valor de cbc:EndpointID schemeID="0225" i es desen a pin_value sense modificar: l’importador no compon ni divideix l’adreça. Un CompanyID sense @schemeID que coincideix amb el sufix d’una adreça SIREN_Suffix s’etiqueta amb l’esquema 8040.

Lliurament

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-72	Data de lliurament	invoice.delivery_date	cac:Delivery/cbc:ActualDeliveryDate
BT-71	ID de la ubicació de lliurament	invoice.delivery_location_id	cac:Delivery/cac:DeliveryLocation/cbc:ID
BT-75	Carrer de lliurament	invoice.delivery_address	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:StreetName
BT-76	Carrer 2 de lliurament	invoice.delivery_address2	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:AdditionalStreetName
BT-77	Ciutat de lliurament	invoice.delivery_city	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CityName
BT-78	Codi postal de lliurament	invoice.delivery_postalcode	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:PostalZone
BT-79	Província de lliurament	invoice.delivery_province	cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CountrySubentity
BT-80	País de lliurament	invoice.delivery_country	cac:Delivery/cac:DeliveryLocation/cac:Address/cac:Country/cbc:IdentificationCode
BT-70	Nom de la part de lliurament	invoice.delivery_party_name	cac:Delivery/cac:DeliveryParty/cac:PartyName/cbc:Name

Pagament

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-81	Codi de mitjà de pagament	invoice.payment_method	cac:PaymentMeans/cbc:PaymentMeansCode @listID='UNCL4461'
BT-82	Text del mitjà de pagament	invoice.payment_method_text	cac:PaymentMeans/cbc:PaymentMeansCode @name
BT-83	Informació de remesa	invoice.remittance_information	cac:PaymentMeans/cbc:PaymentID
BT-84	IBAN del compte del beneficiari	invoice.bank_account.iban	cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID
BT-84-0	Número de compte del beneficiari	invoice.bank_account.number	cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID
BT-85	Nom del compte del beneficiari	invoice.bank_account.name	cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:Name
BT-86	BIC del compte del beneficiari	invoice.bank_account.bic	cac:PaymentMeans/cac:PayeeFinancialAccount/cac:FinancialInstitutionBranch/cbc:ID
BT-87	Número de compte de targeta	invoice.card_account_attributes.account_number	cac:PaymentMeans/cac:CardAccount/cbc:PrimaryAccountNumberID
BT-87-0	Nom del titular de la targeta	invoice.card_account_attributes.holder_name	cac:PaymentMeans/cac:CardAccount/cbc:HolderName
BT-88	Xarxa de la targeta	invoice.card_account_attributes.network	cac:PaymentMeans/cac:CardAccount/cbc:NetworkID
BT-20	Termes de pagament	invoice.payment_terms	cac:PaymentTerms/cbc:Note
BT-89	Referència de mandat	invoice.mandate_reference_identifier	cac:PaymentMeans/cac:PaymentMandate/cbc:ID
BT-90	Referència del creditor	invoice.bank_assigned_creditor_reference	cac:AccountingSupplierParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID='SEPA'
BT-91	IBAN del compte del deutor	invoice.contact_iban	cac:PaymentMeans/cac:PaymentMandate/cac:PayerFinancialAccount/cbc:ID

Totals i impostos

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-106	Total net de línies	(calculat)	cac:LegalMonetaryTotal/cbc:LineExtensionAmount
BT-109	Import exempt d’impostos	(calculat)	cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount
BT-107	Total de descomptes	(calculat)	cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount
BT-108	Total de recàrrecs	(calculat)	cac:LegalMonetaryTotal/cbc:ChargeTotalAmount
BT-112	Import amb impostos inclosos	(calculat)	cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount
BT-113	Import total prepagat	invoice.payments_on_account	cac:LegalMonetaryTotal/cbc:PrepaidAmount
BT-114	Import d’arrodoniment	(des d’ajust de factura)	cac:LegalMonetaryTotal/cbc:PayableRoundingAmount
BT-115	Import pendent de pagament	invoice.payable_amount	cac:LegalMonetaryTotal/cbc:PayableAmount
BT-110	Total IVA de la factura	(calculat)	cac:TaxTotal/cbc:TaxAmount
BT-111	Total IVA en moneda fiscal	invoice.tax_amount_in_tax_currency	cac:TaxTotal/cbc:TaxAmount (2n bloc, currencyID = BT-6)
BT-116	Base imposable per categoria IVA	(calculat des de línies)	cac:TaxTotal/cac:TaxSubtotal/cbc:TaxableAmount
BT-117	Import d’impost per categoria IVA	(calculat des de línies)	cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount
BT-120	Motiu d’exempció d’IVA	invoice_lines_attributes[].taxes_attributes[].comment	cac:TaxTotal/cac:TaxSubtotal/cac:TaxCategory/cbc:TaxExemptionReason
—	Import retingut	invoice.withheld_percent	cac:AllowanceCharge/cbc:Amount
—	Motiu de retenció	invoice.amounts_withheld_reason	cac:AllowanceCharge/cbc:AllowanceChargeReason

Motiu d’exempció d’IVA (BT-120): el motiu s’informa a l’impost de cada línia (taxes_attributes[].comment), però no s’escriu a la línia de la factura. B2Brouter agrupa els impostos de les línies per categoria i tipus al desglossament d’IVA (cac:TaxTotal/cac:TaxSubtotal) i hi escriu el motiu, un per grup. Si diverses línies del mateix grup porten comentaris diferents, només se n’exporta un. S’exporta per a les categories d’exempció (E, AE, G, K, O) i s’omet per a S, Z, L i M, on l’EN 16931 no l’admet.

Descomptes i recàrrecs de capçalera

BT	Business Term	Camp API (B2Brouter)	XPath UBL
BT-92	Import del descompte	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount
BT-93	Base del descompte	(calculada quan hi ha percentatge)	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:BaseAmount
BT-94	Percentatge del descompte	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric
BT-97	Motiu del descompte	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason
BT-99	Import del recàrrec	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount
BT-100	Base del recàrrec	(calculada quan hi ha percentatge)	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:BaseAmount
BT-101	Percentatge del recàrrec	allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X}	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric
BT-104	Motiu del recàrrec	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason
BT-102	Aplicar impost al descompte/recàrrec	allowance_charges_attributes[]{apply_taxes: true}	cac:AllowanceCharge/cac:TaxCategory

Mapeig a nivell de línia de factura

Tots els atributs següents són propietats dels objectes de invoice.invoice_lines_attributes[].

BT	Business Term	Camp API (línia)	XPath UBL
BT-126	ID de línia de factura	position	cac:InvoiceLine/cbc:ID
BT-129	Quantitat facturada	quantity	cac:InvoiceLine/cbc:InvoicedQuantity
BT-130	Quantitat facturada (unitat)	unit	cac:InvoiceLine/cbc:InvoicedQuantity @unitCode
BT-131	Import total de línia	extension_amount	cac:InvoiceLine/cbc:LineExtensionAmount
BT-146	Import del preu	price	cac:InvoiceLine/cac:Price/cbc:PriceAmount
BT-153	Nom de l’article	description	cac:InvoiceLine/cac:Item/cbc:Name
BT-154	Descripció de l’article	notes	cac:InvoiceLine/cac:Item/cbc:Description
BT-155	ID de l’article del venedor	article_code	cac:InvoiceLine/cac:Item/cac:SellersItemIdentification/cbc:ID
BT-156	ID de l’article del comprador	article_code_buyer	cac:InvoiceLine/cac:Item/cac:BuyersItemIdentification/cbc:ID
BT-157	ID estàndard de l’article	article_code2	cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID
BT-157-1	Esquema de l’ID estàndard	article_code2_scheme	cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID
BT-158	Codi de classificació	classification_code	cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID
BT-158-1	Esquema del codi de classificació	classification_code_scheme	cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID
BT-151	Categoria IVA per línia	taxes_attributes[].category	cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:ID
BT-152	Percentatge IVA per línia	taxes_attributes[].percent	cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent
BT-160	Nom de propietat addicional	additional_item_properties_attributes[].name	cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Name
BT-161	Valor de propietat addicional	additional_item_properties_attributes[].value	cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Value
BT-133	Referència comptable del comprador	contact_reference	cac:InvoiceLine/cbc:AccountingCost
BT-134	Inici del període de línia	invoicing_period_start	cac:InvoiceLine/cac:InvoicePeriod/cbc:StartDate
BT-135	Fi del període de línia	invoicing_period_end	cac:InvoiceLine/cac:InvoicePeriod/cbc:EndDate
BT-136	Import de descompte de línia	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount
BT-138	Percentatge de descompte de línia	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric
BT-139	Motiu del descompte de línia	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason
BT-141	Import de recàrrec de línia	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount
BT-143	Percentatge de recàrrec de línia	allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric
BT-144	Motiu del recàrrec de línia	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason
BT-128	Referència de comanda (línia)	invoice_lines_attributes[].ponumber	cac:InvoiceLine/cac:DocumentReference/cbc:ID
BT-132	Referència de línia de comanda	invoice_lines_attributes[].sequence_number	cac:InvoiceLine/cac:OrderLineReference/cbc:LineID