Campos de factura JSON a XML Facturae (3.2.2)

Esta guía mapea los campos de la API de facturas de B2Brouter y los Términos de Negocio (BT) de EN 16931 correspondientes a las rutas XML de Facturae 3.2.2. Para mayor claridad, los XPath se muestran sin prefijos de espacio de nombres.

Mapeo a nivel de cabecera

BT	Término de negocio	Campo API (B2Brouter)	XPath Facturae
BT-1	Número de factura	`invoice.number`	`Invoices/Invoice/InvoiceHeader/InvoiceNumber`
—	Serie de factura	`invoice.series_code`	`Invoices/Invoice/InvoiceHeader/InvoiceSeriesCode`
—	Tipo de documento	(derivado)	`Invoices/Invoice/InvoiceHeader/InvoiceDocumentType`
—	Clase de factura	(derivado)	`Invoices/Invoice/InvoiceHeader/InvoiceClass`
BT-2	Fecha de emisión	`invoice.date`	`Invoices/Invoice/InvoiceIssueData/IssueDate`
BT-7	Fecha de operación	`invoice.tax_point_date` (preferido) o `invoice.delivery_date` (alternativo)	`Invoices/Invoice/InvoiceIssueData/OperationDate`
BT-5	Moneda	`invoice.currency`	`Invoices/Invoice/InvoiceIssueData/InvoiceCurrencyCode`
—	Idioma	`invoice.language`	`Invoices/Invoice/InvoiceIssueData/LanguageName`
—	Tipo de cambio	`invoice.exchange_rate`	`Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRate`
—	Fecha del tipo de cambio	`invoice.exchange_date`	`Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRateDate`
BT-22	Nota (cabecera)	`invoice.extra_info`	`Invoices/Invoice/AdditionalData/InvoiceAdditionalInformation`
—	Literales legales	`invoice.legal_literals`	`Invoices/Invoice/LegalLiterals/LegalReference`

Notas:

ExchangeRateDetails solo se emite cuando la moneda de la factura difiere del EUR. Los valores exchange_rate y exchange_date pueden configurarse mediante la API; si no se proporcionan, se derivan de la configuración de la cuenta o del sistema.
Si tanto tax_point_date como delivery_date están presentes, delivery_date se añade a InvoiceAdditionalInformation.
Varios campos se incluyen en InvoiceAdditionalInformation (véase Campos de información adicional).

Pago

BT	Término de negocio	Campo API (B2Brouter)	XPath Facturae
BT-9	Fecha de vencimiento	`invoice.due_date`	`Invoices/Invoice/PaymentDetails/Installment/InstallmentDueDate`
—	Importe del plazo	(calculado)	`.../Installment/InstallmentAmount`
BT-81	Medio de pago	`invoice.payment_method`	`.../Installment/PaymentMeans`
BT-82	Texto del medio de pago	`invoice.payment_method_text`	`.../Installment/CollectionAdditionalInformation`
BT-84	Cuenta bancaria del vendedor (IBAN)	`invoice.bank_account.iban`	`.../Installment/AccountToBeCredited/IBAN`
BT-86	Cuenta bancaria del vendedor (BIC)	`invoice.bank_account.bic`	`.../Installment/AccountToBeCredited/BIC`
BT-84	Cuenta bancaria del vendedor (número, sin IBAN)	`invoice.bank_account.number`	`.../Installment/AccountToBeCredited/AccountNumber`
BT-91	Cuenta bancaria del comprador (IBAN, domiciliación)	`invoice.contact_iban`	`.../Installment/AccountToBeDebited/IBAN`
—	Cuenta bancaria del comprador (número, sin IBAN)	`invoice.contact_bank_account_number`	`.../Installment/AccountToBeDebited/AccountNumber`
—	Cuenta bancaria del comprador (BIC, domiciliación)	`invoice.contact_bic`	`.../Installment/AccountToBeDebited/BIC`
BT-10	Referencia del comprador	`invoice.buyer_reference`	`.../Installment/DebitReconciliationReference`
—	Referencia de reconciliación de pago	`invoice.payment_reconciliation_ref`	`.../Installment/PaymentReconciliationReference`

