@financica/ubl 0.17.0 → 0.18.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.
@@ -1,12 +1,16 @@
1
1
  import { UblBuildError } from "../../errors";
2
2
  import type {
3
3
  UblAddress,
4
+ UblAllowanceCharge,
4
5
  UblAttachment,
5
6
  UblBillingReference,
7
+ UblDelivery,
6
8
  UblInvoice,
7
9
  UblInvoicePeriod,
8
10
  UblLine,
9
11
  UblParty,
12
+ UblPaymentMeans,
13
+ UblSchemedId,
10
14
  UblTaxCategory,
11
15
  UblTaxSubtotal,
12
16
  } from "../../types";
@@ -27,8 +31,9 @@ import {
27
31
  // ── Validation ─────────────────────────────────────────────────────────
28
32
  //
29
33
  // The model is permissive (the parser reads whatever a document states); the
30
- // serializer is where EN 16931 / Peppol BIS Billing 3.0 mandatory fields are
31
- // enforced. Each check names the BT and the model path in its message.
34
+ // serializer is where EN 16931 / Peppol BIS Billing 3.0 mandatory fields and
35
+ // the arithmetic business rules are enforced. Each check names the BT or the
36
+ // rule and the model path in its message.
32
37
 
33
38
  const missing = (what: string, path: string): UblBuildError =>
34
39
  new UblBuildError(`Missing ${what} (${path})`);
@@ -40,6 +45,23 @@ function required<T>(value: T | undefined, what: string, path: string): NonNulla
40
45
  return value as NonNullable<T>;
41
46
  }
42
47
 
48
+ const round2 = (value: number): number => Math.round(value * 100) / 100;
49
+
50
+ /** Sums of cent-rounded amounts must agree to the cent; R120 allows a cent either way. */
51
+ const assertEqual = (
52
+ rule: string,
53
+ actual: number,
54
+ expected: number,
55
+ path: string,
56
+ tolerance = 0.005,
57
+ ): void => {
58
+ if (Math.abs(actual - expected) > tolerance) {
59
+ throw new UblBuildError(
60
+ `${rule}: ${path} is ${actual.toFixed(2)}, expected ${expected.toFixed(2)}`,
61
+ );
62
+ }
63
+ };
64
+
43
65
  /** Category `O` (outside scope) is the one category BR-O-05 forbids a percent on. */
44
66
  const requiresPercent = (categoryId: string): boolean => categoryId !== "O";
45
67
 
@@ -55,18 +77,71 @@ const validateTaxCategory = (
55
77
  return { ...present, id };
56
78
  };
57
79
 
80
+ const validateAllowanceCharge = (
81
+ item: UblAllowanceCharge,
82
+ path: string,
83
+ level: "document" | "line",
84
+ ): void => {
85
+ const kind = item.chargeIndicator ? "charge" : "allowance";
86
+ required(item.amount, `${kind} amount (BT-92/BT-99)`, `${path}.amount`);
87
+ if (item.reason === undefined && item.reasonCode === undefined) {
88
+ throw missing(`${kind} reason or reason code (BT-97/BT-98)`, `${path}.reason`);
89
+ }
90
+ if (item.baseAmount !== undefined && item.multiplierFactorNumeric !== undefined) {
91
+ assertEqual(
92
+ "PEPPOL-EN16931-R040",
93
+ item.amount ?? 0,
94
+ round2((item.baseAmount * item.multiplierFactorNumeric) / 100),
95
+ `${path}.amount`,
96
+ 0.01,
97
+ );
98
+ }
99
+ if (level === "document") {
100
+ validateTaxCategory(item.taxCategory, `${path}.taxCategory`);
101
+ }
102
+ };
103
+
104
+ const lineAllowanceTotal = (line: UblLine, charges: boolean): number =>
105
+ (line.allowanceCharges ?? [])
106
+ .filter((item) => item.chargeIndicator === charges)
107
+ .reduce((sum, item) => sum + (item.amount ?? 0), 0);
108
+
58
109
  const validateLine = (line: UblLine, index: number): void => {
59
110
  const path = `lines[${index}]`;
60
111
  required(line.id, "line identifier (BT-126)", `${path}.id`);
61
- required(line.quantity, "invoiced quantity (BT-129)", `${path}.quantity`);
112
+ const quantity = required(
113
+ line.quantity,
114
+ "invoiced quantity (BT-129)",
115
+ `${path}.quantity`,
116
+ );
62
117
  required(line.unitCode, "unit code (BT-130)", `${path}.unitCode`);
63
- required(line.unitPrice, "net unit price (BT-146)", `${path}.unitPrice`);
64
- required(
118
+ const unitPrice = required(
119
+ line.unitPrice,
120
+ "net unit price (BT-146)",
121
+ `${path}.unitPrice`,
122
+ );
123
+ const net = required(
65
124
  line.lineExtensionAmount,
66
125
  "line net amount (BT-131)",
67
126
  `${path}.lineExtensionAmount`,
68
127
  );
69
128
  validateTaxCategory(line.taxCategory, `${path}.taxCategory`);
129
+ (line.allowanceCharges ?? []).forEach((item, itemIndex) =>
130
+ validateAllowanceCharge(item, `${path}.allowanceCharges[${itemIndex}]`, "line"),
131
+ );
132
+ // BT-131 = BT-129 × BT-146 + line charges − line allowances. `unitPrice` is
133
+ // the per-unit figure, so BT-149 is already accounted for.
134
+ assertEqual(
135
+ "PEPPOL-EN16931-R120",
136
+ net,
137
+ round2(
138
+ quantity * unitPrice +
139
+ lineAllowanceTotal(line, true) -
140
+ lineAllowanceTotal(line, false),
141
+ ),
142
+ `${path}.lineExtensionAmount`,
143
+ 0.02,
144
+ );
70
145
  };
71
146
 
72
147
  const isExternalOnly = (attachment: UblAttachment): boolean =>
@@ -88,22 +163,181 @@ const validateAttachment = (attachment: UblAttachment, index: number): void => {
88
163
  );
89
164
  };
