Ir al contenido
Log in

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).

BTTérmino de negocioCampo API (B2Brouter)UBL XPath
BT-1Número de facturainvoice.numbercbc:ID
BT-2Fecha de emisióninvoice.datecbc:IssueDate
BT-3Código de tipo de facturainvoice.type_code (api 2026-03-02)cbc:InvoiceTypeCode (o cbc:CreditNoteTypeCode)
BT-5Moneda del documentoinvoice.currencycbc:DocumentCurrencyCode
BT-6Código de moneda fiscalinvoice.tax_currency_codecbc:TaxCurrencyCode
BT-7Fecha del punto impositivoinvoice.tax_point_datecbc:TaxPointDate
BT-9Fecha de vencimientoinvoice.due_datecbc:DueDate
BT-10Referencia del compradorinvoice.buyer_referencecbc:BuyerReference
BT-19Referencia contableinvoice.buyer_accounting_referencecbc:AccountingCost
BT-22Nota (cabecera)invoice.extra_infocbc:Note

Notas:

  • BT-6: Solo se emite si se informa invoice.tax_currency_code; la moneda del contacto comprador no lo establece. Envíalo junto con invoice.tax_amount_in_tax_currency (BT-111), que se renderiza en un segundo bloque cac:TaxTotal en esta moneda. Si solo envías el código, la factura se crea pero no supera la validación Peppol (BR-53, PEPPOL-EN16931-R054, PEPPOL-EN16931-R055). Si solo envías el importe, se ignora.
BTTérmino de negocioCampo API (B2Brouter)UBL XPath
BT-13Referencia de orden de comprainvoice.ponumbercac:OrderReference/cbc:ID
BT-14Referencia de pedido de ventainvoice.sales_order_referencecac:OrderReference/cbc:SalesOrderID
BT-12Referencia de contratoinvoice.contract_numbercac:ContractDocumentReference/cbc:ID
BT-15Referencia de aviso de recepcióninvoice.receiving_advice_referencecac:ReceiptDocumentReference/cbc:ID
BT-16Referencia de aviso de despachoinvoice.delivery_note_numbercac:DespatchDocumentReference/cbc:ID
BT-25Referencia de factura anteriorinvoice.amended_numbercac:BillingReference/cac:InvoiceDocumentReference/cbc:ID
BT-26Fecha de factura anteriorinvoice.amended_datecac:BillingReference/cac:InvoiceDocumentReference/cbc:IssueDate
BT-73Inicio del período de facturacióninvoice.invoicing_period_startcac:InvoicePeriod/cbc:StartDate
BT-74Fin del período de facturacióninvoice.invoicing_period_endcac:InvoicePeriod/cbc:EndDate
BT-11Referencia de proyectoinvoice.file_referencecac:ProjectReference/cbc:ID
—Referencia de documento originadorinvoice.lot_referencecac: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.

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.

BTTérmino de negocioCampo API (B2Brouter)UBL XPath
BT-34ID de endpoint del vendedoraccount.pin_valuecac:AccountingSupplierParty/cac:Party/cbc:EndpointID @schemeID
BT-27Nombre legal del vendedoraccount.namecac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName
BT-31NIF/IVA del vendedoraccount.tin_valuecac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID
BT-35Calle del vendedoraccount.addresscac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:StreetName
BT-36Calle 2 del vendedoraccount.address2cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName
BT-37Ciudad del vendedoraccount.citycac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CityName
BT-38Código postal del vendedoraccount.postalcodecac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:PostalZone
BT-39Provincia del vendedoraccount.provincecac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity
BT-40País del vendedoraccount.countrycac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode
BT-41Nombre de contacto del vendedoraccount.contact_personcac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Name
BT-42Teléfono de contacto del vendedoraccount.phonecac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Telephone
BT-43Email de contacto del vendedoraccount.emailcac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:ElectronicMail
BTTérmino de negocioCampo API (B2Brouter)UBL XPath
BT-49ID de endpoint del compradorinvoice.contact.pin_valuecac:AccountingCustomerParty/cac:Party/cbc:EndpointID @schemeID
BT-46Identificador del compradorinvoice.contact.party_identificationcac:AccountingCustomerParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID
BT-47Identificador de registro legal del compradorinvoice.contact.cin_value (cin_scheme)cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID @schemeID
BT-44Nombre legal del compradorinvoice.contact.namecac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName
BT-45Nombre comercial del compradorinvoice.contact.namecac:AccountingCustomerParty/cac:Party/cac:PartyName/cbc:Name
BT-48NIF/IVA del compradorinvoice.contact.tin_valuecac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID
BT-50Calle del compradorinvoice.contact.addresscac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:StreetName
BT-51Calle 2 del compradorinvoice.contact.address2cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:AdditionalStreetName
BT-52Ciudad del compradorinvoice.contact.citycac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CityName
BT-53Código postal del compradorinvoice.contact.postalcodecac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:PostalZone
BT-54Provincia del compradorinvoice.contact.provincecac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:CountrySubentity
BT-55País del compradorinvoice.contact.countrycac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode
BT-56Nombre de contacto del compradorinvoice.contact.contact_personcac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Name
BT-57Teléfono de contacto del compradorinvoice.contact.phonecac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Telephone
BT-58Email de contacto del compradorinvoice.contact.emailcac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail

