Camps JSON de factura a XML Facturae (3.2.2)

Aquesta guia mapeja els camps de la B2Brouter Invoice API i els corresponents Business Terms (BT) d’EN 16931 a rutes XML de Facturae 3.2.2. Per claredat, els XPath es mostren sense prefixos de namespace.

Mapeig a nivell de capçalera

BT	Business Term	Camp API (B2Brouter)	XPath de Facturae
BT-1	Número de factura	invoice.number	Invoices/Invoice/InvoiceHeader/InvoiceNumber
—	Sèrie de factura	invoice.series_code	Invoices/Invoice/InvoiceHeader/InvoiceSeriesCode
—	Tipus de document	(derivat)	Invoices/Invoice/InvoiceHeader/InvoiceDocumentType
—	Classe de factura	(derivat)	Invoices/Invoice/InvoiceHeader/InvoiceClass
BT-2	Data d’emissió	invoice.date	Invoices/Invoice/InvoiceIssueData/IssueDate
BT-7	Data de l’operació	invoice.tax_point_date (preferent) o invoice.delivery_date (fallback)	Invoices/Invoice/InvoiceIssueData/OperationDate
BT-5	Moneda	invoice.currency	Invoices/Invoice/InvoiceIssueData/InvoiceCurrencyCode
—	Idioma	invoice.language	Invoices/Invoice/InvoiceIssueData/LanguageName
—	Tipus de canvi	invoice.exchange_rate	Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRate
—	Data del tipus de canvi	invoice.exchange_date	Invoices/Invoice/InvoiceIssueData/ExchangeRateDetails/ExchangeRateDate
BT-22	Nota (capçalera)	invoice.extra_info	Invoices/Invoice/AdditionalData/InvoiceAdditionalInformation
—	Literals legals	invoice.legal_literals	Invoices/Invoice/LegalLiterals/LegalReference

Notes:

• ExchangeRateDetails només s’emet quan la moneda de la factura és diferent d’EUR. exchange_rate i exchange_date es poden establir via API; si no es proporcionen, es deriven de la configuració del compte o del sistema.
• Si tant tax_point_date com delivery_date són presents, delivery_date s’afegeix a InvoiceAdditionalInformation.
• Diversos camps s’empaqueten dins de InvoiceAdditionalInformation (vegeu Camps d’informació addicional).

Pagament

BT	Business Term	Camp API (B2Brouter)	XPath de Facturae
BT-9	Data de venciment	invoice.due_date	Invoices/Invoice/PaymentDetails/Installment/InstallmentDueDate
—	Import del venciment	(calculat)	.../Installment/InstallmentAmount
BT-81	Mitjà de pagament	invoice.payment_method	.../Installment/PaymentMeans
BT-82	Text del mitjà de pagament	invoice.payment_method_text	.../Installment/CollectionAdditionalInformation
BT-84	Compte bancari del venedor (IBAN)	invoice.bank_account.iban	.../Installment/AccountToBeCredited/IBAN
BT-86	Compte bancari del venedor (BIC)	invoice.bank_account.bic	.../Installment/AccountToBeCredited/BIC
BT-84	Compte bancari del venedor (número, no IBAN)	invoice.bank_account.number	.../Installment/AccountToBeCredited/AccountNumber
BT-91	Compte bancari del comprador (IBAN, rebut domiciliat)	invoice.contact_iban	.../Installment/AccountToBeDebited/IBAN
—	Compte bancari del comprador (número, no IBAN)	invoice.contact_bank_account_number	.../Installment/AccountToBeDebited/AccountNumber
—	Compte bancari del comprador (BIC, rebut domiciliat)	invoice.contact_bic	.../Installment/AccountToBeDebited/BIC
BT-10	Referència del comprador	invoice.buyer_reference	.../Installment/DebitReconciliationReference
—	Referència de conciliació del pagament	invoice.payment_reconciliation_ref	.../Installment/PaymentReconciliationReference

Notes:

• PaymentDetails/Installment només s’emet quan hi ha informació de pagament o venciment definida.

Referències i períodes

Referències comercials a nivell de capçalera (InvoiceIssueData):

BT	Business Term	Camp API (B2Brouter)	XPath de Facturae
BT-13	Referència de comanda de compra	invoice.ponumber	Invoices/Invoice/InvoiceIssueData/ReceiverTransactionReference
BT-11	Referència de fitxer	invoice.file_reference	Invoices/Invoice/InvoiceIssueData/FileReference
—	Referència de contracte del receptor	invoice.receiver_contract_reference	Invoices/Invoice/InvoiceIssueData/ReceiverContractReference