Notas:

PaymentDetails/Installment solo se emite cuando hay condiciones/términos de pago definidos.

Referencias y períodos

Referencias comerciales a nivel de cabecera (InvoiceIssueData):

BT	Término de negocio	Campo API (B2Brouter)	XPath Facturae
BT-13	Referencia de orden de compra	`invoice.ponumber`	`Invoices/Invoice/InvoiceIssueData/ReceiverTransactionReference`
BT-11	Referencia de archivo	`invoice.file_reference`	`Invoices/Invoice/InvoiceIssueData/FileReference`
—	Referencia de contrato receptor	`invoice.receiver_contract_reference`	`Invoices/Invoice/InvoiceIssueData/ReceiverContractReference`

Período de facturación (cabecera):

BT	Término de negocio	Campo API	XPath Facturae
BT-73	Inicio del período de facturación	`invoice.invoicing_period_start`	`Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/StartDate`
BT-74	Fin del período de facturación	`invoice.invoicing_period_end`	`Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/EndDate`

Facturas rectificativas:

BT	Campo	Campo API	XPath Facturae
—	Método	(derivado de `invoice.amended_number`)	`Invoices/Invoice/InvoiceHeader/Corrective/CorrectionMethod`
—	Descripción del método	(derivado)	`.../Corrective/CorrectionMethodDescription`
—	Código de motivo	`invoice.amend_reason` (por defecto `'16'`)	`.../Corrective/ReasonCode`
—	Descripción del motivo	(derivado de la traducción de `amend_reason`)	`.../Corrective/ReasonDescription`
—	Descripción adicional del motivo	`invoice.extra_info`	`.../Corrective/AdditionalReasonDescription`
BT-25	Número de factura rectificada	`invoice.amended_number`	`.../Corrective/InvoiceNumber` (+ `.../InvoiceSeriesCode` si aplica)
BT-26	Fecha de factura rectificada	`invoice.amended_date`	`.../Corrective/InvoiceIssueDate` (solo 3.2.2)
—	Inicio del período fiscal	`invoice.amended_invoicing_period_start`	`.../Corrective/TaxPeriod/StartDate`
—	Fin del período fiscal	`invoice.amended_invoicing_period_end`	`.../Corrective/TaxPeriod/EndDate`

Notas:

CorrectionMethod se calcula: '03' si amended_number == '?', en caso contrario '02'.

Mapeo de partes (factura emitida)

Si la factura es recibida, intercambia SellerParty y BuyerParty.

Parte vendedora (emisor)

BT	Término de negocio	Campo API	XPath Facturae
BT-27	Nombre del vendedor	`account.name`	`Parties/SellerParty/LegalEntity/CorporateName` (o `Individual/Name` + `FirstSurname`)
BT-31	NIF/IVA del vendedor	`account.tin_value`	`Parties/SellerParty/TaxIdentification/TaxIdentificationNumber`
—	Identificación de parte	`invoice.party_identification`	`Parties/SellerParty/PartyIdentification`
BT-35	Calle del vendedor	`account.address`	`Parties/SellerParty/LegalEntity/AddressInSpain/Address` (o `OverseasAddress/Address`)
BT-38	Código postal del vendedor	`account.postalcode`	`Parties/SellerParty/LegalEntity/AddressInSpain/PostCode`
BT-37	Ciudad del vendedor	`account.city`	`Parties/SellerParty/LegalEntity/AddressInSpain/Town`
BT-39	Provincia del vendedor	`account.province`	`Parties/SellerParty/LegalEntity/AddressInSpain/Province`
BT-40	País del vendedor	`account.country`	`Parties/SellerParty/LegalEntity/AddressInSpain/CountryCode` (ISO3)
BT-43	Email del vendedor	`account.email`	`Parties/SellerParty/LegalEntity/ContactDetails/ElectronicMail`
BT-42	Teléfono del vendedor	`account.phone`	`Parties/SellerParty/LegalEntity/ContactDetails/Telephone`
—	Web del vendedor	`account.website`	`Parties/SellerParty/LegalEntity/ContactDetails/WebAddress`
BT-41	Persona de contacto del vendedor	`account.contact_person`	`Parties/SellerParty/LegalEntity/ContactDetails/ContactPersons`