90
165
 
166
+ /** UNCL4461 codes whose payment means need a mandate (direct debit) or an account (credit transfer). */
167
+ const DIRECT_DEBIT_CODES = new Set(["49", "59"]);
168
+ const CREDIT_TRANSFER_CODES = new Set(["30", "58"]);
169
+
170
+ const validatePaymentMeans = (means: UblPaymentMeans, index: number): void => {
171
+ const path = `paymentMeansList[${index}]`;
172
+ const code = required(means.code, "payment means code (BT-81)", `${path}.code`);
173
+ if (CREDIT_TRANSFER_CODES.has(code)) {
174
+ required(
175
+ means.iban,
176
+ `payment account (BT-84) for code ${code}`,
177
+ `${path}.iban`,
178
+ );
179
+ }
180
+ if (DIRECT_DEBIT_CODES.has(code)) {
181
+ required(
182
+ means.mandateId,
183
+ `mandate reference (BT-89) for code ${code}`,
184
+ `${path}.mandateId`,
185
+ );
186
+ }
187
+ };
188
+
189
+ const validateParty = (party: UblParty, role: string, nameBt: string): void => {
190
+ required(party.name, `${role} name (${nameBt})`, `${role}.name`);
191
+ if (party.endpoint && party.endpoint.scheme === undefined) {
192
+ throw missing(`${role} endpoint scheme`, `${role}.endpoint.scheme`);
193
+ }
194
+ };
195
+
196
+ const paymentMeansList = (doc: UblInvoice): UblPaymentMeans[] =>
197
+ doc.paymentMeansList ?? (doc.paymentMeans ? [doc.paymentMeans] : []);
198
+
199
+ const sumBy = <T>(items: T[], pick: (item: T) => number): number =>
200
+ round2(items.reduce((sum, item) => sum + pick(item), 0));
201
+
202
+ const categoryKey = (category: UblTaxCategory | undefined): string =>
203
+ `${category?.id ?? ""}:${category?.percent ?? ""}`;
204
+
205
+ /**
206
+ * The document arithmetic EN 16931 fixes: BR-CO-10 (line sum), BR-CO-11/12
207
+ * (allowance and charge sums), BR-CO-13 (total without VAT), BR-CO-15 (total
208
+ * with VAT), BR-CO-16 (amount due) and the BR-S-08 family (each VAT category's
209
+ * taxable amount is its line nets minus its allowances plus its charges).
210
+ */
211
+ const validateArithmetic = (doc: UblInvoice): void => {
212
+ const total = doc.monetaryTotal;
213
+ const docItems = doc.allowanceCharges ?? [];
214
+ const allowances = docItems.filter((item) => !item.chargeIndicator);
215
+ const charges = docItems.filter((item) => item.chargeIndicator);
216
+ const lineSum = sumBy(doc.lines, (line) => line.lineExtensionAmount ?? 0);
217
+ const allowanceSum = sumBy(allowances, (item) => item.amount ?? 0);
218
+ const chargeSum = sumBy(charges, (item) => item.amount ?? 0);
219
+
220
+ assertEqual(
221
+ "BR-CO-10",
222
+ total.lineExtensionAmount ?? 0,
223
+ lineSum,
224
+ "monetaryTotal.lineExtensionAmount",
225
+ );
226
+ if (allowances.length > 0 || total.allowanceTotalAmount !== undefined) {
227
+ assertEqual(
228
+ "BR-CO-11",
229
+ total.allowanceTotalAmount ?? 0,
230
+ allowanceSum,
231
+ "monetaryTotal.allowanceTotalAmount",
232
+ );
233
+ }
234
+ if (charges.length > 0 || total.chargeTotalAmount !== undefined) {
235
+ assertEqual(
236
+ "BR-CO-12",
237
+ total.chargeTotalAmount ?? 0,
238
+ chargeSum,
239
+ "monetaryTotal.chargeTotalAmount",
240
+ );
241
+ }
242
+ assertEqual(
243
+ "BR-CO-13",
244
+ total.taxExclusiveAmount ?? 0,
245
+ round2(lineSum - allowanceSum + chargeSum),
246
+ "monetaryTotal.taxExclusiveAmount",
247
+ );
248
+ assertEqual(
249
+ "BR-CO-15",
250
+ total.taxInclusiveAmount ?? 0,
251
+ round2((total.taxExclusiveAmount ?? 0) + (doc.taxTotal.taxAmount ?? 0)),
252
+ "monetaryTotal.taxInclusiveAmount",
253
+ );
254
+ assertEqual(
255
+ "BR-CO-16",
256
+ total.payableAmount ?? 0,
257
+ round2(
258
+ (total.taxInclusiveAmount ?? 0) -
259
+ (total.prepaidAmount ?? 0) +
260
+ (total.payableRoundingAmount ?? 0),
261
+ ),
262
+ "monetaryTotal.payableAmount",
263
+ );
264
+
265
+ const taxableByCategory = new Map<string, number>();
266
+ const add = (category: UblTaxCategory | undefined, amount: number): void => {
267
+ const key = categoryKey(category);
268
+ taxableByCategory.set(key, round2((taxableByCategory.get(key) ?? 0) + amount));
269
+ };
270
+ for (const line of doc.lines) add(line.taxCategory, line.lineExtensionAmount ?? 0);
271
+ for (const item of docItems) {
272
+ add(
273
+ item.taxCategory,
274
+ item.chargeIndicator ? (item.amount ?? 0) : -(item.amount ?? 0),
275
+ );
276
+ }
277
+ doc.taxTotal.subtotals.forEach((subtotal, index) => {
278
+ const key = categoryKey(subtotal.category);
279
+ const expected = taxableByCategory.get(key);
280
+ if (expected === undefined) {
281
+ throw new UblBuildError(
282
+ `BR-S-08: taxTotal.subtotals[${index}] (${key}) has no line, allowance or charge in that category`,
283
+ );
284
+ }
285
+ assertEqual(
286
+ "BR-S-08",
287
+ subtotal.taxableAmount ?? 0,
288
+ expected,
289
+ `taxTotal.subtotals[${index}].taxableAmount`,
290
+ );
291
+ });
292
+ };
293
+
91
294
  const validateInvoice = (doc: UblInvoice): void => {
92
295
  required(doc.id, "document identifier (BT-1)", "id");
93
296
  required(doc.issueDate, "issue date (BT-2)", "issueDate");
94
297
  required(doc.currency, "document currency (BT-5)", "currency");
95
- required(doc.seller.name, "seller name (BT-27)", "seller.name");
96
- required(doc.buyer.name, "buyer name (BT-44)", "buyer.name");
97
- if (doc.seller.endpoint && doc.seller.endpoint.scheme === undefined) {
98
- throw missing("seller endpoint scheme (BT-34-1)", "seller.endpoint.scheme");
298
+ if (
299
+ doc.taxPointDate !== undefined &&
300
+ doc.invoicePeriod?.descriptionCode !== undefined
301
+ ) {
302
+ throw new UblBuildError(
303
+ "BR-CO-3: a tax point date (BT-7, taxPointDate) and a tax point date code (BT-8, invoicePeriod.descriptionCode) are mutually exclusive",
304
+ );
99
305
  }
100
- if (doc.buyer.endpoint && doc.buyer.endpoint.scheme === undefined) {
101
- throw missing("buyer endpoint scheme (BT-49-1)", "buyer.endpoint.scheme");
306
+ if (doc.taxCurrency !== undefined) {
307
+ required(
308
+ doc.taxTotal.taxAmountInTaxCurrency,
309
+ "VAT total in the accounting currency (BT-111, BR-53)",
310
+ "taxTotal.taxAmountInTaxCurrency",
311
+ );
312
+ }
313
+ validateParty(doc.seller, "seller", "BT-27");
314
+ validateParty(doc.buyer, "buyer", "BT-44");
315
+ if (doc.payee) required(doc.payee.name, "payee name (BT-59)", "payee.name");
316
+ if (doc.taxRepresentative) {
317
+ required(
318
+ doc.taxRepresentative.name,
319
+ "tax representative name (BT-62)",
320
+ "taxRepresentative.name",
321
+ );
322
+ required(
323
+ doc.taxRepresentative.vatId,
324
+ "tax representative VAT identifier (BT-63)",
325
+ "taxRepresentative.vatId",
326
+ );
327
+ required(
328
+ doc.taxRepresentative.address?.countryCode,
329
+ "tax representative country (BT-69)",
330
+ "taxRepresentative.address.countryCode",
331
+ );
102
332
  }
103
333
  if (doc.lines.length === 0) {
104
334
  throw new UblBuildError("A document needs at least one line (BG-25, lines)");
105
335
  }
106
336
  doc.lines.forEach(validateLine);
337
+ (doc.allowanceCharges ?? []).forEach((item, index) =>
338
+ validateAllowanceCharge(item, `allowanceCharges[${index}]`, "document"),
339
+ );
340
+ paymentMeansList(doc).forEach(validatePaymentMeans);
107
341
  required(doc.taxTotal.taxAmount, "total VAT amount (BT-110)", "taxTotal.taxAmount");
108
342
  const total = doc.monetaryTotal;
109
343
  required(
@@ -123,6 +357,7 @@ const validateInvoice = (doc: UblInvoice): void => {
123
357
  );
124
358
  required(total.payableAmount, "amount due (BT-115)", "monetaryTotal.payableAmount");
125
359
  (doc.attachments ?? []).forEach(validateAttachment);
360
+ validateArithmetic(doc);
126
361
  };
127
362
 
128
363
  // ── Formatting ─────────────────────────────────────────────────────────
@@ -139,16 +374,28 @@ const percent = (value: number): string => {
139
374
  const money = (name: string, value: number, currency: string): XmlElement =>
140
375
  el(name, { currencyID: currency }, amount(value));
141
376
 
377
+ const optionalMoney = (
378
+ name: string,
379
+ value: number | undefined,
380
+ currency: string,
381
+ ): XmlElement | null => (value !== undefined ? money(name, value, currency) : null);
382
+
142
383
  const text = (name: string, value: string | undefined): XmlElement | null =>
143
384
  value !== undefined ? el(name, null, value) : null;
144
385
 
386
+ const schemedId = (name: string, id: UblSchemedId | undefined): XmlElement | null =>
387
+ id !== undefined
388
+ ? el(name, id.scheme !== undefined ? { schemeID: id.scheme } : null, id.value)
389
+ : null;
390
+
145
391
  const taxScheme = (schemeId: string | undefined): XmlElement =>
146
392
  el("cac:TaxScheme", null, [el("cbc:ID", null, schemeId ?? VAT_TAX_SCHEME_ID)]);
147
393
 
148
394
  /**
149
395
  * Render a tax category, shared between `cac:ClassifiedTaxCategory` (on lines)
150
- * and `cac:TaxCategory` (in the VAT breakdown). EN 16931 requires an exemption
151
- * reason for the non-charging categories (E/AE/O/K/G).
396
+ * and `cac:TaxCategory` (in the VAT breakdown and on document allowances and
397
+ * charges). EN 16931 requires an exemption reason for the non-charging
398
+ * categories (E/AE/O/K/G); the code precedes the text in the sequence.
152
399
  */
153
400
  const taxCategory = (
154
401
  name: string,
@@ -161,29 +408,77 @@ const taxCategory = (
161
408
  valid.percent !== undefined
162
409
  ? el("cbc:Percent", null, percent(valid.percent))
163
410
  : null,
411
+ text("cbc:TaxExemptionReasonCode", valid.exemptionReasonCode),
164
412
  text("cbc:TaxExemptionReason", valid.exemptionReason),
165
413
  taxScheme(valid.schemeId),
166
414
  ]);
167
415
  };
168
416
 
417
+ const addressChildren = (address: UblAddress): (XmlElement | null)[] => [
418
+ text("cbc:StreetName", address.street),
419
+ text("cbc:AdditionalStreetName", address.additionalStreet),
420
+ text("cbc:CityName", address.city),
421
+ text("cbc:PostalZone", address.postalZone),
422
+ text("cbc:CountrySubentity", address.countrySubentity),
423
+ address.countryCode !== undefined
424
+ ? el("cac:Country", null, [
425
+ el(
426
+ "cbc:IdentificationCode",
427
+ { listID: COUNTRY_CODE_LIST_ID },
428
+ address.countryCode,
429
+ ),
430
+ ])
431
+ : null,
432
+ ];
433
+
169
434
  const postalAddress = (address: UblAddress): XmlElement =>
170
- el("cac:PostalAddress", null, [
171
- text("cbc:StreetName", address.street),
172
- text("cbc:AdditionalStreetName", address.additionalStreet),
173
- text("cbc:CityName", address.city),
174
- text("cbc:PostalZone", address.postalZone),
175
- text("cbc:CountrySubentity", address.countrySubentity),
176
- address.countryCode !== undefined
177
- ? el("cac:Country", null, [
178
- el(
179
- "cbc:IdentificationCode",
180
- { listID: COUNTRY_CODE_LIST_ID },
181
- address.countryCode,
182
- ),
183
- ])
184
- : null,
185
- ]);
435
+ el("cac:PostalAddress", null, addressChildren(address));
436
+
437
+ const partyIdentifications = (source: UblParty): XmlElement[] =>
438
+ (source.partyIdentifications ?? []).map((identification) =>
439
+ el("cac:PartyIdentification", null, [
440
+ el(
441
+ "cbc:ID",
442
+ identification.schemeId !== undefined
443
+ ? { schemeID: identification.schemeId }
444
+ : null,
445
+ identification.id,
446
+ ),
447
+ ]),
448
+ );
449
+
450
+ const partyName = (name: string): XmlElement =>
451
+ el("cac:PartyName", null, [el("cbc:Name", null, name)]);
452
+
453
+ const partyTaxScheme = (source: UblParty): XmlElement | null =>
454
+ source.vatId !== undefined
455
+ ? el("cac:PartyTaxScheme", null, [
456
+ el("cbc:CompanyID", null, source.vatId),
457
+ taxScheme(source.taxSchemeId),
458
+ ])
459
+ : null;
186
460
 
461
+ const companyId = (source: UblParty): XmlElement | null =>
462
+ source.companyId
463
+ ? el(
464
+ "cbc:CompanyID",
465
+ source.companyId.scheme !== undefined
466
+ ? { schemeID: source.companyId.scheme }
467
+ : null,
468
+ source.companyId.value,
469
+ )
470
+ : null;
471
+
472
+ const contact = (source: UblParty): XmlElement | null =>
473
+ source.contact
474
+ ? el("cac:Contact", null, [
475
+ text("cbc:Name", source.contact.name),
476
+ text("cbc:Telephone", source.contact.phone),
477
+ text("cbc:ElectronicMail", source.contact.email),
478
+ ])
479
+ : null;
480
+
481
+ /** `cac:Party` for the seller and buyer (BG-4, BG-7). */
187
482
  const party = (source: UblParty, name: string): XmlElement =>
188
483
  el("cac:Party", null, [
189
484
  source.endpoint
@@ -193,26 +488,137 @@ const party = (source: UblParty, name: string): XmlElement =>
193
488
  source.endpoint.value,
194
489
  )
195
490
  : null,
196
- el("cac:PartyName", null, [el("cbc:Name", null, name)]),
491
+ ...partyIdentifications(source),
492
+ partyName(name),
197
493
  source.address ? postalAddress(source.address) : null,
198
- source.vatId !== undefined
199
- ? el("cac:PartyTaxScheme", null, [
200
- el("cbc:CompanyID", null, source.vatId),
201
- taxScheme(source.taxSchemeId),
202
- ])
203
- : null,
494
+ partyTaxScheme(source),
204
495
  el("cac:PartyLegalEntity", null, [
205
496
  el("cbc:RegistrationName", null, source.registrationName ?? name),
206
- source.companyId
207
- ? el(
208
- "cbc:CompanyID",
209
- source.companyId.scheme !== undefined
210
- ? { schemeID: source.companyId.scheme }
211
- : null,
212
- source.companyId.value,
213
- )
214
- : null,
497
+ companyId(source),
498
+ text("cbc:CompanyLegalForm", source.companyLegalForm),
215
499
  ]),
500
+ contact(source),
501
+ ]);
502
+
503
+ /** `cac:PayeeParty` (BG-10): identification, name and legal entity id, unwrapped. */
504
+ const payeeParty = (source: UblParty): XmlElement =>
505
+ el("cac:PayeeParty", null, [
506
+ ...partyIdentifications(source),
507
+ partyName(source.name ?? ""),
508
+ source.companyId ? el("cac:PartyLegalEntity", null, [companyId(source)]) : null,
509
+ ]);
510
+
511
+ /** `cac:TaxRepresentativeParty` (BG-11): name, address and VAT id, unwrapped. */
512
+ const taxRepresentativeParty = (source: UblParty): XmlElement =>
513
+ el("cac:TaxRepresentativeParty", null, [
514
+ partyName(source.name ?? ""),
515
+ source.address ? postalAddress(source.address) : null,
516
+ partyTaxScheme(source),
517
+ ]);
518
+
519
+ /** `cac:Delivery` (BG-13). */
520
+ const delivery = (source: UblDelivery): XmlElement | null => {
521
+ const location =
522
+ source.locationId !== undefined || source.address !== undefined
523
+ ? el("cac:DeliveryLocation", null, [
524
+ schemedId("cbc:ID", source.locationId),
525
+ source.address
526
+ ? el("cac:Address", null, addressChildren(source.address))
527
+ : null,
528
+ ])
529
+ : null;
530
+ const deliveryParty =
531
+ source.partyName !== undefined
532
+ ? el("cac:DeliveryParty", null, [partyName(source.partyName)])
533
+ : null;
534
+ if (source.actualDeliveryDate === undefined && !location && !deliveryParty)
535
+ return null;
536
+ return el("cac:Delivery", null, [
537
+ text("cbc:ActualDeliveryDate", source.actualDeliveryDate),
538
+ location,
539
+ deliveryParty,
540
+ ]);
541
+ };
542
+
543
+ /**
544
+ * `cac:PaymentMeans` (BG-16). On a credit note BT-9 has no root element and
545
+ * rides in the first payment means as `cbc:PaymentDueDate`. `cbc:NetworkID`
546
+ * is schema-mandatory inside `cac:CardAccount` and carries no business term;
547
+ * the BIS example value is `NA`.
548
+ */
549
+ const paymentMeans = (
550
+ source: UblPaymentMeans,
551
+ dueDate: string | undefined,
552
+ ): XmlElement =>
553
+ el("cac:PaymentMeans", null, [
554
+ el(
555
+ "cbc:PaymentMeansCode",
556
+ source.codeName !== undefined ? { name: source.codeName } : null,
557
+ source.code ?? "",
558
+ ),
559
+ text("cbc:PaymentDueDate", dueDate),
560
+ text("cbc:PaymentID", source.paymentId),
561
+ source.cardNumber !== undefined
562
+ ? el("cac:CardAccount", null, [
563
+ el("cbc:PrimaryAccountNumberID", null, source.cardNumber),
564
+ el("cbc:NetworkID", null, "NA"),
565
+ text("cbc:HolderName", source.cardHolder),
566
+ ])
567
+ : null,
568
+ source.iban !== undefined
569
+ ? el("cac:PayeeFinancialAccount", null, [
570
+ el("cbc:ID", null, source.iban),
571
+ text("cbc:Name", source.accountName),
572
+ source.bic !== undefined
573
+ ? el("cac:FinancialInstitutionBranch", null, [
574
+ el("cbc:ID", null, source.bic),
575
+ ])
576
+ : null,
577
+ ])
578
+ : null,
579
+ source.mandateId !== undefined
580
+ ? el("cac:PaymentMandate", null, [
581
+ el("cbc:ID", null, source.mandateId),
582
+ source.debitedAccount !== undefined
583
+ ? el("cac:PayerFinancialAccount", null, [
584
+ el("cbc:ID", null, source.debitedAccount),
585
+ ])
586
+ : null,
587
+ ])
588
+ : null,
589
+ ]);
590
+
591
+ /**
592
+ * `cac:AllowanceCharge` at document level (BG-20/BG-21, with its VAT
593
+ * category) and line level (BG-27/BG-28, without: the line's category
594
+ * applies).
595
+ */
596
+ const allowanceCharge = (
597
+ item: UblAllowanceCharge,
598
+ currency: string,
599
+ path: string,
600
+ level: "document" | "line",
601
+ ): XmlElement =>
602
+ el("cac:AllowanceCharge", null, [
603
+ el("cbc:ChargeIndicator", null, item.chargeIndicator ? "true" : "false"),
604
+ text("cbc:AllowanceChargeReasonCode", item.reasonCode),
605
+ text("cbc:AllowanceChargeReason", item.reason),
606
+ item.multiplierFactorNumeric !== undefined
607
+ ? el(
608
+ "cbc:MultiplierFactorNumeric",
609
+ null,
610
+ percent(item.multiplierFactorNumeric),
611
+ )
612
+ : null,
613
+ money("cbc:Amount", item.amount ?? 0, currency),
614
+ optionalMoney("cbc:BaseAmount", item.baseAmount, currency),
615
+ level === "document"
616
+ ? taxCategory(
617
+ "cac:TaxCategory",
618
+ item.taxCategory ?? {},
619
+ `${path}.taxCategory`,
620
+ )
621
+ : null,
216
622
  ]);
217
623
 
218
624
  const taxSubtotal = (
@@ -245,17 +651,32 @@ const taxSubtotal = (
245
651
  };
246
652
 
247
653
  /**
248
- * `cac:LegalMonetaryTotal` children, in UBL sequence order. `cbc:PrepaidAmount`
249
- * (BT-113) and `cbc:PayableRoundingAmount` (BT-114) precede `cbc:PayableAmount`
250
- * — emitting them after it produces schema-invalid XML. BT-113/BT-114 are
251
- * omitted when absent or zero.
654
+ * `cac:LegalMonetaryTotal` children, in UBL sequence order. BT-107/BT-108 are
655
+ * written when the document carries allowances or charges; BT-113 and BT-114
656
+ * are omitted when absent or zero.
252
657
  */
253
658
  const legalMonetaryTotalChildren = (doc: UblInvoice): XmlElement[] => {
254
659
  const { currency, monetaryTotal: total } = doc;
660
+ const hasAllowances = (doc.allowanceCharges ?? []).some(
661
+ (item) => !item.chargeIndicator,
662
+ );
663
+ const hasCharges = (doc.allowanceCharges ?? []).some(
664
+ (item) => item.chargeIndicator,
665
+ );
255
666
  const children: (XmlElement | null)[] = [
256
667
  money("cbc:LineExtensionAmount", total.lineExtensionAmount ?? 0, currency),
257
668
  money("cbc:TaxExclusiveAmount", total.taxExclusiveAmount ?? 0, currency),
258
669
  money("cbc:TaxInclusiveAmount", total.taxInclusiveAmount ?? 0, currency),
670
+ hasAllowances || total.allowanceTotalAmount
671
+ ? money(
672
+ "cbc:AllowanceTotalAmount",
673
+ total.allowanceTotalAmount ?? 0,
674
+ currency,
675
+ )
676
+ : null,
677
+ hasCharges || total.chargeTotalAmount
678
+ ? money("cbc:ChargeTotalAmount", total.chargeTotalAmount ?? 0, currency)
679
+ : null,
259
680
  total.prepaidAmount
260
681
  ? money("cbc:PrepaidAmount", total.prepaidAmount, currency)
261
682
  : null,
@@ -269,7 +690,8 @@ const legalMonetaryTotalChildren = (doc: UblInvoice): XmlElement[] => {
269
690
 
270
691
  /**
271
692
  * `cac:InvoicePeriod`. Null when neither bound is set — an empty period element
272
- * fails BR-CO-19, which requires at least one of the two dates.
693
+ * fails BR-CO-19, which requires at least one of the two dates. BT-8 (the tax
694
+ * point date code) is only meaningful on the document period.
273
695
  */
274
696
  const invoicePeriod = (period: UblInvoicePeriod | undefined): XmlElement | null => {
275
697
  if (!period || (period.startDate === undefined && period.endDate === undefined)) {
@@ -278,9 +700,60 @@ const invoicePeriod = (period: UblInvoicePeriod | undefined): XmlElement | null
278
700
  return el("cac:InvoicePeriod", null, [
279
701
  text("cbc:StartDate", period.startDate),
280
702
  text("cbc:EndDate", period.endDate),
703
+ text("cbc:DescriptionCode", period.descriptionCode),
281
704
  ]);
282
705
  };
283
706
 
707
+ const item = (source: UblLine): XmlElement =>
708
+ el("cac:Item", null, [
709
+ text("cbc:Description", source.description),
710
+ // BT-153 is mandatory; BT-154 stands in when the line has no name.
711
+ el("cbc:Name", null, source.itemName ?? source.description ?? source.id),
712
+ source.buyersItemId !== undefined
713
+ ? el("cac:BuyersItemIdentification", null, [
714
+ el("cbc:ID", null, source.buyersItemId),
715
+ ])
716
+ : null,
717
+ source.sellersItemId !== undefined
718
+ ? el("cac:SellersItemIdentification", null, [
719
+ el("cbc:ID", null, source.sellersItemId),
720
+ ])
721
+ : null,
722
+ source.standardItemId !== undefined
723
+ ? el("cac:StandardItemIdentification", null, [
724
+ schemedId("cbc:ID", source.standardItemId),
725
+ ])
726
+ : null,
727
+ source.originCountryCode !== undefined
728
+ ? el("cac:OriginCountry", null, [
729
+ el("cbc:IdentificationCode", null, source.originCountryCode),
730
+ ])
731
+ : null,
732
+ ...(source.commodityClassifications ?? []).map((classification) =>
733
+ el("cac:CommodityClassification", null, [
734
+ el(
735
+ "cbc:ItemClassificationCode",
736
+ {
737
+ listID: classification.listId,
738
+ listVersionID: classification.listVersionId,
739
+ },
740
+ classification.value,
741
+ ),
742
+ ]),
743
+ ),
744
+ taxCategory(
745
+ "cac:ClassifiedTaxCategory",
746
+ source.taxCategory ?? {},
747
+ `lines[${source.id}].taxCategory`,
748
+ ),
749
+ ...(source.additionalItemProperties ?? []).map((property) =>
750
+ el("cac:AdditionalItemProperty", null, [
751
+ el("cbc:Name", null, property.name),
752
+ el("cbc:Value", null, property.value ?? ""),
753
+ ]),
754
+ ),
755
+ ]);
756
+
284
757
  const line = (
285
758
  source: UblLine,
286
759
  currency: string,
@@ -297,19 +770,31 @@ const line = (
297
770
 
298
771
  return el(lineElementName, null, [
299
772
  el("cbc:ID", null, source.id),
773
+ text("cbc:Note", source.note),
300
774
  el(quantityElementName, { unitCode }, String(source.quantity ?? 0)),
301
775
  money("cbc:LineExtensionAmount", source.lineExtensionAmount ?? 0, currency),
776
+ text("cbc:AccountingCost", source.accountingCost),
302
777
  invoicePeriod(source.invoicePeriod),
303
- el("cac:Item", null, [
304
- text("cbc:Description", source.description),
305
- // BT-153 is mandatory; BT-154 stands in when the line has no name.
306
- el("cbc:Name", null, source.itemName ?? source.description ?? source.id),
307
- taxCategory(
308
- "cac:ClassifiedTaxCategory",
309
- source.taxCategory ?? {},
310
- `lines[${source.id}].taxCategory`,
778
+ source.orderLineReference !== undefined
779
+ ? el("cac:OrderLineReference", null, [
780
+ el("cbc:LineID", null, source.orderLineReference),
781
+ ])
782
+ : null,
783
+ source.objectIdentifier !== undefined
784
+ ? el("cac:DocumentReference", null, [
785
+ schemedId("cbc:ID", source.objectIdentifier),
786
+ el("cbc:DocumentTypeCode", null, "130"),
787
+ ])
788
+ : null,
789
+ ...(source.allowanceCharges ?? []).map((entry, index) =>
790
+ allowanceCharge(
791
+ entry,
792
+ currency,
793
+ `lines[${source.id}].allowanceCharges[${index}]`,
794
+ "line",
311
795
  ),
312
- ]),
796
+ ),
797
+ item(source),
313
798
  // BT-149's unit code must match the invoiced/credited quantity's
314
799
  // (PEPPOL-EN16931-R130).
315
800
  el("cac:Price", null, [
@@ -317,6 +802,21 @@ const line = (
317
802
  source.baseQuantity !== undefined
318
803
  ? el("cbc:BaseQuantity", { unitCode }, String(source.baseQuantity))
319
804
  : null,
805
+ source.priceAllowance !== undefined
806
+ ? el("cac:AllowanceCharge", null, [
807
+ el("cbc:ChargeIndicator", null, "false"),
808
+ money(
809
+ "cbc:Amount",
810
+ source.priceAllowance.amount ?? 0,
811
+ currency,
812
+ ),
813
+ optionalMoney(
814
+ "cbc:BaseAmount",
815
+ source.priceAllowance.baseAmount,
816
+ currency,
817
+ ),
818
+ ])
819
+ : null,
320
820
  ]),
321
821
  ]);
322
822
  };
@@ -328,6 +828,7 @@ const attachmentReference = (attachment: UblAttachment): XmlElement =>
328
828
  null,
329
829
  attachment.id ?? attachment.filename ?? attachment.externalUri ?? "",
330
830
  ),
831
+ text("cbc:DocumentDescription", attachment.description),
331
832
  el("cac:Attachment", null, [
332
833
  isExternalOnly(attachment)
333
834
  ? el("cac:ExternalReference", null, [
@@ -344,11 +845,34 @@ const attachmentReference = (attachment: UblAttachment): XmlElement =>
344
845
  ]),
345
846
  ]);
346
847
 
848
+ /** A typed `cac:AdditionalDocumentReference` without attachment (BT-17, BT-18, BT-11 on a credit note). */
849
+ const typedDocumentReference = (id: UblSchemedId, typeCode: string): XmlElement =>
850
+ el("cac:AdditionalDocumentReference", null, [
851
+ schemedId("cbc:ID", id),
852
+ el("cbc:DocumentTypeCode", null, typeCode),
853
+ ]);
854
+
855
+ const documentReference = (name: string, id: string | undefined): XmlElement | null =>
856
+ id !== undefined ? el(name, null, [el("cbc:ID", null, id)]) : null;
857
+
858
+ /**
859
+ * `cac:OrderReference`. BT-13 (the buyer's order number) is the element's
860
+ * mandatory child, so a sales order id (BT-14) alone is not emitted.
861
+ */
862
+ const orderReference = (doc: UblInvoice): XmlElement | null => {
863
+ if (doc.orderReference === undefined) return null;
864
+ return el("cac:OrderReference", null, [
865
+ el("cbc:ID", null, doc.orderReference),
866
+ text("cbc:SalesOrderID", doc.salesOrderId),
867
+ ]);
868
+ };
869
+
347
870
  const billingReference = (reference: UblBillingReference): XmlElement | null => {
348
871
  if (reference.invoiceId === undefined) return null;
349
872
  return el("cac:BillingReference", null, [
350
873
  el("cac:InvoiceDocumentReference", null, [
351
874
  el("cbc:ID", null, reference.invoiceId),
875
+ text("cbc:IssueDate", reference.invoiceIssueDate),
352
876
  ]),
353
877
  ]);
354
878
  };
@@ -356,19 +880,21 @@ const billingReference = (reference: UblBillingReference): XmlElement | null =>
356
880
  /**
357
881
  * Serialize a {@link UblInvoice} into a Peppol BIS Billing 3.0 XML string.
358
882
  *
359
- * Emits the subset of the model a Peppol BIS Billing 3.0 document needs:
360
- * header (`customizationId`, `profileId` and `invoiceTypeCode` default to the
361
- * BIS values), note, buyer reference, invoice period, billing reference,
362
- * attachments, parties, payment terms, VAT breakdown, monetary totals and
363
- * lines with their price and classified VAT category. Payment means,
364
- * allowances/charges, delivery and the document references are not emitted.
883
+ * Writes every EN 16931 business term the model holds, at its position in the
884
+ * UBL 2.1 sequence: the header terms (`customizationId`, `profileId` and
885
+ * `invoiceTypeCode` default to the BIS values), the references (BT-10 to
886
+ * BT-19), the parties with identifications, legal form and contacts, the
887
+ * payee and tax representative, delivery, payment means, payment terms,
888
+ * document and line allowances and charges, the VAT breakdown (plus BT-111 in
889
+ * the accounting currency), the monetary totals, attachments and document
890
+ * references, and lines with their item identifiers, classifications,
891
+ * properties, price discount and classified VAT category. Line-level tax
892
+ * totals are not emitted: BIS Billing 3.0 forbids them.
365
893
  *
366
- * @throws {UblBuildError} when a field EN 16931 / Peppol BIS makes mandatory is
367
- * missing: document id, issue date, currency, seller and buyer name, an
368
- * endpoint without a scheme, at least one line, per line the quantity, unit
369
- * code, unit price, net amount and VAT category (id, plus the rate unless the
370
- * category is `O`), the total VAT amount, the four monetary totals, and for an
371
- * embedded attachment its filename, MIME code and content.
894
+ * @throws {UblBuildError} when a field EN 16931 / Peppol BIS makes mandatory
895
+ * is missing (naming the BT and the model path), or when the document's
896
+ * arithmetic breaks a business rule: BR-CO-3, BR-CO-10 to BR-CO-13, BR-CO-15,
897
+ * BR-CO-16, BR-53, the BR-S-08 family, PEPPOL-EN16931-R040 and R120.
372
898
  */
373
899
  export const serializeUblInvoice = (doc: UblInvoice): string => {
374
900
  validateInvoice(doc);
@@ -383,39 +909,94 @@ export const serializeUblInvoice = (doc: UblInvoice): string => {
383
909
  doc.invoiceTypeCode ?? CREDIT_NOTE_TYPE_CODE,
384
910
  )
385
911
  : el("cbc:InvoiceTypeCode", null, doc.invoiceTypeCode ?? INVOICE_TYPE_CODE);
912
+ const taxPointDate = text("cbc:TaxPointDate", doc.taxPointDate);
913
+ const means = paymentMeansList(doc);
914
+ // A credit note has no cbc:DueDate: BT-9 goes in the first PaymentMeans.
915
+ const creditNoteDueDate =
916
+ isCreditNote && means.length > 0 ? doc.dueDate : undefined;
386
917
 
387
918
  const children: (XmlElement | null | false)[] = [
388
919
  el("cbc:CustomizationID", null, doc.customizationId ?? UBL_CUSTOMIZATION_ID),
389
920
  el("cbc:ProfileID", null, doc.profileId ?? UBL_PROFILE_ID),
390
921
  el("cbc:ID", null, doc.id),
391
922
  el("cbc:IssueDate", null, doc.issueDate),
392
- // CreditNote has no DueDate element in the UBL sequence.
393
923
  !isCreditNote ? text("cbc:DueDate", doc.dueDate) : null,
924
+ // The CreditNote sequence puts BT-7 before the type code, Invoice after the note.
925
+ isCreditNote ? taxPointDate : null,
394
926
  typeCodeElement,
395
927
  text("cbc:Note", doc.note),
928
+ !isCreditNote ? taxPointDate : null,
396
929
  el("cbc:DocumentCurrencyCode", null, doc.currency),
930
+ text("cbc:TaxCurrencyCode", doc.taxCurrency),
931
+ text("cbc:AccountingCost", doc.accountingCost),
397
932
  text("cbc:BuyerReference", doc.buyerReference),
398
933
  invoicePeriod(doc.invoicePeriod),
934
+ orderReference(doc),
399
935
  doc.billingReference ? billingReference(doc.billingReference) : null,
936
+ documentReference("cac:DespatchDocumentReference", doc.despatchReference),
937
+ documentReference("cac:ReceiptDocumentReference", doc.receivingAdviceReference),
938
+ documentReference("cac:ContractDocumentReference", doc.contractReference),
400
939
  ...(doc.attachments ?? []).map(attachmentReference),
940
+ ...(doc.documentReferences ?? []).map((reference) =>
941
+ el("cac:AdditionalDocumentReference", null, [
942
+ el("cbc:ID", null, reference.id ?? ""),
943
+ text("cbc:DocumentDescription", reference.description),
944
+ ]),
945
+ ),
946
+ doc.invoicedObjectId !== undefined
947
+ ? typedDocumentReference(doc.invoicedObjectId, "130")
948
+ : null,
949
+ !isCreditNote && doc.tenderReference !== undefined
950
+ ? typedDocumentReference({ value: doc.tenderReference }, "50")
951
+ : null,
952
+ // UBL's CreditNote has no cac:ProjectReference; BIS uses type code 50.
953
+ isCreditNote && doc.projectReference !== undefined
954
+ ? typedDocumentReference({ value: doc.projectReference }, "50")
955
+ : null,
956
+ !isCreditNote
957
+ ? documentReference("cac:ProjectReference", doc.projectReference)
958
+ : null,
401
959
  el("cac:AccountingSupplierParty", null, [
402
960
  party(doc.seller, doc.seller.name ?? ""),
403
961
  ]),
404
962
  el("cac:AccountingCustomerParty", null, [
405
963
  party(doc.buyer, doc.buyer.name ?? ""),
406
964
  ]),
407
- // BT-20. In both the Invoice and CreditNote sequences PaymentTerms sits
408
- // after the parties (and PaymentMeans, which we do not emit) and before
409
- // TaxTotal.
965
+ doc.payee ? payeeParty(doc.payee) : null,
966
+ doc.taxRepresentative ? taxRepresentativeParty(doc.taxRepresentative) : null,
967
+ doc.delivery ? delivery(doc.delivery) : null,
968
+ ...means.map((entry, index) =>
969
+ paymentMeans(entry, index === 0 ? creditNoteDueDate : undefined),
970
+ ),
971
+ // BT-20. In both sequences PaymentTerms sits after PaymentMeans and
972
+ // before AllowanceCharge and TaxTotal.
410
973
  doc.paymentTermsNote !== undefined
411
974
  ? el("cac:PaymentTerms", null, [el("cbc:Note", null, doc.paymentTermsNote)])
412
975
  : null,
976
+ ...(doc.allowanceCharges ?? []).map((entry, index) =>
977
+ allowanceCharge(
978
+ entry,
979
+ doc.currency,
980
+ `allowanceCharges[${index}]`,
981
+ "document",
982
+ ),
983
+ ),
413
984
  el("cac:TaxTotal", null, [
414
985
  money("cbc:TaxAmount", doc.taxTotal.taxAmount ?? 0, doc.currency),
415
986
  ...doc.taxTotal.subtotals.map((subtotal, index) =>
416
987
  taxSubtotal(subtotal, doc.currency, index),
417
988
  ),
418
989
  ]),
990
+ // BT-111: a second TaxTotal carrying only the VAT total in BT-6.
991
+ doc.taxCurrency !== undefined
992
+ ? el("cac:TaxTotal", null, [
993
+ money(
994
+ "cbc:TaxAmount",
995
+ doc.taxTotal.taxAmountInTaxCurrency ?? 0,
996
+ doc.taxCurrency,
997
+ ),
998
+ ])
999
+ : null,
419
1000
  el("cac:LegalMonetaryTotal", null, legalMonetaryTotalChildren(doc)),
420
1001
  ...doc.lines.map((source) => line(source, doc.currency, doc.documentType)),
421
1002
  ];