Notas:

  • BT-46: el atributo @schemeID solo se emite, con el valor 0009, cuando el identificador coincide con el SIRET de establecimiento del contacto; en el resto de casos el elemento no lleva @schemeID. En los perfiles franceses (FRCIUS y extensión FR) el BT-46 no sale de party_identification: se emite el SIRET del contacto con schemeID="0009" y, si el contacto lo tiene, el code service con schemeID="0224".
  • BT-47: el atributo @schemeID es el código ICD de cin_scheme. Si el contacto no tiene cin_value, se emite pin_value y, si tampoco lo hay, tin_value. Para un contacto francés el identificador legal es el SIREN: un sufijo (8040) o un code routage (0224) guardados como cin_value se resuelven al SIREN bajo 0002; un SIRET (0009) se resuelve al SIREN si el contacto es una oficina y, en los perfiles franceses, siempre.
  • BT-31 y BT-48: cac:PartyTaxScheme/cac:TaxScheme/cbc:ID sale del esquema del identificador: VAT (o GST para los esquemas GST) cuando el esquema es taxcode. Si la parte no tiene tin_value, se escribe el cin_value. Si el esquema de ese CIN no es taxcode (por ejemplo un GLN, 0088), el código es ZZZ y el documento no lleva el identificador de IVA. Si la parte no tiene ni TIN ni CIN, el bloque cac:PartyTaxScheme no se escribe. Tampoco se escribe cuando la factura lleva un impuesto de categoría O. Para que el documento lleve el número de IVA del comprador, guárdalo en tin_value del contacto con un esquema taxcode (ver Esquemas). Solo lo llevan los documentos generados después del cambio.

Cuando se sube o se recibe un fichero UBL, el importador lee el comprador de cac:AccountingCustomerParty/cac:Party así:

  • cbc:EndpointID y su @schemeID pasan a pin_value y pin_scheme tal como vienen. Un endpoint con schemeID="EM" (correo electrónico) no se lee, y un endpoint igual a la dirección Peppol de tu propia cuenta se descarta.
  • cac:PartyLegalEntity/cbc:CompanyID y su @schemeID pasan a cin_value y cin_scheme. Un CompanyID que repite el número de IVA se descarta.
  • Si el fichero no lleva CompanyID, el EndpointID rellena el CIN solo cuando su esquema es un identificador de empresa (por ejemplo 0002 o 0009), nunca cuando es un esquema de enrutamiento (0224, 0225, 8040). De un endpoint 0225 se deriva el SIREN inicial, que pasa a cin_value bajo 0002.
  • cac:PartyIdentification/cbc:ID pasa a party_identification (BT-46); si hay varios, tiene prioridad el que lleva un esquema de identificador de empresa (un SIRET bajo 0009) y después el que no lleva @schemeID. Un SIRET bajo 0009 también rellena el CIN si aún está vacío.

Las cuatro composiciones de enrutamiento francesas (SIREN, SIREN_SIRET, SIREN_SIRET_CodeRoutage, SIREN_Suffix) viajan como valor de cbc:EndpointID schemeID="0225" y se guardan en pin_value sin modificar: el importador no compone ni divide la dirección. Un CompanyID sin @schemeID que coincide con el sufijo de una dirección SIREN_Suffix se etiqueta con el esquema 8040.