Parte compradora (receptor)

BT	Término de negocio	Campo API	XPath Facturae
BT-44	Nombre del comprador	`invoice.contact.name`	`Parties/BuyerParty/LegalEntity/CorporateName` (o `Individual/...`)
BT-48	NIF/IVA del comprador	`invoice.contact.tin_value`	`Parties/BuyerParty/TaxIdentification/TaxIdentificationNumber`
BT-50	Calle del comprador	`invoice.contact.address`	`Parties/BuyerParty/LegalEntity/AddressInSpain/Address`
BT-53	Código postal del comprador	`invoice.contact.postalcode`	`Parties/BuyerParty/LegalEntity/AddressInSpain/PostCode`
BT-52	Ciudad del comprador	`invoice.contact.city`	`Parties/BuyerParty/LegalEntity/AddressInSpain/Town`
BT-54	Provincia del comprador	`invoice.contact.province`	`Parties/BuyerParty/LegalEntity/AddressInSpain/Province`
BT-55	País del comprador	`invoice.contact.country`	`Parties/BuyerParty/LegalEntity/AddressInSpain/CountryCode`
BT-58	Email del comprador	`invoice.contact.email`	`Parties/BuyerParty/LegalEntity/ContactDetails/ElectronicMail`
BT-57	Teléfono del comprador	`invoice.contact.phone`	`Parties/BuyerParty/LegalEntity/ContactDetails/Telephone`
BT-56	Persona de contacto del comprador	`invoice.contact.contact_person`	`Parties/BuyerParty/LegalEntity/ContactDetails/ContactPersons`
—	Datos de contacto adicionales	`invoice.contact_additional_details`	`Parties/BuyerParty/LegalEntity/ContactDetails/AdditionalContactDetails`

Notas:

Usa AddressInSpain o OverseasAddress según el país.
PartyIdentification solo se emite cuando el valor es una cadena numérica de hasta 10 dígitos.

Centros administrativos (sector público español)

Para facturar a administraciones públicas españolas (FACe), se pueden configurar centros administrativos con códigos DIR3:

Campo	Campo API	XPath Facturae
Oficina contable	`invoice.oc`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='01']/CentreCode`
Órgano gestor	`invoice.og`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='02']/CentreCode`
Unidad tramitadora	`invoice.ut`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='03']/CentreCode`
Órgano proponente	`invoice.op`	`Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='04']/CentreCode`
ID de ubicación de entrega	`invoice.delivery_location_id`	Se usa como `CentreCode` para el rol 04 cuando `op` no está definido
Nombres centros 1-3	`invoice.cin1_name` … `invoice.cin3_name`	`AdministrativeCentre[RoleTypeCode='01'-'03']/Name`
Nombre centro 4	`invoice.cin4_name`	`AdministrativeCentre[RoleTypeCode='04']/Name`

Notas:

Cada centro administrativo también incluye la dirección y los datos de contacto de la parte compradora.
Los campos de dirección de entrega (delivery_address, delivery_city, delivery_province, delivery_postalcode) rellenan la dirección del centro con RoleTypeCode 04.

Impuestos y totales (cabecera)

BT	Término de negocio	Campo API	XPath Facturae
BT-110	Total IVA (repercutido)	(calculado)	`Invoices/Invoice/InvoiceTotals/TotalTaxOutputs` + detalles en `Invoices/Invoice/TaxesOutputs/Tax`
—	Retenciones (cabecera)	`invoice.amounts_withheld_reason`, `invoice.withheld_percent`	`Invoices/Invoice/InvoiceTotals/AmountsWithheld/(WithholdingReason\|WithholdingRate\|WithholdingAmount)`
—	Importe bruto antes de impuestos	(calculado)	`Invoices/Invoice/InvoiceTotals/TotalGrossAmountBeforeTaxes`
BT-92	Importe del descuento de cabecera	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}`	`Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountAmount`
BT-94	Porcentaje del descuento de cabecera	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}`	`Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountRate`
BT-97	Motivo del descuento de cabecera	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}`	`Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountReason`
BT-99	Importe del cargo de cabecera	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}`	`Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeAmount`
BT-104	Motivo del cargo de cabecera	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}`	`Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeReason`
BT-113	Importe prepagado	`invoice.payments_on_account`	`Invoices/Invoice/InvoiceTotals/PaymentsOnAccount/PaymentOnAccount/PaymentOnAccountAmount`
—	Total factura (a pagar)	(calculado)	`Invoices/Invoice/InvoiceTotals/InvoiceTotal`
—	Saldo pendiente	(calculado)	`Invoices/Invoice/InvoiceTotals/TotalOutstandingAmount`
—	Importe ejecutable	(calculado)	`Invoices/Invoice/InvoiceTotals/TotalExecutableAmount`

