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

Esta guía detalla el mapeo entre los campos de la API de facturas de B2Brouter, los Términos de Negocio (BT) correspondientes definidos por el estándar europeo de facturación electrónica (EN 16931) y las rutas XML del modelo UBL 2.1 (incluyendo Peppol BIS Billing 3.0).

Mapeo a nivel de cabecera

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-1	Número de factura	`invoice.number`	`cbc:ID`
BT-2	Fecha de emisión	`invoice.date`	`cbc:IssueDate`
BT-3	Código de tipo de factura	`invoice.type_code` (api 2026-03-02)	`cbc:InvoiceTypeCode` (o `cbc:CreditNoteTypeCode`)
BT-5	Moneda del documento	`invoice.currency`	`cbc:DocumentCurrencyCode`
BT-6	Código de moneda fiscal	`invoice.contact.currency`	`cbc:TaxCurrencyCode`
BT-7	Fecha del punto impositivo	`invoice.tax_point_date`	`cbc:TaxPointDate`
BT-9	Fecha de vencimiento	`invoice.due_date`	`cbc:DueDate`
BT-10	Referencia del comprador	`invoice.buyer_reference`	`cbc:BuyerReference`
BT-19	Referencia contable	`invoice.buyer_accounting_reference`	`cbc:AccountingCost`
BT-22	Nota (cabecera)	`invoice.extra_info`	`cbc:Note`

Notas:

BT-6: Solo se emite cuando la moneda del contacto comprador difiere de la moneda de la factura (BT-5) y hay importes de impuestos en dicha moneda. Cuando se establece, se renderiza un segundo bloque cac:TaxTotal con los importes en esta moneda.

Referencias y períodos

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-13	Referencia de orden de compra	`invoice.ponumber`	`cac:OrderReference/cbc:ID`
BT-14	Referencia de pedido de venta	`invoice.sales_order_reference`	`cac:OrderReference/cbc:SalesOrderID`
BT-12	Referencia de contrato	`invoice.contract_number`	`cac:ContractDocumentReference/cbc:ID`
BT-15	Referencia de aviso de recepción	`invoice.receiving_advice_reference`	`cac:ReceiptDocumentReference/cbc:ID`
BT-16	Referencia de aviso de despacho	`invoice.delivery_note_number`	`cac:DespatchDocumentReference/cbc:ID`
BT-25	Referencia de factura anterior	`invoice.amended_number`	`cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID`
BT-26	Fecha de factura anterior	`invoice.amended_date`	`cac:BillingReference/cac:InvoiceDocumentReference/cbc:IssueDate`
BT-73	Inicio del período de facturación	`invoice.invoicing_period_start`	`cac:InvoicePeriod/cbc:StartDate`
BT-74	Fin del período de facturación	`invoice.invoicing_period_end`	`cac:InvoicePeriod/cbc:EndDate`
BT-11	Referencia de proyecto	`invoice.file_reference`	`cac:ProjectReference/cbc:ID`
—	Referencia de documento originador	`invoice.lot_reference`	`cac:OriginatorDocumentReference/cbc:ID`

Notas:

Para notas de crédito, file_reference (BT-11) se emite como cac:AdditionalDocumentReference/cbc:ID en lugar de cac:ProjectReference/cbc:ID.

Mapeo de partes

Este mapeo se describe para una factura emitida; si deseas mapear una factura recibida, intercambia AccountingSupplierParty y AccountingCustomerParty.

Autofacturación (IssuedSelfInvoice / ReceivedSelfInvoice): en la autofacturación el comprador emite la factura en nombre del proveedor, por lo que los roles de las partes en el XML se invierten respecto a los campos de la API. Para una IssuedSelfInvoice, los datos de account aparecen en AccountingCustomerParty (tu empresa es el comprador) y los datos de invoice.contact aparecen en AccountingSupplierParty (el contacto es el proveedor). Lo mismo aplica simétricamente a ReceivedSelfInvoice.

Parte vendedora

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-34	ID de endpoint del vendedor	`account.pin_value`	`cac:AccountingSupplierParty/cac:Party/cbc:EndpointID @schemeID`
BT-27	Nombre legal del vendedor	`account.name`	`cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName`
BT-31	NIF/IVA del vendedor	`account.tin_value`	`cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID`
BT-35	Calle del vendedor	`account.address`	`cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:StreetName`
BT-36	Calle 2 del vendedor	`account.address2`	`cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName`
BT-37	Ciudad del vendedor	`account.city`	`cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CityName`
BT-38	Código postal del vendedor	`account.postalcode`	`cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:PostalZone`
BT-39	Provincia del vendedor	`account.province`	`cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity`
BT-40	País del vendedor	`account.country`	`cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode`
BT-41	Nombre de contacto del vendedor	`account.contact_person`	`cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Name`
BT-42	Teléfono de contacto del vendedor	`account.phone`	`cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Telephone`
BT-43	Email de contacto del vendedor	`account.email`	`cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:ElectronicMail`