BTTérmino de negocioCampo API (B2Brouter)UBL XPath
BT-72Fecha de entregainvoice.delivery_datecac:Delivery/cbc:ActualDeliveryDate
BT-71ID de ubicación de entregainvoice.delivery_location_idcac:Delivery/cac:DeliveryLocation/cbc:ID
BT-75Calle de entregainvoice.delivery_addresscac:Delivery/cac:DeliveryLocation/cac:Address/cbc:StreetName
BT-76Calle 2 de entregainvoice.delivery_address2cac:Delivery/cac:DeliveryLocation/cac:Address/cbc:AdditionalStreetName
BT-77Ciudad de entregainvoice.delivery_citycac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CityName
BT-78Código postal de entregainvoice.delivery_postalcodecac:Delivery/cac:DeliveryLocation/cac:Address/cbc:PostalZone
BT-79Provincia de entregainvoice.delivery_provincecac:Delivery/cac:DeliveryLocation/cac:Address/cbc:CountrySubentity
BT-80País de entregainvoice.delivery_countrycac:Delivery/cac:DeliveryLocation/cac:Address/cac:Country/cbc:IdentificationCode
BT-70Nombre de la parte de entregainvoice.delivery_party_namecac:Delivery/cac:DeliveryParty/cac:PartyName/cbc:Name
BTTérmino de negocioCampo API (B2Brouter)UBL XPath
BT-81Código de medio de pagoinvoice.payment_methodcac:PaymentMeans/cbc:PaymentMeansCode @listID='UNCL4461'
BT-82Texto del medio de pagoinvoice.payment_method_textcac:PaymentMeans/cbc:PaymentMeansCode @name
BT-83Información de remesainvoice.remittance_informationcac:PaymentMeans/cbc:PaymentID
BT-84IBAN de cuenta bancaria del beneficiarioinvoice.bank_account.ibancac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID
BT-84-0Número de cuenta bancaria del beneficiarioinvoice.bank_account.numbercac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID (alternativo cuando no hay IBAN)
BT-85Nombre de cuenta bancaria del beneficiarioinvoice.bank_account.namecac:PaymentMeans/cac:PayeeFinancialAccount/cbc:Name (actualmente no se renderiza)
BT-86BIC de cuenta bancaria del beneficiarioinvoice.bank_account.biccac:PaymentMeans/cac:PayeeFinancialAccount/cac:FinancialInstitutionBranch/cbc:ID
BT-87Número de cuenta de tarjetainvoice.card_account_attributes.account_numbercac:PaymentMeans/cac:CardAccount/cbc:PrimaryAccountNumberID
BT-87-0Nombre del titular de la tarjetainvoice.card_account_attributes.holder_namecac:PaymentMeans/cac:CardAccount/cbc:HolderName
BT-88ID de red de tarjetainvoice.card_account_attributes.networkcac:PaymentMeans/cac:CardAccount/cbc:NetworkID
BT-20Condiciones de pagoinvoice.payment_termscac:PaymentTerms/cbc:Note
BT-89Referencia de mandato (solo SEPA DD)invoice.mandate_reference_identifiercac:PaymentMeans/cac:PaymentMandate/cbc:ID
BT-90Referencia del acreedor (SEPA DD)invoice.bank_assigned_creditor_referencecac:AccountingSupplierParty/cac:Party/cac:PartyIdentification/cbc:ID @schemeID='SEPA'
BT-91IBAN de cuenta del deudor (SEPA DD)invoice.contact_ibancac:PaymentMeans/cac:PaymentMandate/cac:PayerFinancialAccount/cbc:ID
BTTérmino de negocioCampo API (B2Brouter)UBL XPath
BT-106Total importes netos de líneas(calculado)cac:LegalMonetaryTotal/cbc:LineExtensionAmount
BT-109Importe sin impuestos(calculado)cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount
BT-107Total importes de descuentos(calculado)cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount
BT-108Total importes de cargos(calculado)cac:LegalMonetaryTotal/cbc:ChargeTotalAmount
BT-112Importe con impuestos(calculado)cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount
BT-113Total importe prepagadoinvoice.payments_on_accountcac:LegalMonetaryTotal/cbc:PrepaidAmount
BT-114Importe de redondeo(del ajuste de factura)cac:LegalMonetaryTotal/cbc:PayableRoundingAmount
BT-115Importe pendiente de pagoinvoice.payable_amountcac:LegalMonetaryTotal/cbc:PayableAmount
BT-110Importe total de IVA(calculado)cac:TaxTotal/cbc:TaxAmount
BT-111Total de IVA en moneda fiscalinvoice.tax_amount_in_tax_currencycac:TaxTotal/cbc:TaxAmount (2.º bloque, currencyID = BT-6)
BT-116Base imponible por categoría(calculado de las líneas)cac:TaxTotal/cac:TaxSubtotal/cbc:TaxableAmount
BT-117Importe de IVA por categoría(calculado de las líneas)cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount
BT-120Motivo de exención de IVAinvoice_lines_attributes[].taxes_attributes[].commentcac:TaxTotal/cac:TaxSubtotal/cac:TaxCategory/cbc:TaxExemptionReason
—Importe retenidoinvoice.withheld_percentcac:AllowanceCharge/cbc:Amount
—Motivo de retencióninvoice.amounts_withheld_reasoncac:AllowanceCharge/cbc:AllowanceChargeReason