Notas:

TaxesOutputs/Tax/TaxTypeCode identifica el tipo de impuesto (p. ej., 01 para IVA).

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)	XPath Facturae
BT-153	Nombre/descripción del artículo	`description`	`Invoices/Invoice/Items/InvoiceLine/ItemDescription`
BT-129	Cantidad facturada	`quantity`	`.../Quantity`
BT-130	Unidad de medida	`unit`	`.../UnitOfMeasure`
BT-146	Precio unitario	`price`	`.../UnitPriceWithoutTax`
BT-131	Importe de extensión de línea	`extension_amount` (o calculado)	`.../GrossAmount` (o `.../TotalCost`)
BT-155	ID artículo del vendedor	`article_code`	`.../ArticleCode` (solo Facturae 3.2)
BT-154	Notas del artículo	`notes`	`.../AdditionalLineItemInformation`
BT-132	Referencia de línea del comprador	`sequence_number`	`.../SequenceNumber`
BT-128	Referencia de transacción del receptor	`ponumber` (alternativo: `invoice.ponumber`)	`.../ReceiverTransactionReference`
—	Referencia de archivo	`file_reference` (alternativo: `invoice.file_reference`)	`.../FileReference`
—	Fecha de archivo	`file_date`	`.../FileDate`
—	Número de albarán	`delivery_note_number` (alternativo: `invoice.delivery_note_number`)	`.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteNumber`
—	Fecha de albarán	`delivery_note_date` (alternativo: `invoice.delivery_note_date`)	`.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteDate`
—	Referencia de contrato del emisor	(de `invoice.contract_number`)	`.../IssuerContractReference`
—	Fecha del contrato del emisor	`invoice.issuer_contract_date`	`.../IssuerContractDate`
—	Referencia de transacción del emisor	`issuer_transaction_reference`	`.../IssuerTransactionReference`
—	Fecha de transacción del emisor	`issuer_transaction_date`	`.../IssuerTransactionDate`
—	Referencia de contrato del receptor	`receiver_contract_reference` (alternativo: `invoice.receiver_contract_reference`)	`.../ReceiverContractReference`
—	Fecha del contrato del receptor	`receiver_contract_date`	`.../ReceiverContractDate`
—	Fecha de transacción del receptor	`receiver_transaction_date`	`.../ReceiverTransactionDate`
BT-134	Inicio del período de facturación de línea	`invoicing_period_start`	`.../LineItemPeriod/StartDate`
BT-135	Fin del período de facturación de línea	`invoicing_period_end`	`.../LineItemPeriod/EndDate`
BT-151	Código de tipo de impuesto (por línea)	`taxes_attributes[].category`	`.../TaxesOutputs/Tax/TaxTypeCode`
BT-152	Porcentaje de impuesto (por línea)	`taxes_attributes[].percent`	`.../TaxesOutputs/Tax/TaxRate`
BT-120	Motivo de exención/no sujeción fiscal	`taxes_attributes[].comment`	`.../SpecialTaxableEvent/SpecialTaxableEventReason`
—	Código de exención/no sujeción fiscal	(derivado: `'02'` si categoría `NS`, en caso contrario `'01'`)	`.../SpecialTaxableEvent/SpecialTaxableEventCode`
BT-136	Importe del descuento de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}`	`.../DiscountsAndRebates/Discount/DiscountAmount`
BT-138	Porcentaje del descuento de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}`	`.../DiscountsAndRebates/Discount/DiscountRate`
BT-139	Motivo del descuento de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}`	`.../DiscountsAndRebates/Discount/DiscountReason`
BT-141	Importe del cargo de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}`	`.../Charges/Charge/ChargeAmount`
BT-144	Motivo del cargo de línea	`allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}`	`.../Charges/Charge/ChargeReason`