Parte compradora

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-49	ID de endpoint del comprador	`invoice.contact.pin_value`	`cac:AccountingCustomerParty/cac:Party/cbc:EndpointID @schemeID`
BT-44	Nombre legal del comprador	`invoice.contact.name`	`cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName`
BT-45	Nombre comercial del comprador	`invoice.contact.name`	`cac:AccountingCustomerParty/cac:Party/cac:PartyName/cbc:Name`
BT-48	NIF/IVA del comprador	`invoice.contact.tin_value`	`cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID`
BT-50	Calle del comprador	`invoice.contact.address`	`cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:StreetName`
BT-51	Calle 2 del comprador	`invoice.contact.address2`	`cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName`
BT-52	Ciudad del comprador	`invoice.contact.city`	`cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CityName`
BT-53	Código postal del comprador	`invoice.contact.postalcode`	`cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:PostalZone`
BT-54	Provincia 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	Nombre de contacto del comprador	`invoice.contact.contact_person`	`cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Name`
BT-57	Teléfono de contacto del comprador	`invoice.contact.phone`	`cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Telephone`
BT-58	Email de contacto del comprador	`invoice.contact.email`	`cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail`

Entrega

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-72	Fecha de entrega	`invoice.delivery_date`	`cac:Delivery/cbc:ActualDeliveryDate`
BT-71	ID de ubicación de entrega	`invoice.delivery_location_id`	`cac:Delivery/cac:DeliveryLocation/cbc:ID`
BT-75	Calle de entrega	`invoice.delivery_address`	`cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:StreetName`
BT-76	Calle 2 de entrega	`invoice.delivery_address2`	`cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:AdditionalStreetName`
BT-77	Ciudad de entrega	`invoice.delivery_city`	`cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CityName`
BT-78	Código postal de entrega	`invoice.delivery_postalcode`	`cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:PostalZone`
BT-79	Provincia de entrega	`invoice.delivery_province`	`cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CountrySubentity`
BT-80	País de entrega	`invoice.delivery_country`	`cac:Delivery/cac:DeliveryLocation/cac:Address/cac:Country/cbc:IdentificationCode`
BT-70	Nombre de la parte de entrega	`invoice.delivery_party_name`	`cac:Delivery/cac:DeliveryParty/cac:PartyName/cbc:Name`

Pago

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-81	Código de medio de pago	`invoice.payment_method`	`cac:PaymentMeans/cbc:PaymentMeansCode @listID='UNCL4461'`
BT-82	Texto del medio de pago	`invoice.payment_method_text`	`cac:PaymentMeans/cbc:PaymentMeansCode @name`
BT-83	Información de remesa	`invoice.remittance_information`	`cac:PaymentMeans/cbc:PaymentID`
BT-84	IBAN de cuenta bancaria del beneficiario	`invoice.bank_account.iban`	`cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID`
BT-84-0	Número de cuenta bancaria del beneficiario	`invoice.bank_account.number`	`cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID` (alternativo cuando no hay IBAN)
BT-85	Nombre de cuenta bancaria del beneficiario	`invoice.bank_account.name`	`cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:Name` (actualmente no se renderiza)
BT-86	BIC de cuenta bancaria del beneficiario	`invoice.bank_account.bic`	`cac:PaymentMeans/cac:PayeeFinancialAccount/cac:FinancialInstitutionBranch/cbc:ID`
BT-87	Número de cuenta de tarjeta	`invoice.card_account_attributes.account_number`	`cac:PaymentMeans/cac:CardAccount/cbc:PrimaryAccountNumberID`
BT-87-0	Nombre del titular de la tarjeta	`invoice.card_account_attributes.holder_name`	`cac:PaymentMeans/cac:CardAccount/cbc:HolderName`
BT-88	ID de red de tarjeta	`invoice.card_account_attributes.network`	`cac:PaymentMeans/cac:CardAccount/cbc:NetworkID`
BT-20	Condiciones de pago	`invoice.payment_terms`	`cac:PaymentTerms/cbc:Note`
BT-89	Referencia de mandato (solo SEPA DD)	`invoice.mandate_reference_identifier`	`cac:PaymentMeans/cac:PaymentMandate/cbc:ID`
BT-90	Referencia del acreedor (SEPA DD)	`invoice.bank_assigned_creditor_reference`	`cac:AccountingSupplierParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID='SEPA'`
BT-91	IBAN de cuenta del deudor (SEPA DD)	`invoice.contact_iban`	`cac:PaymentMeans/cac:PaymentMandate/cac:PayerFinancialAccount/cbc:ID`

