@financica/ubl 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/normalize.ts CHANGED
@@ -110,9 +110,9 @@ const sanitizeAllowanceCharges = (charges?: UblAllowanceCharge[]) =>
110
110
  multiplier_factor_numeric: toNumberOrNull(charge.multiplierFactorNumeric),
111
111
  reason: normalizeText(charge.reason),
112
112
  reason_code: normalizeText(charge.reasonCode),
113
- tax_percent: toNumberOrNull(charge.taxPercent),
114
- tax_category_id: normalizeText(charge.taxCategoryId),
115
- tax_scheme_id: normalizeText(charge.taxSchemeId),
113
+ tax_percent: toNumberOrNull(charge.taxCategory?.percent),
114
+ tax_category_id: normalizeText(charge.taxCategory?.id),
115
+ tax_scheme_id: normalizeText(charge.taxCategory?.schemeId),
116
116
  }));
117
117
 
118
118
  const sanitizeRawUbl = (ubl: UblInvoice) => ({
@@ -124,11 +124,12 @@ const sanitizeRawUbl = (ubl: UblInvoice) => ({
124
124
  // --- Summation helpers ---
125
125
 
126
126
  const sumTaxTotal = (ubl: UblInvoice): number | null => {
127
- const subtotalSum = ubl.taxSubtotals.reduce(
127
+ const { subtotals } = ubl.taxTotal;
128
+ const subtotalSum = subtotals.reduce(
128
129
  (sum, subtotal) => sum + (subtotal.taxAmount ?? 0),
129
130
  0,
130
131
  );
131
- if (ubl.taxSubtotals.length > 0 && Number.isFinite(subtotalSum)) {
132
+ if (subtotals.length > 0 && Number.isFinite(subtotalSum)) {
132
133
  return subtotalSum;
133
134
  }
134
135
  const { taxInclusiveAmount, taxExclusiveAmount } = ubl.monetaryTotal;
@@ -217,7 +218,7 @@ export const normalizeUblResponse = (
217
218
  unit_price: toNumberOrNull(line.unitPrice),
218
219
  amount: toNumberOrNull(line.lineExtensionAmount),
219
220
  tax_amount: toNumberOrNull(line.taxAmount),
220
- tax_rate: toNumberOrNull(line.taxPercent),
221
+ tax_rate: toNumberOrNull(line.taxCategory?.percent),
221
222
  product_code:
222
223
  normalizeText(line.sellersItemId) ?? normalizeText(line.buyersItemId),
223
224
  discount_amount: toNumberOrNull(line.discountAmount),
@@ -228,8 +229,8 @@ export const normalizeUblResponse = (
228
229
  item_name: normalizeText(line.itemName),
229
230
  sellers_item_id: normalizeText(line.sellersItemId),
230
231
  buyers_item_id: normalizeText(line.buyersItemId),
231
- tax_category_id: normalizeText(line.taxCategoryId),
232
- tax_scheme_id: normalizeText(line.taxSchemeId),
232
+ tax_category_id: normalizeText(line.taxCategory?.id),
233
+ tax_scheme_id: normalizeText(line.taxCategory?.schemeId),
233
234
  tax_subtotals: line.taxSubtotals ?? [],
234
235
  allowance_charges: sanitizeAllowanceCharges(line.allowanceCharges),
235
236
  charge_amount: toNumberOrNull(line.chargeAmount),
@@ -286,7 +287,7 @@ export const normalizeUblResponse = (
286
287
  address: supplierAddress,
287
288
  tax_id:
288
289
  normalizeText(ubl.seller.vatId) ??
289
- normalizeText(ubl.seller.companyId),
290
+ normalizeText(ubl.seller.companyId?.value),
290
291
  iban: normalizeText(ubl.paymentMeans?.iban),
291
292
  bic: normalizeText(ubl.paymentMeans?.bic),
292
293
  },
@@ -297,7 +298,7 @@ export const normalizeUblResponse = (
297
298
  address: receiverAddress,
298
299
  tax_id:
299
300
  normalizeText(ubl.buyer.vatId) ??
300
- normalizeText(ubl.buyer.companyId),
301
+ normalizeText(ubl.buyer.companyId?.value),
301
302
  },
302
303
  extra: {
303
304
  document_type: ubl.documentType,
@@ -333,11 +334,11 @@ export const normalizeUblResponse = (
333
334
  }
334
335
  : null,
335
336
  supplier: {
336
- endpoint_id: normalizeText(ubl.seller.endpointId),
337
- endpoint_scheme_id: normalizeText(ubl.seller.endpointSchemeId),
337
+ endpoint_id: normalizeText(ubl.seller.endpoint?.value),
338
+ endpoint_scheme_id: normalizeText(ubl.seller.endpoint?.scheme),
338
339
  registration_name: normalizeText(ubl.seller.registrationName),
339
340
  company_legal_form: normalizeText(ubl.seller.companyLegalForm),
340
- company_id_scheme_id: normalizeText(ubl.seller.companyIdSchemeId),
341
+ company_id_scheme_id: normalizeText(ubl.seller.companyId?.scheme),
341
342
  tax_scheme_id: normalizeText(ubl.seller.taxSchemeId),
342
343
  party_identifications: ubl.seller.partyIdentifications ?? [],
343
344
  contact_name: normalizeText(ubl.seller.contact?.name),
@@ -345,11 +346,11 @@ export const normalizeUblResponse = (
345
346
  contact_email: normalizeText(ubl.seller.contact?.email),
346
347
  },
347
348
  receiver: {
348
- endpoint_id: normalizeText(ubl.buyer.endpointId),
349
- endpoint_scheme_id: normalizeText(ubl.buyer.endpointSchemeId),
349
+ endpoint_id: normalizeText(ubl.buyer.endpoint?.value),
350
+ endpoint_scheme_id: normalizeText(ubl.buyer.endpoint?.scheme),
350
351
  registration_name: normalizeText(ubl.buyer.registrationName),
351
352
  company_legal_form: normalizeText(ubl.buyer.companyLegalForm),
352
- company_id_scheme_id: normalizeText(ubl.buyer.companyIdSchemeId),
353
+ company_id_scheme_id: normalizeText(ubl.buyer.companyId?.scheme),
353
354
  tax_scheme_id: normalizeText(ubl.buyer.taxSchemeId),
354
355
  party_identifications: ubl.buyer.partyIdentifications ?? [],
355
356
  contact_name: normalizeText(ubl.buyer.contact?.name),
@@ -358,7 +359,7 @@ export const normalizeUblResponse = (
358
359
  },
359
360
  supplier_address_structured: supplierAddressStructured,
360
361
  receiver_address_structured: receiverAddressStructured,
361
- tax_subtotals: ubl.taxSubtotals,
362
+ tax_subtotals: ubl.taxTotal.subtotals,
362
363
  allowance_charges: sanitizeAllowanceCharges(ubl.allowanceCharges),
363
364
  attachments: attachmentMetadata,
364
365
  document_references: ubl.documentReferences ?? [],
package/src/parser.ts CHANGED
@@ -15,7 +15,9 @@ import type {
15
15
  UblParty,
16
16
  UblPartyIdentification,
17
17
  UblPaymentMeans,
18
+ UblTaxCategory,
18
19
  UblTaxSubtotal,
20
+ UblTaxTotal,
19
21
  } from "./types.js";
20
22
  import { UblParseError } from "./errors.js";
21
23
  import { CAC_NS, CBC_NS, parseXmlDocument } from "./xml-dom.js";
@@ -163,6 +165,13 @@ function parseParty(root: Element, role: string): UblParty {
163
165
  ? legalEntity.getElementsByTagNameNS(CBC_NS, "CompanyID")[0]
164
166
  : null;
165
167
 
168
+ const endpointValue = trimmed(endpointEl?.textContent);
169
+ const companyIdValue = companyIdEl
170
+ ? trimmed(companyIdEl.textContent)
171
+ : partyId
172
+ ? cbcText(partyId, "ID")
173
+ : undefined;
174
+
166
175
  return {
167
176
  name: partyName ? cbcText(partyName, "Name") : undefined,
168
177
  registrationName: legalEntity
@@ -173,14 +182,14 @@ function parseParty(root: Element, role: string): UblParty {
173
182
  : undefined,
174
183
  vatId: taxScheme ? cbcText(taxScheme, "CompanyID") : undefined,
175
184
  taxSchemeId: parseTaxSchemeId(taxScheme),
176
- companyId: companyIdEl
177
- ? trimmed(companyIdEl.textContent)
178
- : partyId
179
- ? cbcText(partyId, "ID")
185
+ companyId:
186
+ companyIdValue !== undefined
187
+ ? { value: companyIdValue, scheme: attribute(companyIdEl, "schemeID") }
188
+ : undefined,
189
+ endpoint:
190
+ endpointValue !== undefined
191
+ ? { value: endpointValue, scheme: attribute(endpointEl, "schemeID") }
180
192
  : undefined,
181
- companyIdSchemeId: attribute(companyIdEl, "schemeID"),
182
- endpointId: trimmed(endpointEl?.textContent),
183
- endpointSchemeId: attribute(endpointEl, "schemeID"),
184
193
  partyIdentifications:
185
194
  partyIdentifications.length > 0 ? partyIdentifications : undefined,
186
195
  address: parseAddress(party),
@@ -188,16 +197,40 @@ function parseParty(root: Element, role: string): UblParty {
188
197
  };
189
198
  }
190
199
 
200
+ /**
201
+ * `cac:TaxCategory` / `cac:ClassifiedTaxCategory`. Emitted whenever the
202
+ * element states anything; `percentFallback` covers the E-FFF habit of putting
203
+ * `cbc:Percent` on the subtotal instead of inside the category.
204
+ */
205
+ function parseTaxCategory(
206
+ cat: Element | null,
207
+ percentFallback?: Element,
208
+ ): UblTaxCategory | undefined {
209
+ const percentFromParent = percentFallback
210
+ ? cbcDirectNumber(percentFallback, "Percent")
211
+ : undefined;
212
+ if (!cat) {
213
+ return percentFromParent !== undefined
214
+ ? { percent: percentFromParent }
215
+ : undefined;
216
+ }
217
+ const category: UblTaxCategory = {
218
+ id: cbcText(cat, "ID"),
219
+ percent: cbcNumber(cat, "Percent") ?? percentFromParent,
220
+ schemeId: parseTaxSchemeId(cat),
221
+ exemptionReason: cbcText(cat, "TaxExemptionReason"),
222
+ exemptionReasonCode: cbcText(cat, "TaxExemptionReasonCode"),
223
+ };
224
+ return Object.values(category).some((value) => value !== undefined)
225
+ ? category
226
+ : undefined;
227
+ }
228
+
191
229
  function parseTaxSubtotal(sub: Element): UblTaxSubtotal {
192
- const cat = cacElement(sub, "TaxCategory");
193
230
  return {
194
231
  taxableAmount: cbcNumber(sub, "TaxableAmount"),
195
232
  taxAmount: cbcNumber(sub, "TaxAmount"),
196
- taxPercent:
197
- (cat ? cbcNumber(cat, "Percent") : undefined) ?? cbcNumber(sub, "Percent"),
198
- taxCategoryId: cat ? cbcText(cat, "ID") : undefined,
199
- taxSchemeId: parseTaxSchemeId(cat),
200
- taxExemptionReason: cat ? cbcText(cat, "TaxExemptionReason") : undefined,
233
+ category: parseTaxCategory(cacElement(sub, "TaxCategory"), sub),
201
234
  };
202
235
  }
203
236
 
@@ -205,10 +238,18 @@ function parseTaxSubtotalsFromTaxTotal(taxTotal: Element): UblTaxSubtotal[] {
205
238
  return cacDirectElements(taxTotal, "TaxSubtotal").map(parseTaxSubtotal);
206
239
  }
207
240
 
208
- function parseTaxSubtotals(root: Element): UblTaxSubtotal[] {
241
+ /**
242
+ * `cac:TaxTotal` (BG-22). BT-110 is read from the first `cac:TaxTotal` as
243
+ * stated, never summed from the subtotals; the subtotals of every `TaxTotal`
244
+ * (a second one carries the accounting-currency figure) are concatenated.
245
+ */
246
+ function parseTaxTotal(root: Element): UblTaxTotal {
209
247
  const taxTotals = cacDirectElements(root, "TaxTotal");
210
- if (taxTotals.length === 0) return [];
211
- return taxTotals.flatMap(parseTaxSubtotalsFromTaxTotal);
248
+ const first = taxTotals[0];
249
+ return {
250
+ taxAmount: first ? cbcDirectNumber(first, "TaxAmount") : undefined,
251
+ subtotals: taxTotals.flatMap(parseTaxSubtotalsFromTaxTotal),
252
+ };
212
253
  }
213
254
 
214
255
  function parseAllowanceCharge(charge: Element): UblAllowanceCharge {
@@ -222,9 +263,7 @@ function parseAllowanceCharge(charge: Element): UblAllowanceCharge {
222
263
  multiplierFactorNumeric: cbcDirectNumber(charge, "MultiplierFactorNumeric"),
223
264
  reason: cbcText(charge, "AllowanceChargeReason"),
224
265
  reasonCode: cbcText(charge, "AllowanceChargeReasonCode"),
225
- taxPercent: taxCategory ? cbcNumber(taxCategory, "Percent") : undefined,
226
- taxCategoryId: taxCategory ? cbcText(taxCategory, "ID") : undefined,
227
- taxSchemeId: parseTaxSchemeId(taxCategory),
266
+ taxCategory: parseTaxCategory(taxCategory),
228
267
  };
229
268
  }
230
269
 
@@ -232,6 +271,22 @@ function parseAllowanceCharges(parent: Element): UblAllowanceCharge[] {
232
271
  return cacDirectElements(parent, "AllowanceCharge").map(parseAllowanceCharge);
233
272
  }
234
273
 
274
+ function mergeTaxCategories(
275
+ preferred: UblTaxCategory | undefined,
276
+ fallback: UblTaxCategory | undefined,
277
+ ): UblTaxCategory | undefined {
278
+ if (!preferred) return fallback;
279
+ if (!fallback) return preferred;
280
+ return {
281
+ id: preferred.id ?? fallback.id,
282
+ percent: preferred.percent ?? fallback.percent,
283
+ schemeId: preferred.schemeId ?? fallback.schemeId,
284
+ exemptionReason: preferred.exemptionReason ?? fallback.exemptionReason,
285
+ exemptionReasonCode:
286
+ preferred.exemptionReasonCode ?? fallback.exemptionReasonCode,
287
+ };
288
+ }
289
+
235
290
  function parseLines(root: Element, isCreditNote: boolean): UblLine[] {
236
291
  const qtyTag = isCreditNote ? "CreditedQuantity" : "InvoicedQuantity";
237
292
  const lineTag = isCreditNote ? "CreditNoteLine" : "InvoiceLine";
@@ -239,7 +294,9 @@ function parseLines(root: Element, isCreditNote: boolean): UblLine[] {
239
294
  return cacElements(root, lineTag).map((line) => {
240
295
  const item = cacElement(line, "Item");
241
296
  const price = cacElement(line, "Price");
242
- const taxCategory = item ? cacElement(item, "ClassifiedTaxCategory") : null;
297
+ const classifiedCategory = parseTaxCategory(
298
+ item ? cacElement(item, "ClassifiedTaxCategory") : null,
299
+ );
243
300
  const sellersId = item ? cacElement(item, "SellersItemIdentification") : null;
244
301
  const buyersId = item ? cacElement(item, "BuyersItemIdentification") : null;
245
302
  const qtyEl = line.getElementsByTagNameNS(CBC_NS, qtyTag)[0];
@@ -255,9 +312,11 @@ function parseLines(root: Element, isCreditNote: boolean): UblLine[] {
255
312
  const taxAmountFromLineTotal = lineTaxTotal
256
313
  ? cbcDirectNumber(lineTaxTotal, "TaxAmount")
257
314
  : undefined;
258
- const taxPercent =
259
- lineTaxSubtotals[0]?.taxPercent ??
260
- (taxCategory ? cbcNumber(taxCategory, "Percent") : undefined);
315
+ // A line-level TaxSubtotal (E-FFF) wins over the classified category,
316
+ // field by field.
317
+ const subtotalCategory = lineTaxSubtotals[0]?.category;
318
+ const taxCategory = mergeTaxCategories(subtotalCategory, classifiedCategory);
319
+ const taxPercent = taxCategory?.percent;
261
320
  const computedTaxAmount =
262
321
  taxPercent !== undefined && lineExtensionAmount !== undefined
263
322
  ? Number(((lineExtensionAmount * taxPercent) / 100).toFixed(2))
@@ -309,17 +368,13 @@ function parseLines(root: Element, isCreditNote: boolean): UblLine[] {
309
368
  unitCode: attribute(qtyEl, "unitCode"),
310
369
  unitPrice,
311
370
  lineExtensionAmount,
312
- taxPercent,
371
+ baseQuantity: priceBaseQuantity,
372
+ taxCategory,
313
373
  taxAmount:
314
374
  taxAmountFromLineTotal ??
315
375
  (lineTaxSubtotals.length > 0
316
376
  ? taxAmountFromSubtotals
317
377
  : computedTaxAmount),
318
- taxCategoryId:
319
- lineTaxSubtotals[0]?.taxCategoryId ??
320
- (taxCategory ? cbcText(taxCategory, "ID") : undefined),
321
- taxSchemeId:
322
- lineTaxSubtotals[0]?.taxSchemeId ?? parseTaxSchemeId(taxCategory),
323
378
  taxSubtotals: lineTaxSubtotals.length > 0 ? lineTaxSubtotals : undefined,
324
379
  allowanceCharges:
325
380
  allowanceCharges.length > 0 ? allowanceCharges : undefined,
@@ -582,7 +637,7 @@ export function parseUblInvoice(xml: string): UblInvoice | null {
582
637
  buyer: parseParty(root, "AccountingCustomerParty"),
583
638
  delivery: parseDelivery(root),
584
639
  lines: parseLines(root, isCreditNote),
585
- taxSubtotals: parseTaxSubtotals(root),
640
+ taxTotal: parseTaxTotal(root),
586
641
  monetaryTotal: parseMonetaryTotal(root),
587
642
  paymentMeansList,
588
643
  paymentMeans: paymentMeansList?.[0],
package/src/types.ts CHANGED
@@ -1,142 +1,287 @@
1
- // --- UBL parsed types ---
1
+ // --- UBL document model ---
2
2
  //
3
- // Parse-side model. A field the document may omit is an optional key: the
4
- // parser never writes `""`/`0` to fill a gap. Fields EN 16931 makes mandatory
5
- // (document id, issue date, currency, line id) stay required; a document that
6
- // lacks one is rejected with `UblParseError`. Containers the consumer iterates
7
- // (`lines`, `taxSubtotals`) and the `seller`/`buyer`/`monetaryTotal` objects
8
- // are always present.
3
+ // One model, used by the parser, the serializer and the build helpers. It is a
4
+ // vendor-neutral mirror of the UBL 2.1 / Peppol BIS Billing 3.0 fields this
5
+ // package reads and writes, not a full UBL object graph.
6
+ //
7
+ // The parser reads everything the document states: a field the document omits
8
+ // is an absent key (never `""`/`0`/`"S"` to fill a gap). Only the fields
9
+ // EN 16931 makes mandatory for *parsing* (document id, issue date, currency,
10
+ // line id) are required on the type; a document that lacks one is rejected
11
+ // with `UblParseError`. Containers the consumer iterates (`lines`,
12
+ // `taxTotal.subtotals`) and the `seller`/`buyer`/`taxTotal`/`monetaryTotal`
13
+ // objects are always present.
14
+ //
15
+ // The serializer is the validator: `serializeUblInvoice` throws `UblBuildError`
16
+ // when a field EN 16931 / Peppol BIS makes mandatory on the wire is missing.
9
17
 
10
18
  export interface UblAddress {
19
+ /** `cbc:StreetName` (BT-35). */
11
20
  street?: string | undefined;
21
+ /** `cbc:AdditionalStreetName` (BT-36). */
12
22
  additionalStreet?: string | undefined;
23
+ /** `cbc:CityName` (BT-37). */
13
24
  city?: string | undefined;
25
+ /** `cbc:PostalZone` (BT-38). */
14
26
  postalZone?: string | undefined;
27
+ /** `cbc:CountrySubentity` (BT-39). */
15
28
  countrySubentity?: string | undefined;
29
+ /** `cac:Country/cbc:IdentificationCode` (BT-40) — ISO 3166-1 alpha-2. */
16
30
  countryCode?: string | undefined;
17
31
  }
18
32
 
19
33
  export interface UblContact {
34
+ /** `cac:Contact/cbc:Name` (BT-41/BT-56). */
20
35
  name?: string | undefined;
36
+ /** `cac:Contact/cbc:Telephone` (BT-42/BT-57). */
21
37
  phone?: string | undefined;
38
+ /** `cac:Contact/cbc:ElectronicMail` (BT-43/BT-58). */
22
39
  email?: string | undefined;
23
40
  }
24
41
 
42
+ /**
43
+ * Peppol participant identifier (`cbc:EndpointID` + `@schemeID`), e.g. scheme
44
+ * `0208`, value `0800279001`. A document may state the value without a scheme;
45
+ * the serializer requires both.
46
+ */
47
+ export interface UblEndpoint {
48
+ value: string;
49
+ /** EAS scheme (`@schemeID`), e.g. `0208`. */
50
+ scheme?: string | undefined;
51
+ }
52
+
53
+ /**
54
+ * Legal registration identifier (`cac:PartyLegalEntity/cbc:CompanyID` +
55
+ * `@schemeID`), e.g. a Belgian enterprise number.
56
+ */
57
+ export interface UblCompanyId {
58
+ value: string;
59
+ /** ISO 6523 ICD scheme (`@schemeID`, e.g. `0208` for the Belgian CBE), when known. */
60
+ scheme?: string | undefined;
61
+ }
62
+
63
+ /** `cac:PartyIdentification/cbc:ID` (BT-29/BT-46) with its `@schemeID`. */
25
64
  export interface UblPartyIdentification {
26
65
  id: string;
27
66
  schemeId?: string | undefined;
28
67
  }
29
68
 
30
69
  export interface UblParty {
70
+ /** `cac:PartyName/cbc:Name` (BT-28/BT-45). */
31
71
  name?: string | undefined;
72
+ /** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). */
32
73
  registrationName?: string | undefined;
74
+ /** `cac:PartyLegalEntity/cbc:CompanyLegalForm` (BT-33). */
33
75
  companyLegalForm?: string | undefined;
76
+ /** `cac:PartyTaxScheme/cbc:CompanyID` (BT-31/BT-48) — the VAT identifier. */
34
77
  vatId?: string | undefined;
78
+ /** `cac:PartyTaxScheme/cac:TaxScheme/cbc:ID`, normally `VAT`. */
35
79
  taxSchemeId?: string | undefined;
36
- companyId?: string | undefined;
37
- companyIdSchemeId?: string | undefined;
38
- endpointId?: string | undefined;
39
- endpointSchemeId?: string | undefined;
80
+ /** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
81
+ companyId?: UblCompanyId | undefined;
82
+ /** `cbc:EndpointID` (BT-34/BT-49) — the Peppol routing identifier. */
83
+ endpoint?: UblEndpoint | undefined;
40
84
  partyIdentifications?: UblPartyIdentification[] | undefined;
41
85
  address?: UblAddress | undefined;
42
86
  contact?: UblContact | undefined;
43
87
  }
44
88
 
89
+ /**
90
+ * VAT category (`cac:ClassifiedTaxCategory` on a line, `cac:TaxCategory` in
91
+ * the VAT breakdown and on an allowance/charge). `id` is a UNCL5305 code:
92
+ * - `S` Standard rate
93
+ * - `Z` Zero-rated goods
94
+ * - `E` Exempt from VAT
95
+ * - `AE` VAT reverse charge
96
+ * - `O` Services outside scope of tax
97
+ * - `K` Intra-community supply
98
+ * - `G` Export outside the EU
99
+ */
100
+ export interface UblTaxCategory {
101
+ /** `cbc:ID` (BT-151/BT-118/BT-95/BT-102). */
102
+ id?: string | undefined;
103
+ /** `cbc:Percent` (BT-152/BT-119/BT-96/BT-103); absent for `O` and when the document omits it. */
104
+ percent?: number | undefined;
105
+ /** `cac:TaxScheme/cbc:ID`, normally `VAT`. */
106
+ schemeId?: string | undefined;
107
+ /** `cbc:TaxExemptionReason` (BT-120). Required by EN 16931 for non-charging categories. */
108
+ exemptionReason?: string | undefined;
109
+ /** `cbc:TaxExemptionReasonCode` (BT-121). */
110
+ exemptionReasonCode?: string | undefined;
111
+ }
112
+
45
113
  export interface UblItemProperty {
114
+ /** `cac:AdditionalItemProperty/cbc:Name` (BT-160). */
46
115
  name: string;
116
+ /** `cac:AdditionalItemProperty/cbc:Value` (BT-161). */
47
117
  value?: string | undefined;
48
118
  }
49
119
 
50
120
  export interface UblLine {
121
+ /** `cbc:ID` (BT-126) — line identifier. */
51
122
  id: string;
123
+ /** `cac:Item/cbc:Description` (BT-154). */
52
124
  description?: string | undefined;
125
+ /** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
53
126
  quantity?: number | undefined;
127
+ /** UN/ECE Rec 20 unit code (BT-130). */
54
128
  unitCode?: string | undefined;
129
+ /**
130
+ * Net price of one unit: `cac:Price/cbc:PriceAmount` (BT-146) divided by
131
+ * `cbc:BaseQuantity` (BT-149, default 1).
132
+ */
55
133
  unitPrice?: number | undefined;
134
+ /** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
56
135
  lineExtensionAmount?: number | undefined;
57
- taxPercent?: number | undefined;
136
+ /**
137
+ * `cac:Price/cbc:BaseQuantity` (BT-149) — the number of units BT-146
138
+ * covers. Omitted means 1. Set it when the net doesn't divide evenly into
139
+ * cents, so `quantity × unitPrice` reproduces the line net exactly
140
+ * (PEPPOL-EN16931-R120); see `deriveUnitPrice`. The serializer emits
141
+ * `PriceAmount = unitPrice × baseQuantity`.
142
+ */
143
+ baseQuantity?: number | undefined;
144
+ /** `cac:Item/cac:ClassifiedTaxCategory` (BT-151/BT-152). */
145
+ taxCategory?: UblTaxCategory | undefined;
146
+ /** Line VAT amount: `cac:TaxTotal/cbc:TaxAmount` when stated, else derived from the rate. */
58
147
  taxAmount?: number | undefined;
59
- taxCategoryId?: string | undefined;
60
- taxSchemeId?: string | undefined;
148
+ /** Line-level `cac:TaxTotal/cac:TaxSubtotal` (not used by BIS Billing, seen in the wild). */
61
149
  taxSubtotals?: UblTaxSubtotal[] | undefined;
62
150
  allowanceCharges?: UblAllowanceCharge[] | undefined;
151
+ /** Sum of line-level allowances (absolute). */
63
152
  discountAmount?: number | undefined;
153
+ /** Sum of line-level charges (absolute). */
64
154
  chargeAmount?: number | undefined;
155
+ /** `cac:Item/cbc:Name` (BT-153). */
65
156
  itemName?: string | undefined;
157
+ /** `cac:Item/cac:SellersItemIdentification/cbc:ID` (BT-155). */
66
158
  sellersItemId?: string | undefined;
159
+ /** `cac:Item/cac:BuyersItemIdentification/cbc:ID` (BT-156). */
67
160
  buyersItemId?: string | undefined;
68
161
  additionalItemProperties?: UblItemProperty[] | undefined;
69
- /** EN 16931 BT-134/BT-135: the line's own service period. */
162
+ /** `cac:InvoicePeriod` (BT-134/BT-135) — the line's own service period. */
70
163
  invoicePeriod?: UblInvoicePeriod | undefined;
71
164
  }
72
165
 
73
166
  export interface UblAllowanceCharge {
167
+ /** `cbc:ChargeIndicator` — `true` for a charge, `false` for an allowance. */
74
168
  chargeIndicator: boolean;
169
+ /** `cbc:Amount` (BT-92/BT-99). */
75
170
  amount?: number | undefined;
171
+ /** `cbc:BaseAmount` (BT-93/BT-100). */
76
172
  baseAmount?: number | undefined;
173
+ /** `cbc:MultiplierFactorNumeric` (BT-94/BT-101). */
77
174
  multiplierFactorNumeric?: number | undefined;
175
+ /** `cbc:AllowanceChargeReason` (BT-97/BT-104). */
78
176
  reason?: string | undefined;
177
+ /** `cbc:AllowanceChargeReasonCode` (BT-98/BT-105). */
79
178
  reasonCode?: string | undefined;
80
- taxPercent?: number | undefined;
81
- taxCategoryId?: string | undefined;
82
- taxSchemeId?: string | undefined;
179
+ /** `cac:TaxCategory` (BT-95/BT-96, BT-102/BT-103). */
180
+ taxCategory?: UblTaxCategory | undefined;
83
181
  }
84
182
 
85
183
  export interface UblTaxSubtotal {
184
+ /** `cbc:TaxableAmount` (BT-116). */
86
185
  taxableAmount?: number | undefined;
186
+ /** `cbc:TaxAmount` (BT-117). */
87
187
  taxAmount?: number | undefined;
88
- taxPercent?: number | undefined;
89
- taxCategoryId?: string | undefined;
90
- taxSchemeId?: string | undefined;
91
- taxExemptionReason?: string | undefined;
188
+ /** `cac:TaxCategory` (BT-118/BT-119/BT-120/BT-121). */
189
+ category?: UblTaxCategory | undefined;
190
+ }
191
+
192
+ export interface UblTaxTotal {
193
+ /** `cac:TaxTotal/cbc:TaxAmount` (BT-110). Read as stated; never summed from the subtotals. */
194
+ taxAmount?: number | undefined;
195
+ /** `cac:TaxSubtotal` (BG-23) — the VAT breakdown. */
196
+ subtotals: UblTaxSubtotal[];
92
197
  }
93
198
 
94
199
  export interface UblMonetaryTotal {
200
+ /** BT-106 — sum of line net amounts. */
95
201
  lineExtensionAmount?: number | undefined;
202
+ /** BT-109 — total without VAT. */
96
203
  taxExclusiveAmount?: number | undefined;
204
+ /** BT-112 — total with VAT. */
97
205
  taxInclusiveAmount?: number | undefined;
206
+ /** BT-107 — sum of document-level allowances. */
98
207
  allowanceTotalAmount?: number | undefined;
208
+ /** BT-108 — sum of document-level charges. */
99
209
  chargeTotalAmount?: number | undefined;
210
+ /**
211
+ * BT-113 — sum of amounts paid in advance. **Gross (VAT-inclusive)**, since
212
+ * BR-CO-16 subtracts it directly from BT-112.
213
+ */
100
214
  prepaidAmount?: number | undefined;
215
+ /** BT-114 — rounding applied to the payable amount. */
101
216
  payableRoundingAmount?: number | undefined;
217
+ /**
218
+ * BT-115 — amount due for payment, i.e. the *outstanding* amount.
219
+ * BR-CO-16: `BT-115 = BT-112 − BT-113 + BT-114`.
220
+ */
102
221
  payableAmount?: number | undefined;
103
222
  }
104
223
 
105
224
  export interface UblPaymentMeans {
225
+ /** `cbc:PaymentMeansCode` (BT-81). */
106
226
  code?: string | undefined;
227
+ /** `cbc:PaymentMeansCode/@name` (BT-82). */
107
228
  codeName?: string | undefined;
229
+ /** `cbc:PaymentID` (BT-83). */
108
230
  paymentId?: string | undefined;
231
+ /** `cac:PayeeFinancialAccount/cbc:ID` (BT-84). */
109
232
  iban?: string | undefined;
233
+ /** `cac:FinancialInstitutionBranch/cbc:ID` (BT-86). */
110
234
  bic?: string | undefined;
235
+ /** `cac:PayeeFinancialAccount/cbc:Name` (BT-85). */
111
236
  accountName?: string | undefined;
237
+ /** `cac:PaymentMandate/cbc:ID` (BT-89). */
112
238
  mandateId?: string | undefined;
113
239
  }
114
240
 
241
+ /**
242
+ * A service period: BT-73/BT-74 on the document, BT-134/BT-135 on a line.
243
+ * Either bound may stand alone — UBL allows a half-open period — but a period
244
+ * with neither is omitted entirely.
245
+ */
115
246
  export interface UblInvoicePeriod {
247
+ /** `cbc:StartDate`, `YYYY-MM-DD`. */
116
248
  startDate?: string | undefined;
249
+ /** `cbc:EndDate`, `YYYY-MM-DD`, inclusive. */
117
250
  endDate?: string | undefined;
251
+ /** `cbc:DescriptionCode` (BT-8). */
118
252
  descriptionCode?: string | undefined;
119
253
  }
120
254
 
255
+ /** A supporting document (BG-24): embedded (`base64Content`) or external (`externalUri`). */
121
256
  export interface UblAttachment {
257
+ /** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
122
258
  id?: string | undefined;
259
+ /** `cbc:EmbeddedDocumentBinaryObject/@filename` (BT-125-2). */
123
260
  filename?: string | undefined;
261
+ /** MIME type (BT-125-1), e.g. `application/pdf`. */
124
262
  mimeCode?: string | undefined;
263
+ /** `cbc:DocumentDescription` (BT-123). */
125
264
  description?: string | undefined;
265
+ /** Base64-encoded document bytes (BT-125). */
126
266
  base64Content?: string | undefined;
267
+ /** `cac:ExternalReference/cbc:URI` (BT-124). */
127
268
  externalUri?: string | undefined;
128
269
  }
129
270
 
271
+ /** A text-only `cac:AdditionalDocumentReference` (no attachment). */
130
272
  export interface UblDocumentReference {
131
273
  id?: string | undefined;
132
274
  description?: string | undefined;
133
275
  }
134
276
 
135
277
  export interface UblDelivery {
278
+ /** `cbc:ActualDeliveryDate` (BT-72). */
136
279
  actualDeliveryDate?: string | undefined;
280
+ /** `cac:DeliveryLocation/cac:Address` (BG-15). */
137
281
  address?: UblAddress | undefined;
138
282
  }
139
283
 
284
+ /** `cac:BillingReference/cac:InvoiceDocumentReference` (BT-25/BT-26). */
140
285
  export interface UblBillingReference {
141
286
  invoiceId?: string | undefined;
142
287
  invoiceIssueDate?: string | undefined;
@@ -144,33 +289,52 @@ export interface UblBillingReference {
144
289
 
145
290
  export interface UblInvoice {
146
291
  documentType: "Invoice" | "CreditNote";
292
+ /** `cbc:CustomizationID` (BT-24). The serializer defaults to Peppol BIS Billing 3.0. */
147
293
  customizationId?: string | undefined;
294
+ /** `cbc:ProfileID` (BT-23). The serializer defaults to the Peppol billing process. */
148
295
  profileId?: string | undefined;
296
+ /** Invoice / credit note number (BT-1). */
149
297
  id: string;
298
+ /** `cbc:InvoiceTypeCode` / `cbc:CreditNoteTypeCode` (BT-3). The serializer defaults to 380/381. */
150
299
  invoiceTypeCode?: string | undefined;
300
+ /** Issue date (BT-2), `YYYY-MM-DD`. */
151
301
  issueDate: string;
302
+ /** Payment due date (BT-9). Invoices only. */
152
303
  dueDate?: string | undefined;
304
+ /** `cbc:TaxPointDate` (BT-7). */
153
305
  taxPointDate?: string | undefined;
306
+ /** Document currency (BT-5). */
154
307
  currency: string;
308
+ /** Buyer reference (BT-10). */
155
309
  buyerReference?: string | undefined;
310
+ /** `cac:OrderReference/cbc:ID` (BT-13). */
156
311
  orderReference?: string | undefined;
312
+ /** `cac:OrderReference/cbc:SalesOrderID` (BT-14). */
157
313
  salesOrderId?: string | undefined;
314
+ /** `cac:ContractDocumentReference/cbc:ID` (BT-12). */
158
315
  contractReference?: string | undefined;
316
+ /** `cac:ProjectReference/cbc:ID` (BT-11). */
159
317
  projectReference?: string | undefined;
318
+ /** For credit notes: the referenced original invoice (BT-25). */
160
319
  billingReference?: UblBillingReference | undefined;
161
320
  seller: UblParty;
162
321
  buyer: UblParty;
163
322
  delivery?: UblDelivery | undefined;
164
323
  lines: UblLine[];
165
- taxSubtotals: UblTaxSubtotal[];
324
+ taxTotal: UblTaxTotal;
166
325
  monetaryTotal: UblMonetaryTotal;
326
+ /** The first entry of `paymentMeansList`. */
167
327
  paymentMeans?: UblPaymentMeans | undefined;
168
328
  paymentMeansList?: UblPaymentMeans[] | undefined;
329
+ /** Invoicing period (BT-73/BT-74). */
169
330
  invoicePeriod?: UblInvoicePeriod | undefined;
331
+ /** Free-text note (BT-22). */
170
332
  note?: string | undefined;
333
+ /** Payment terms note (BT-20, `cac:PaymentTerms/cbc:Note`). */
171
334
  paymentTermsNote?: string | undefined;
172
335
  attachments?: UblAttachment[] | undefined;
173
336
  documentReferences?: UblDocumentReference[] | undefined;
337
+ /** Document-level allowances and charges (BG-20/BG-21). */
174
338
  allowanceCharges?: UblAllowanceCharge[] | undefined;
175
339
  }
176
340