Període de facturació (capçalera):

BT	Business Term	Camp API	XPath de Facturae
BT-73	Inici del període de facturació	invoice.invoicing_period_start	Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/StartDate
BT-74	Fi del període de facturació	invoice.invoicing_period_end	Invoices/Invoice/InvoiceIssueData/InvoicingPeriod/EndDate

Factures rectificatives:

BT	Camp	Camp API	XPath de Facturae
—	Mètode	(derivat de invoice.amended_number)	Invoices/Invoice/InvoiceHeader/Corrective/CorrectionMethod
—	Descripció del mètode	(derivat)	.../Corrective/CorrectionMethodDescription
—	Codi de motiu	invoice.amend_reason (per defecte '16')	.../Corrective/ReasonCode
—	Descripció del motiu	(derivada de la traducció de amend_reason)	.../Corrective/ReasonDescription
—	Descripció addicional del motiu	invoice.extra_info	.../Corrective/AdditionalReasonDescription
BT-25	Número de factura corregida	invoice.amended_number	.../Corrective/InvoiceNumber (+ .../InvoiceSeriesCode si aplica)
BT-26	Data de la factura corregida	invoice.amended_date	.../Corrective/InvoiceIssueDate (només 3.2.2)
—	Inici del període fiscal	invoice.amended_invoicing_period_start	.../Corrective/TaxPeriod/StartDate
—	Fi del període fiscal	invoice.amended_invoicing_period_end	.../Corrective/TaxPeriod/EndDate

Notes:

• CorrectionMethod es calcula així: '03' si amended_number == '?', altrament '02'.

Mapeig de parts (factura emesa)

Si la factura és rebuda, intercanvia SellerParty i BuyerParty.

Seller Party (emissor)

BT	Business Term	Camp API	XPath de Facturae
BT-27	Nom del venedor	account.name	Parties/SellerParty/LegalEntity/CorporateName (o Individual/Name + FirstSurname)
BT-31	NIF/IVA del venedor	account.tin_value	Parties/SellerParty/TaxIdentification/TaxIdentificationNumber
—	Identificació de part	invoice.party_identification	Parties/SellerParty/PartyIdentification
BT-35	Carrer del venedor	account.address	Parties/SellerParty/LegalEntity/AddressInSpain/Address (o OverseasAddress/Address)
BT-38	Codi postal del venedor	account.postalcode	Parties/SellerParty/LegalEntity/AddressInSpain/PostCode
BT-37	Ciutat del venedor	account.city	Parties/SellerParty/LegalEntity/AddressInSpain/Town
BT-39	Província del venedor	account.province	Parties/SellerParty/LegalEntity/AddressInSpain/Province
BT-40	País del venedor	account.country	Parties/SellerParty/LegalEntity/AddressInSpain/CountryCode (ISO3)
BT-43	Correu del venedor	account.email	Parties/SellerParty/LegalEntity/ContactDetails/ElectronicMail
BT-42	Telèfon del venedor	account.phone	Parties/SellerParty/LegalEntity/ContactDetails/Telephone
—	Web del venedor	account.website	Parties/SellerParty/LegalEntity/ContactDetails/WebAddress
BT-41	Persona de contacte del venedor	account.contact_person	Parties/SellerParty/LegalEntity/ContactDetails/ContactPersons

Buyer Party (receptor)

BT	Business Term	Camp API	XPath de Facturae
BT-44	Nom 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	Carrer del comprador	invoice.contact.address	Parties/BuyerParty/LegalEntity/AddressInSpain/Address
BT-53	Codi postal del comprador	invoice.contact.postalcode	Parties/BuyerParty/LegalEntity/AddressInSpain/PostCode
BT-52	Ciutat del comprador	invoice.contact.city	Parties/BuyerParty/LegalEntity/AddressInSpain/Town
BT-54	Província 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	Correu del comprador	invoice.contact.email	Parties/BuyerParty/LegalEntity/ContactDetails/ElectronicMail
BT-57	Telèfon del comprador	invoice.contact.phone	Parties/BuyerParty/LegalEntity/ContactDetails/Telephone
BT-56	Persona de contacte del comprador	invoice.contact.contact_person	Parties/BuyerParty/LegalEntity/ContactDetails/ContactPersons
—	Dades addicionals de contacte	invoice.contact_additional_details	Parties/BuyerParty/LegalEntity/ContactDetails/AdditionalContactDetails

Notes:

