@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/CHANGELOG.md +7 -0
- package/README.md +20 -25
- package/dist/build/index.d.ts +58 -193
- package/dist/build/index.d.ts.map +1 -1
- package/dist/build/index.js +229 -130
- package/dist/build/index.js.map +1 -1
- package/dist/errors-C9YYJ1xR.js +33 -0
- package/dist/errors-C9YYJ1xR.js.map +1 -0
- package/dist/index.d.ts +2 -224
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +78 -55
- package/dist/index.js.map +1 -1
- package/dist/types-DossV2at.d.ts +389 -0
- package/dist/types-DossV2at.d.ts.map +1 -0
- package/package.json +1 -1
- package/src/build/address.ts +9 -10
- package/src/build/attachment.ts +13 -9
- package/src/build/identifiers.ts +28 -28
- package/src/build/index.ts +19 -9
- package/src/build/numeric.ts +17 -11
- package/src/build/party.ts +16 -14
- package/src/build/tax-category.ts +5 -4
- package/src/build/tax-totals.ts +31 -20
- package/src/build/ubl/serialize.ts +281 -102
- package/src/build/utils.ts +12 -4
- package/src/errors.ts +16 -0
- package/src/index.ts +5 -1
- package/src/normalize.ts +18 -17
- package/src/parser.ts +85 -30
- package/src/types.ts +187 -23
- package/src/build/ubl/types.ts +0 -179
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.
|
|
114
|
-
tax_category_id: normalizeText(charge.
|
|
115
|
-
tax_scheme_id: normalizeText(charge.
|
|
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
|
|
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 (
|
|
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.
|
|
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.
|
|
232
|
-
tax_scheme_id: normalizeText(line.
|
|
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.
|
|
337
|
-
endpoint_scheme_id: normalizeText(ubl.seller.
|
|
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.
|
|
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.
|
|
349
|
-
endpoint_scheme_id: normalizeText(ubl.buyer.
|
|
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.
|
|
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.
|
|
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:
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
211
|
-
return
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
259
|
-
|
|
260
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
1
|
+
// --- UBL document model ---
|
|
2
2
|
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
//
|
|
8
|
-
//
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
81
|
-
|
|
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
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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
|
-
|
|
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
|
|