Notas:

Varios campos a nivel de línea se incluyen en AdditionalLineItemInformation: article_code2, classification_code, article_code_buyer, contact_reference.

Campos de información adicional

Varios campos que tienen elementos XML dedicados en UBL/CII se empaquetan en InvoiceAdditionalInformation en Facturae. Se añaden a invoice.extra_info:

BT	Campo API	Prefijo en AdditionalInformation
BT-14	`invoice.sales_order_reference`	”Sales order reference:“
BT-15	`invoice.receiving_advice_reference`	”Receiving advice reference:“
BT-20	`invoice.payment_terms`	”Payment terms:“
BT-83	`invoice.remittance_information`	”Remittance information:“
BT-90	`invoice.bank_assigned_creditor_reference`	”Bank assigned creditor reference:“
BT-89	`invoice.mandate_reference_identifier`	”Mandate reference identifier:“
BT-19	`invoice.buyer_accounting_reference`	”Buyer accounting reference:“
BT-72	`invoice.delivery_date` (cuando `tax_point_date` también está presente)	“Delivery date:“

Datos de cesión de factoring

Para el factoring de facturas (cesión de crédito), los siguientes campos rellenan el bloque FactoringAssignmentData:

Campo	Campo API	XPath Facturae
NIF del cesionario	`invoice.fa_taxcode`	`FactoringAssignmentData/Assignee/TaxIdentification/TaxIdentificationNumber`
Nombre del cesionario	`invoice.fa_name`	`FactoringAssignmentData/Assignee/LegalEntity/CorporateName`
Dirección del cesionario	`invoice.fa_address`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Address`
Código postal del cesionario	`invoice.fa_postcode`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/PostCode`
Ciudad del cesionario	`invoice.fa_town`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Town`
Provincia del cesionario	`invoice.fa_province`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Province`
País del cesionario	`invoice.fa_country`	`FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/CountryCode`
Fecha de vencimiento del pago	`invoice.fa_duedate`	`FactoringAssignmentData/PaymentDetails/Installment/InstallmentDueDate`
Importe del pago	`invoice.fa_import`	`FactoringAssignmentData/PaymentDetails/Installment/InstallmentAmount`
Método de pago	`invoice.fa_payment_method`	`FactoringAssignmentData/PaymentDetails/Installment/PaymentMeans`
IBAN del cesionario	`invoice.fa_iban`	`FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/IBAN`
BIC del cesionario	`invoice.fa_bic`	`FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BIC`
Cláusulas de factoring	`invoice.fa_clauses`	`FactoringAssignmentData/FactoringAssignmentClauses`
Información adicional	`invoice.fa_info`	`FactoringAssignmentData/Assignee/LegalEntity/ContactDetails/AdditionalContactDetails`
Código de banco	`invoice.fa_bank_code`	`FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BankCode`