• Utilitza AddressInSpain o OverseasAddress segons el país.
• PartyIdentification només s’emet quan el valor és una cadena numèrica de fins a 10 dígits.

Centres administratius (sector públic espanyol)

Per a facturació a administracions públiques espanyoles (FACe), es poden establir centres administratius amb codis DIR3:

Camp	Camp API	XPath de Facturae
Oficina comptable	invoice.oc	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='01']/CentreCode
Òrgan gestor	invoice.og	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='02']/CentreCode
Unitat tramitadora	invoice.ut	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='03']/CentreCode
Òrgan proponent	invoice.op	Parties/BuyerParty/AdministrativeCentres/AdministrativeCentre[RoleTypeCode='04']/CentreCode
ID d’ubicació de lliurament	invoice.delivery_location_id	S’utilitza com a CentreCode per al rol 04 quan op no està definit
Noms centres 1-3	invoice.cin1_name … invoice.cin3_name	AdministrativeCentre[RoleTypeCode='01'-'03']/Name
Nom centre 4	invoice.cin4_name	AdministrativeCentre[RoleTypeCode='04']/Name

Notes:

• Cada centre administratiu també arrossega l’adreça i dades de contacte de la part compradora.
• Els camps de lliurament (delivery_address, delivery_city, delivery_province, delivery_postalcode) omplen l’adreça del centre amb RoleTypeCode 04.

Impostos i totals (capçalera)

BT	Business Term	Camp API	XPath de Facturae
BT-110	Total IVA (outputs)	(calculat)	Invoices/Invoice/InvoiceTotals/TotalTaxOutputs + detall a Invoices/Invoice/TaxesOutputs/Tax
—	Retencions (capçalera)	invoice.amounts_withheld_reason, invoice.withheld_percent	Invoices/Invoice/InvoiceTotals/AmountsWithheld/(WithholdingReason|WithholdingRate|WithholdingAmount)
—	Import brut abans d’impostos	(calculat)	Invoices/Invoice/InvoiceTotals/TotalGrossAmountBeforeTaxes
BT-92	Import de descompte global	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountAmount
BT-94	Percentatge de descompte global	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountRate
BT-97	Motiu del descompte global	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	Invoices/Invoice/InvoiceTotals/GeneralDiscounts/Discount/DiscountReason
BT-99	Import de recàrrec global	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeAmount
BT-104	Motiu del recàrrec global	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	Invoices/Invoice/InvoiceTotals/GeneralSurcharges/Charge/ChargeReason
BT-113	Import prepagat	invoice.payments_on_account	Invoices/Invoice/InvoiceTotals/PaymentsOnAccount/PaymentOnAccount/PaymentOnAccountAmount
—	Total factura (a pagar)	(calculat)	Invoices/Invoice/InvoiceTotals/InvoiceTotal
—	Import pendent	(calculat)	Invoices/Invoice/InvoiceTotals/TotalOutstandingAmount
—	Import executable	(calculat)	Invoices/Invoice/InvoiceTotals/TotalExecutableAmount

Notes:

• TaxesOutputs/Tax/TaxTypeCode identifica l’impost, per exemple 01 per a IVA.

Mapeig a nivell de línia de factura

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

