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
Section titled “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.contact.currency | 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 quan la moneda del contacte comprador és diferent de la moneda de la factura i existeixen imports fiscals en aquella moneda. Quan s’estableix, es renderitza un segon bloc
cac:TaxTotal.
Referències i períodes
Section titled “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_references’emet com acac:AdditionalDocumentReference/cbc:IDen lloc decac:ProjectReference/cbc:ID.
Mapeig de parts
Section titled “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
Section titled “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
Section titled “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-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 |
Lliurament
Section titled “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
Section titled “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
Section titled “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-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 |
| — | Import retingut | invoice.withheld_percent | cac:AllowanceCharge/cbc:Amount |
| — | Motiu de retenció | invoice.amounts_withheld_reason | cac:AllowanceCharge/cbc:AllowanceChargeReason |
Descomptes i recàrrecs de capçalera
Section titled “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
Section titled “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-120 | Motiu d’exempció fiscal | taxes_attributes[].comment | cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:TaxExemptionReason |
| 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 |