Totales e impuestos

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-106	Total importes netos de líneas	(calculado)	`cac:LegalMonetaryTotal/cbc:LineExtensionAmount`
BT-109	Importe sin impuestos	(calculado)	`cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount`
BT-107	Total importes de descuentos	(calculado)	`cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount`
BT-108	Total importes de cargos	(calculado)	`cac:LegalMonetaryTotal/cbc:ChargeTotalAmount`
BT-112	Importe con impuestos	(calculado)	`cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount`
BT-113	Total importe prepagado	`invoice.payments_on_account`	`cac:LegalMonetaryTotal/cbc:PrepaidAmount`
BT-114	Importe de redondeo	(del ajuste de factura)	`cac:LegalMonetaryTotal/cbc:PayableRoundingAmount`
BT-115	Importe pendiente de pago	`invoice.payable_amount`	`cac:LegalMonetaryTotal/cbc:PayableAmount`
BT-110	Importe total de IVA	(calculado)	`cac:TaxTotal/cbc:TaxAmount`
BT-116	Base imponible por categoría	(calculado de las líneas)	`cac:TaxTotal/cac:TaxSubtotal/cbc:TaxableAmount`
BT-117	Importe de IVA por categoría	(calculado de las líneas)	`cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount`
—	Importe retenido	`invoice.withheld_percent`	`cac:AllowanceCharge/cbc:Amount`
—	Motivo de retención	`invoice.amounts_withheld_reason`	`cac:AllowanceCharge/cbc:AllowanceChargeReason`

Descuentos y cargos de cabecera

BT	Término de negocio	Campo API (B2Brouter)	UBL XPath
BT-92	Importe del descuento	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}`	`cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount`
BT-93	Importe base del descuento	(calculado cuando es porcentual)	`cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:BaseAmount`
BT-94	Porcentaje del descuento	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}`	`cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric`
BT-97	Motivo del descuento	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}`	`cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason`
BT-99	Importe del cargo	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}`	`cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount`
BT-100	Importe base del cargo	(calculado cuando es porcentual)	`cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:BaseAmount`
BT-101	Porcentaje del cargo	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X}`	`cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric`
BT-104	Motivo del cargo	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}`	`cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason`
BT-102	Aplicar impuesto al descuento/cargo	`allowance_charges_attributes[]{apply_taxes: true}`	`cac:AllowanceCharge/cac:TaxCategory`

Mapeo a nivel de línea de factura

Todos los atributos siguientes son propiedades de objetos en: invoice.invoice_lines_attributes[].

BT	Término de negocio	Campo API (línea)	UBL XPath
BT-126	ID de línea de factura	`position`	`cac:InvoiceLine/cbc:ID`
BT-129	Cantidad facturada	`quantity`	`cac:InvoiceLine/cbc:InvoicedQuantity`
BT-130	Cantidad facturada (unidad)	`unit`	`cac:InvoiceLine/cbc:InvoicedQuantity @unitCode`
BT-131	Importe de extensión de línea	`extension_amount` (o calculado)	`cac:InvoiceLine/cbc:LineExtensionAmount`
BT-146	Precio unitario	`price`	`cac:InvoiceLine/cac:Price/cbc:PriceAmount`
BT-153	Nombre del artículo	`description`	`cac:InvoiceLine/cac:Item/cbc:Name`
BT-154	Descripción del artículo	`notes`	`cac:InvoiceLine/cac:Item/cbc:Description`
BT-155	ID del artículo del vendedor	`article_code`	`cac:InvoiceLine/cac:Item/cac:SellersItemIdentification/cbc:ID`
BT-156	ID del artículo del comprador	`article_code_buyer`	`cac:InvoiceLine/cac:Item/cac:BuyersItemIdentification/cbc:ID`
BT-157	ID estándar del artículo	`article_code2`	`cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID`
BT-157-1	Esquema del ID estándar del artículo	`article_code2_scheme`	`cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID` (por defecto `0160`)
BT-158	Código de clasificación	`classification_code`	`cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID`
BT-158-1	Esquema de código de clasificación	`classification_code_scheme`	`cac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID`
BT-151	Categoría IVA (por línea)	`taxes_attributes[].category`	`cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:ID`
BT-152	Porcentaje IVA (por línea)	`taxes_attributes[].percent`	`cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent`
BT-120	Motivo de exención fiscal	`taxes_attributes[].comment`	`cac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:TaxExemptionReason`
BT-160	Nombre de propiedad adicional	`additional_item_properties_attributes[].name`	`cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Name`
BT-161	Valor de propiedad adicional	`additional_item_properties_attributes[].value`	`cac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Value`
BT-133	Referencia contable del comprador	`contact_reference`	`cac:InvoiceLine/cbc:AccountingCost`
BT-134	Inicio del período de facturación de línea	`invoicing_period_start`	`cac:InvoiceLine/cac:InvoicePeriod/cbc:StartDate`
BT-135	Fin del período de facturación de línea	`invoicing_period_end`	`cac:InvoiceLine/cac:InvoicePeriod/cbc:EndDate`
BT-136	Importe del descuento de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}`	`cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount`
BT-138	Porcentaje del descuento de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}`	`cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric`
BT-139	Motivo del descuento de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}`	`cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason`
BT-141	Importe del cargo de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}`	`cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount`
BT-143	Porcentaje del cargo de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X}`	`cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric`
BT-144	Motivo del cargo de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}`	`cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason`
BT-128	Referencia de orden de compra (línea)	`invoice_lines_attributes[].ponumber`	`cac:InvoiceLine/cac:DocumentReference/cbc:ID`
BT-132	Referencia de línea de PO	`invoice_lines_attributes[].sequence_number`	`cac:InvoiceLine/cac:OrderLineReference/cbc:LineID`