Motivo de exención de IVA (BT-120): el motivo se informa en el impuesto de cada línea (taxes_attributes[].comment), pero no se escribe en la línea de la factura. B2Brouter agrupa los impuestos de las líneas por categoría y tipo en el desglose de IVA (cac:TaxTotal/cac:TaxSubtotal) y escribe allí el motivo, uno por grupo. Si varias líneas del mismo grupo llevan comentarios distintos, solo se exporta uno. Se exporta para las categorías de exención (E, AE, G, K, O) y se omite para S, Z, L y M, donde la EN 16931 no lo admite.

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

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

BTTérmino de negocioCampo API (línea)UBL XPath
BT-126ID de línea de facturapositioncac:InvoiceLine/cbc:ID
BT-129Cantidad facturadaquantitycac:InvoiceLine/cbc:InvoicedQuantity
BT-130Cantidad facturada (unidad)unitcac:InvoiceLine/cbc:InvoicedQuantity @unitCode
BT-131Importe de extensión de líneaextension_amount (o calculado)cac:InvoiceLine/cbc:LineExtensionAmount
BT-146Precio unitariopricecac:InvoiceLine/cac:Price/cbc:PriceAmount
BT-153Nombre del artículodescriptioncac:InvoiceLine/cac:Item/cbc:Name
BT-154Descripción del artículonotescac:InvoiceLine/cac:Item/cbc:Description
BT-155ID del artículo del vendedorarticle_codecac:InvoiceLine/cac:Item/cac:SellersItemIdentification/cbc:ID
BT-156ID del artículo del compradorarticle_code_buyercac:InvoiceLine/cac:Item/cac:BuyersItemIdentification/cbc:ID
BT-157ID estándar del artículoarticle_code2cac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID
BT-157-1Esquema del ID estándar del artículoarticle_code2_schemecac:InvoiceLine/cac:Item/cac:StandardItemIdentification/cbc:ID @schemeID (por defecto 0160)
BT-158Código de clasificaciónclassification_codecac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID
BT-158-1Esquema de código de clasificaciónclassification_code_schemecac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode @listID
BT-151Categoría IVA (por línea)taxes_attributes[].categorycac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:ID
BT-152Porcentaje IVA (por línea)taxes_attributes[].percentcac:InvoiceLine/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent
BT-160Nombre de propiedad adicionaladditional_item_properties_attributes[].namecac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Name
BT-161Valor de propiedad adicionaladditional_item_properties_attributes[].valuecac:InvoiceLine/cac:Item/cac:AdditionalItemProperty/cbc:Value
BT-133Referencia contable del compradorcontact_referencecac:InvoiceLine/cbc:AccountingCost
BT-134Inicio del período de facturación de líneainvoicing_period_startcac:InvoiceLine/cac:InvoicePeriod/cbc:StartDate
BT-135Fin del período de facturación de líneainvoicing_period_endcac:InvoiceLine/cac:InvoicePeriod/cbc:EndDate
BT-136Importe del descuento de líneaallowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:Amount
BT-138Porcentaje del descuento de líneaallowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:MultiplierFactorNumeric
BT-139Motivo del descuento de líneaallowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=false]/cbc:AllowanceChargeReason
BT-141Importe del cargo de líneaallowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:Amount
BT-143Porcentaje del cargo de líneaallowance_charges_attributes[]{allowance_charge_indicator: "charge", percentage: X}cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:MultiplierFactorNumeric
BT-144Motivo del cargo de líneaallowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}cac:InvoiceLine/cac:AllowanceCharge[cbc:ChargeIndicator=true]/cbc:AllowanceChargeReason
BT-128Referencia de orden de compra (línea)invoice_lines_attributes[].ponumbercac:InvoiceLine/cac:DocumentReference/cbc:ID
BT-132Referencia de línea de POinvoice_lines_attributes[].sequence_numbercac:InvoiceLine/cac:OrderLineReference/cbc:LineID