BT	Business Term	Camp API (línia)	XPath de Facturae
BT-153	Nom/descripció de l’article	description	Invoices/Invoice/Items/InvoiceLine/ItemDescription
BT-129	Quantitat facturada	quantity	.../Quantity
BT-130	Unitat de mesura	unit	.../UnitOfMeasure
BT-146	Preu unitari	price	.../UnitPriceWithoutTax
BT-131	Import total de línia	extension_amount (o calculat)	.../GrossAmount (o .../TotalCost)
BT-155	ID de l’article del venedor	article_code	.../ArticleCode (Facturae 3.2 només)
BT-154	Notes de l’article	notes	.../AdditionalLineItemInformation
BT-132	Referència de línia del comprador	sequence_number	.../SequenceNumber
BT-128	Referència de transacció del receptor	ponumber (fallback: invoice.ponumber)	.../ReceiverTransactionReference
—	Referència de fitxer	file_reference (fallback: invoice.file_reference)	.../FileReference
—	Data de fitxer	file_date	.../FileDate
—	Número d’albarà	delivery_note_number (fallback: invoice.delivery_note_number)	.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteNumber
—	Data d’albarà	delivery_note_date (fallback: invoice.delivery_note_date)	.../DeliveryNotesReferences/DeliveryNote/DeliveryNoteDate
—	Referència de contracte de l’emissor	(des de invoice.contract_number)	.../IssuerContractReference
—	Data de contracte de l’emissor	invoice.issuer_contract_date	.../IssuerContractDate
—	Referència de transacció de l’emissor	issuer_transaction_reference	.../IssuerTransactionReference
—	Data de transacció de l’emissor	issuer_transaction_date	.../IssuerTransactionDate
—	Referència de contracte del receptor	receiver_contract_reference (fallback: invoice.receiver_contract_reference)	.../ReceiverContractReference
—	Data de contracte del receptor	receiver_contract_date	.../ReceiverContractDate
—	Data de transacció del receptor	receiver_transaction_date	.../ReceiverTransactionDate
BT-134	Inici del període de línia	invoicing_period_start	.../LineItemPeriod/StartDate
BT-135	Fi del període de línia	invoicing_period_end	.../LineItemPeriod/EndDate
BT-151	Codi del tipus d’impost (per línia)	taxes_attributes[].category	.../TaxesOutputs/Tax/TaxTypeCode
BT-152	Percentatge d’impost (per línia)	taxes_attributes[].percent	.../TaxesOutputs/Tax/TaxRate
BT-120	Motiu d’exempció/no subjecció	taxes_attributes[].comment	.../SpecialTaxableEvent/SpecialTaxableEventReason
—	Codi d’exempció/no subjecció	(derivat: '02' si la categoria és NS, altrament '01')	.../SpecialTaxableEvent/SpecialTaxableEventCode
BT-136	Import de descompte de línia	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", amount: X}	.../DiscountsAndRebates/Discount/DiscountAmount
BT-138	Percentatge de descompte de línia	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", percentage: X}	.../DiscountsAndRebates/Discount/DiscountRate
BT-139	Motiu del descompte de línia	allowance_charges_attributes[]{allowance_charge_indicator: "allowance", description: "..."}	.../DiscountsAndRebates/Discount/DiscountReason
BT-141	Import de recàrrec de línia	allowance_charges_attributes[]{allowance_charge_indicator: "charge", amount: X}	.../Charges/Charge/ChargeAmount
BT-144	Motiu del recàrrec de línia	allowance_charges_attributes[]{allowance_charge_indicator: "charge", description: "..."}	.../Charges/Charge/ChargeReason

Notes:

• Diversos camps a nivell de línia s’empaqueten dins de AdditionalLineItemInformation: article_code2, classification_code, article_code_buyer, contact_reference.

Camps d’informació addicional

Diversos camps que tenen elements XML dedicats a UBL/CII s’empaqueten dins de InvoiceAdditionalInformation a Facturae. Aquests valors s’afegeixen a invoice.extra_info:

BT	Camp API	Prefix a 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 (quan tax_point_date també és present)	“Delivery date:“

Dades de cessió de crèdit (factoring)

Per a factoring de factures (cessió de crèdit), els camps següents omplen el bloc FactoringAssignmentData:

Camp	Camp API	XPath de Facturae
NIF de l’assignee	invoice.fa_taxcode	FactoringAssignmentData/Assignee/TaxIdentification/TaxIdentificationNumber
Nom de l’assignee	invoice.fa_name	FactoringAssignmentData/Assignee/LegalEntity/CorporateName
Adreça de l’assignee	invoice.fa_address	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Address
Codi postal de l’assignee	invoice.fa_postcode	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/PostCode
Ciutat de l’assignee	invoice.fa_town	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Town
Província de l’assignee	invoice.fa_province	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/Province
País de l’assignee	invoice.fa_country	FactoringAssignmentData/Assignee/LegalEntity/AddressInSpain/CountryCode
Data de venciment del pagament	invoice.fa_duedate	FactoringAssignmentData/PaymentDetails/Installment/InstallmentDueDate
Import del pagament	invoice.fa_import	FactoringAssignmentData/PaymentDetails/Installment/InstallmentAmount
Mètode de pagament	invoice.fa_payment_method	FactoringAssignmentData/PaymentDetails/Installment/PaymentMeans
IBAN de l’assignee	invoice.fa_iban	FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/IBAN
BIC de l’assignee	invoice.fa_bic	FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BIC
Clàusules de factoring	invoice.fa_clauses	FactoringAssignmentData/FactoringAssignmentClauses
Informació addicional	invoice.fa_info	FactoringAssignmentData/Assignee/LegalEntity/ContactDetails/AdditionalContactDetails
Codi de banc	invoice.fa_bank_code	FactoringAssignmentData/PaymentDetails/Installment/AccountToBeCredited/BankCode