@financica/ubl 0.16.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.
package/src/types.ts CHANGED
@@ -1,142 +1,343 @@
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
+ /** An identifier with an optional `@schemeID`: BT-18, BT-71, BT-128, BT-157. */
64
+ export interface UblSchemedId {
65
+ value: string;
66
+ scheme?: string | undefined;
67
+ }
68
+
69
+ /** `cac:PartyIdentification/cbc:ID` (BT-29/BT-46) with its `@schemeID`. */
25
70
  export interface UblPartyIdentification {
26
71
  id: string;
27
72
  schemeId?: string | undefined;
28
73
  }
29
74
 
30
75
  export interface UblParty {
76
+ /** `cac:PartyName/cbc:Name` (BT-28/BT-45). */
31
77
  name?: string | undefined;
78
+ /** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). */
32
79
  registrationName?: string | undefined;
80
+ /** `cac:PartyLegalEntity/cbc:CompanyLegalForm` (BT-33). */
33
81
  companyLegalForm?: string | undefined;
82
+ /** `cac:PartyTaxScheme/cbc:CompanyID` (BT-31/BT-48) — the VAT identifier. */
34
83
  vatId?: string | undefined;
84
+ /** `cac:PartyTaxScheme/cac:TaxScheme/cbc:ID`, normally `VAT`. */
35
85
  taxSchemeId?: string | undefined;
36
- companyId?: string | undefined;
37
- companyIdSchemeId?: string | undefined;
38
- endpointId?: string | undefined;
39
- endpointSchemeId?: string | undefined;
86
+ /** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
87
+ companyId?: UblCompanyId | undefined;
88
+ /** `cbc:EndpointID` (BT-34/BT-49) — the Peppol routing identifier. */
89
+ endpoint?: UblEndpoint | undefined;
40
90
  partyIdentifications?: UblPartyIdentification[] | undefined;
41
91
  address?: UblAddress | undefined;
42
92
  contact?: UblContact | undefined;
43
93
  }
44
94
 
95
+ /**
96
+ * VAT category (`cac:ClassifiedTaxCategory` on a line, `cac:TaxCategory` in
97
+ * the VAT breakdown and on an allowance/charge). `id` is a UNCL5305 code:
98
+ * - `S` Standard rate
99
+ * - `Z` Zero-rated goods
100
+ * - `E` Exempt from VAT
101
+ * - `AE` VAT reverse charge
102
+ * - `O` Services outside scope of tax
103
+ * - `K` Intra-community supply
104
+ * - `G` Export outside the EU
105
+ */
106
+ export interface UblTaxCategory {
107
+ /** `cbc:ID` (BT-151/BT-118/BT-95/BT-102). */
108
+ id?: string | undefined;
109
+ /** `cbc:Percent` (BT-152/BT-119/BT-96/BT-103); absent for `O` and when the document omits it. */
110
+ percent?: number | undefined;
111
+ /** `cac:TaxScheme/cbc:ID`, normally `VAT`. */
112
+ schemeId?: string | undefined;
113
+ /** `cbc:TaxExemptionReason` (BT-120). Required by EN 16931 for non-charging categories. */
114
+ exemptionReason?: string | undefined;
115
+ /** `cbc:TaxExemptionReasonCode` (BT-121). */
116
+ exemptionReasonCode?: string | undefined;
117
+ }
118
+
45
119
  export interface UblItemProperty {
120
+ /** `cac:AdditionalItemProperty/cbc:Name` (BT-160). */
46
121
  name: string;
122
+ /** `cac:AdditionalItemProperty/cbc:Value` (BT-161). */
47
123
  value?: string | undefined;
48
124
  }
49
125
 
50
126
  export interface UblLine {
127
+ /** `cbc:ID` (BT-126) — line identifier. */
51
128
  id: string;
129
+ /** `cbc:Note` (BT-127). */
130
+ note?: string | undefined;
131
+ /** `cac:DocumentReference/cbc:ID` with `cbc:DocumentTypeCode` 130 (BT-128). */
132
+ objectIdentifier?: UblSchemedId | undefined;
133
+ /** `cac:OrderLineReference/cbc:LineID` (BT-132). */
134
+ orderLineReference?: string | undefined;
135
+ /** `cbc:AccountingCost` (BT-133). */
136
+ accountingCost?: string | undefined;
137
+ /** `cac:Item/cbc:Description` (BT-154). */
52
138
  description?: string | undefined;
139
+ /** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
53
140
  quantity?: number | undefined;
141
+ /** UN/ECE Rec 20 unit code (BT-130). */
54
142
  unitCode?: string | undefined;
143
+ /**
144
+ * Net price of one unit: `cac:Price/cbc:PriceAmount` (BT-146) divided by
145
+ * `cbc:BaseQuantity` (BT-149, default 1).
146
+ */
55
147
  unitPrice?: number | undefined;
148
+ /** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
56
149
  lineExtensionAmount?: number | undefined;
57
- taxPercent?: number | undefined;
150
+ /**
151
+ * `cac:Price/cbc:BaseQuantity` (BT-149) — the number of units BT-146
152
+ * covers. Omitted means 1. Set it when the net doesn't divide evenly into
153
+ * cents, so `quantity × unitPrice` reproduces the line net exactly
154
+ * (PEPPOL-EN16931-R120); see `deriveUnitPrice`. The serializer emits
155
+ * `PriceAmount = unitPrice × baseQuantity`.
156
+ */
157
+ baseQuantity?: number | undefined;
158
+ /** `cac:Item/cac:ClassifiedTaxCategory` (BT-151/BT-152). */
159
+ taxCategory?: UblTaxCategory | undefined;
160
+ /** Line VAT amount: `cac:TaxTotal/cbc:TaxAmount` when stated, else derived from the rate. */
58
161
  taxAmount?: number | undefined;
59
- taxCategoryId?: string | undefined;
60
- taxSchemeId?: string | undefined;
162
+ /** Line-level `cac:TaxTotal/cac:TaxSubtotal` (not used by BIS Billing, seen in the wild). */
61
163
  taxSubtotals?: UblTaxSubtotal[] | undefined;
164
+ /** Line-level allowances and charges (BG-27/BG-28); the price discount is `priceAllowance`. */
62
165
  allowanceCharges?: UblAllowanceCharge[] | undefined;
166
+ /**
167
+ * `cac:Price/cac:AllowanceCharge` (BT-147/BT-148): the discount between
168
+ * the gross unit price (`baseAmount`) and the net one (BT-146).
169
+ */
170
+ priceAllowance?: UblPriceAllowance | undefined;
171
+ /** Sum of line-level allowances plus the price allowance (absolute). */
63
172
  discountAmount?: number | undefined;
173
+ /** Sum of line-level charges (absolute). */
64
174
  chargeAmount?: number | undefined;
175
+ /** `cac:Item/cbc:Name` (BT-153). */
65
176
  itemName?: string | undefined;
177
+ /** `cac:Item/cac:SellersItemIdentification/cbc:ID` (BT-155). */
66
178
  sellersItemId?: string | undefined;
179
+ /** `cac:Item/cac:BuyersItemIdentification/cbc:ID` (BT-156). */
67
180
  buyersItemId?: string | undefined;
181
+ /** `cac:Item/cac:StandardItemIdentification/cbc:ID` (BT-157), `@schemeID` an ICD. */
182
+ standardItemId?: UblSchemedId | undefined;
183
+ /** `cac:Item/cac:CommodityClassification` (BT-158). */
184
+ commodityClassifications?: UblCommodityClassification[] | undefined;
185
+ /** `cac:Item/cac:OriginCountry/cbc:IdentificationCode` (BT-159). */
186
+ originCountryCode?: string | undefined;
68
187
  additionalItemProperties?: UblItemProperty[] | undefined;
69
- /** EN 16931 BT-134/BT-135: the line's own service period. */
188
+ /** `cac:InvoicePeriod` (BT-134/BT-135) — the line's own service period. */
70
189
  invoicePeriod?: UblInvoicePeriod | undefined;
71
190
  }
72
191
 
192
+ export interface UblPriceAllowance {
193
+ /** `cbc:Amount` (BT-147) — the discount per BT-149 units. */
194
+ amount?: number | undefined;
195
+ /** `cbc:BaseAmount` (BT-148) — the gross price per BT-149 units. */
196
+ baseAmount?: number | undefined;
197
+ /** `cbc:AllowanceChargeReason`, read when a document states one; not part of BIS and not written. */
198
+ reason?: string | undefined;
199
+ }
200
+
201
+ /** `cac:CommodityClassification/cbc:ItemClassificationCode` (BT-158) and its list. */
202
+ export interface UblCommodityClassification {
203
+ value: string;
204
+ /** `@listID` (BT-158-1), a UNTDID 7143 code. */
205
+ listId?: string | undefined;
206
+ /** `@listVersionID` (BT-158-2). */
207
+ listVersionId?: string | undefined;
208
+ }
209
+
73
210
  export interface UblAllowanceCharge {
211
+ /** `cbc:ChargeIndicator` — `true` for a charge, `false` for an allowance. */
74
212
  chargeIndicator: boolean;
213
+ /** `cbc:Amount` (BT-92/BT-99). */
75
214
  amount?: number | undefined;
215
+ /** `cbc:BaseAmount` (BT-93/BT-100). */
76
216
  baseAmount?: number | undefined;
217
+ /** `cbc:MultiplierFactorNumeric` (BT-94/BT-101). */
77
218
  multiplierFactorNumeric?: number | undefined;
219
+ /** `cbc:AllowanceChargeReason` (BT-97/BT-104). */
78
220
  reason?: string | undefined;
221
+ /** `cbc:AllowanceChargeReasonCode` (BT-98/BT-105). */
79
222
  reasonCode?: string | undefined;
80
- taxPercent?: number | undefined;
81
- taxCategoryId?: string | undefined;
82
- taxSchemeId?: string | undefined;
223
+ /** `cac:TaxCategory` (BT-95/BT-96, BT-102/BT-103). */
224
+ taxCategory?: UblTaxCategory | undefined;
83
225
  }
84
226
 
85
227
  export interface UblTaxSubtotal {
228
+ /** `cbc:TaxableAmount` (BT-116). */
86
229
  taxableAmount?: number | undefined;
230
+ /** `cbc:TaxAmount` (BT-117). */
87
231
  taxAmount?: number | undefined;
88
- taxPercent?: number | undefined;
89
- taxCategoryId?: string | undefined;
90
- taxSchemeId?: string | undefined;
91
- taxExemptionReason?: string | undefined;
232
+ /** `cac:TaxCategory` (BT-118/BT-119/BT-120/BT-121). */
233
+ category?: UblTaxCategory | undefined;
234
+ }
235
+
236
+ export interface UblTaxTotal {
237
+ /** `cac:TaxTotal/cbc:TaxAmount` (BT-110). Read as stated; never summed from the subtotals. */
238
+ taxAmount?: number | undefined;
239
+ /** `cac:TaxSubtotal` (BG-23) — the VAT breakdown. */
240
+ subtotals: UblTaxSubtotal[];
241
+ /** BT-111 — the VAT total in the VAT accounting currency (`UblInvoice.taxCurrency`). */
242
+ taxAmountInTaxCurrency?: number | undefined;
92
243
  }
93
244
 
94
245
  export interface UblMonetaryTotal {
246
+ /** BT-106 — sum of line net amounts. */
95
247
  lineExtensionAmount?: number | undefined;
248
+ /** BT-109 — total without VAT. */
96
249
  taxExclusiveAmount?: number | undefined;
250
+ /** BT-112 — total with VAT. */
97
251
  taxInclusiveAmount?: number | undefined;
252
+ /** BT-107 — sum of document-level allowances. */
98
253
  allowanceTotalAmount?: number | undefined;
254
+ /** BT-108 — sum of document-level charges. */
99
255
  chargeTotalAmount?: number | undefined;
256
+ /**
257
+ * BT-113 — sum of amounts paid in advance. **Gross (VAT-inclusive)**, since
258
+ * BR-CO-16 subtracts it directly from BT-112.
259
+ */
100
260
  prepaidAmount?: number | undefined;
261
+ /** BT-114 — rounding applied to the payable amount. */
101
262
  payableRoundingAmount?: number | undefined;
263
+ /**
264
+ * BT-115 — amount due for payment, i.e. the *outstanding* amount.
265
+ * BR-CO-16: `BT-115 = BT-112 − BT-113 + BT-114`.
266
+ */
102
267
  payableAmount?: number | undefined;
103
268
  }
104
269
 
105
270
  export interface UblPaymentMeans {
271
+ /** `cbc:PaymentMeansCode` (BT-81). */
106
272
  code?: string | undefined;
273
+ /** `cbc:PaymentMeansCode/@name` (BT-82). */
107
274
  codeName?: string | undefined;
275
+ /** `cbc:PaymentID` (BT-83). */
108
276
  paymentId?: string | undefined;
277
+ /** `cac:PayeeFinancialAccount/cbc:ID` (BT-84). */
109
278
  iban?: string | undefined;
279
+ /** `cac:FinancialInstitutionBranch/cbc:ID` (BT-86). */
110
280
  bic?: string | undefined;
281
+ /** `cac:PayeeFinancialAccount/cbc:Name` (BT-85). */
111
282
  accountName?: string | undefined;
283
+ /** `cac:PaymentMandate/cbc:ID` (BT-89). */
112
284
  mandateId?: string | undefined;
285
+ /** `cac:PaymentMandate/cac:PayerFinancialAccount/cbc:ID` (BT-91). */
286
+ debitedAccount?: string | undefined;
287
+ /** `cac:CardAccount/cbc:PrimaryAccountNumberID` (BT-87). */
288
+ cardNumber?: string | undefined;
289
+ /** `cac:CardAccount/cbc:HolderName` (BT-88). */
290
+ cardHolder?: string | undefined;
113
291
  }
114
292
 
293
+ /**
294
+ * A service period: BT-73/BT-74 on the document, BT-134/BT-135 on a line.
295
+ * Either bound may stand alone — UBL allows a half-open period — but a period
296
+ * with neither is omitted entirely.
297
+ */
115
298
  export interface UblInvoicePeriod {
299
+ /** `cbc:StartDate`, `YYYY-MM-DD`. */
116
300
  startDate?: string | undefined;
301
+ /** `cbc:EndDate`, `YYYY-MM-DD`, inclusive. */
117
302
  endDate?: string | undefined;
303
+ /** `cbc:DescriptionCode` (BT-8). */
118
304
  descriptionCode?: string | undefined;
119
305
  }
120
306
 
307
+ /** A supporting document (BG-24): embedded (`base64Content`) or external (`externalUri`). */
121
308
  export interface UblAttachment {
309
+ /** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
122
310
  id?: string | undefined;
311
+ /** `cbc:EmbeddedDocumentBinaryObject/@filename` (BT-125-2). */
123
312
  filename?: string | undefined;
313
+ /** MIME type (BT-125-1), e.g. `application/pdf`. */
124
314
  mimeCode?: string | undefined;
315
+ /** `cbc:DocumentDescription` (BT-123). */
125
316
  description?: string | undefined;
317
+ /** Base64-encoded document bytes (BT-125). */
126
318
  base64Content?: string | undefined;
319
+ /** `cac:ExternalReference/cbc:URI` (BT-124). */
127
320
  externalUri?: string | undefined;
128
321
  }
129
322
 
323
+ /** A text-only `cac:AdditionalDocumentReference` (no attachment). */
130
324
  export interface UblDocumentReference {
131
325
  id?: string | undefined;
132
326
  description?: string | undefined;
133
327
  }
134
328
 
135
329
  export interface UblDelivery {
330
+ /** `cbc:ActualDeliveryDate` (BT-72). */
136
331
  actualDeliveryDate?: string | undefined;
332
+ /** `cac:DeliveryLocation/cbc:ID` (BT-71). */
333
+ locationId?: UblSchemedId | undefined;
334
+ /** `cac:DeliveryLocation/cac:Address` (BG-15). */
137
335
  address?: UblAddress | undefined;
336
+ /** `cac:DeliveryParty/cac:PartyName/cbc:Name` (BT-70). */
337
+ partyName?: string | undefined;
138
338
  }
139
339
 
340
+ /** `cac:BillingReference/cac:InvoiceDocumentReference` (BT-25/BT-26). */
140
341
  export interface UblBillingReference {
141
342
  invoiceId?: string | undefined;
142
343
  invoiceIssueDate?: string | undefined;
@@ -144,33 +345,72 @@ export interface UblBillingReference {
144
345
 
145
346
  export interface UblInvoice {
146
347
  documentType: "Invoice" | "CreditNote";
348
+ /** `cbc:CustomizationID` (BT-24). The serializer defaults to Peppol BIS Billing 3.0. */
147
349
  customizationId?: string | undefined;
350
+ /** `cbc:ProfileID` (BT-23). The serializer defaults to the Peppol billing process. */
148
351
  profileId?: string | undefined;
352
+ /** Invoice / credit note number (BT-1). */
149
353
  id: string;
354
+ /** `cbc:InvoiceTypeCode` / `cbc:CreditNoteTypeCode` (BT-3). The serializer defaults to 380/381. */
150
355
  invoiceTypeCode?: string | undefined;
356
+ /** Issue date (BT-2), `YYYY-MM-DD`. */
151
357
  issueDate: string;
358
+ /** Payment due date (BT-9). Invoices only. */
152
359
  dueDate?: string | undefined;
360
+ /** `cbc:TaxPointDate` (BT-7). */
153
361
  taxPointDate?: string | undefined;
362
+ /** Document currency (BT-5). */
154
363
  currency: string;
364
+ /** `cbc:TaxCurrencyCode` (BT-6); requires `taxTotal.taxAmountInTaxCurrency` (BR-53). */
365
+ taxCurrency?: string | undefined;
366
+ /** `cbc:AccountingCost` (BT-19). */
367
+ accountingCost?: string | undefined;
368
+ /** Buyer reference (BT-10). */
155
369
  buyerReference?: string | undefined;
370
+ /** `cac:OrderReference/cbc:ID` (BT-13). */
156
371
  orderReference?: string | undefined;
372
+ /** `cac:OrderReference/cbc:SalesOrderID` (BT-14). */
157
373
  salesOrderId?: string | undefined;
374
+ /** `cac:ContractDocumentReference/cbc:ID` (BT-12). */
158
375
  contractReference?: string | undefined;
376
+ /**
377
+ * BT-11. `cac:ProjectReference/cbc:ID` on an invoice; a credit note has no
378
+ * such element, so there it is an additional document reference with
379
+ * `cbc:DocumentTypeCode` 50.
380
+ */
159
381
  projectReference?: string | undefined;
382
+ /** `cac:ReceiptDocumentReference/cbc:ID` (BT-15). */
383
+ receivingAdviceReference?: string | undefined;
384
+ /** `cac:DespatchDocumentReference/cbc:ID` (BT-16). */
385
+ despatchReference?: string | undefined;
386
+ /** BT-17, an additional document reference with `cbc:DocumentTypeCode` 50. Invoices only. */
387
+ tenderReference?: string | undefined;
388
+ /** BT-18, an additional document reference with `cbc:DocumentTypeCode` 130. */
389
+ invoicedObjectId?: UblSchemedId | undefined;
390
+ /** For credit notes: the referenced original invoice (BT-25). */
160
391
  billingReference?: UblBillingReference | undefined;
161
392
  seller: UblParty;
162
393
  buyer: UblParty;
394
+ /** `cac:PayeeParty` (BG-10): name, identification and legal entity id only. */
395
+ payee?: UblParty | undefined;
396
+ /** `cac:TaxRepresentativeParty` (BG-11): name, VAT id and address only. */
397
+ taxRepresentative?: UblParty | undefined;
163
398
  delivery?: UblDelivery | undefined;
164
399
  lines: UblLine[];
165
- taxSubtotals: UblTaxSubtotal[];
400
+ taxTotal: UblTaxTotal;
166
401
  monetaryTotal: UblMonetaryTotal;
402
+ /** The first entry of `paymentMeansList`. */
167
403
  paymentMeans?: UblPaymentMeans | undefined;
168
404
  paymentMeansList?: UblPaymentMeans[] | undefined;
405
+ /** Invoicing period (BT-73/BT-74). */
169
406
  invoicePeriod?: UblInvoicePeriod | undefined;
407
+ /** Free-text note (BT-22). */
170
408
  note?: string | undefined;
409
+ /** Payment terms note (BT-20, `cac:PaymentTerms/cbc:Note`). */
171
410
  paymentTermsNote?: string | undefined;
172
411
  attachments?: UblAttachment[] | undefined;
173
412
  documentReferences?: UblDocumentReference[] | undefined;
413
+ /** Document-level allowances and charges (BG-20/BG-21). */
174
414
  allowanceCharges?: UblAllowanceCharge[] | undefined;
175
415
  }
176
416
 
@@ -1,179 +0,0 @@
1
- /**
2
- * A vendor-neutral model of a Peppol BIS Billing 3.0 document.
3
- *
4
- * This is the intermediate representation the builders in `../` (and, for
5
- * Stripe data, `stripe-ubl`) produce; `./serialize.ts` turns it into UBL XML.
6
- * It is deliberately a thin, construction-oriented mirror of the UBL fields we
7
- * populate — not a full UBL object graph.
8
- */
9
-
10
- export interface UblAddress {
11
- /** `cbc:StreetName` (BT-35). */
12
- street: string | null;
13
- /** `cbc:AdditionalStreetName` (BT-36). */
14
- additionalStreet: string | null;
15
- /** `cbc:CityName` (BT-37). */
16
- city: string | null;
17
- /** `cbc:PostalZone` (BT-38). */
18
- postalZone: string | null;
19
- /** `cbc:CountrySubentity` (BT-39). */
20
- countrySubentity: string | null;
21
- /** `cac:Country/cbc:IdentificationCode` (BT-40) — ISO 3166-1 alpha-2. */
22
- countryCode: string | null;
23
- }
24
-
25
- /** Peppol participant identifier, e.g. scheme `0208`, value `0800279001`. */
26
- export interface UblEndpoint {
27
- scheme: string;
28
- value: string;
29
- }
30
-
31
- /** Legal registration identifier, e.g. a Belgian enterprise number. */
32
- export interface UblCompanyId {
33
- value: string;
34
- /** ICD scheme (e.g. `0208` for the Belgian CBE), when known. */
35
- scheme?: string | null;
36
- }
37
-
38
- export interface UblParty {
39
- /** `cbc:EndpointID` (BT-49/BT-34) — the Peppol routing identifier. */
40
- endpoint: UblEndpoint | null;
41
- /** `cac:PartyName/cbc:Name` (BT-27/BT-44). */
42
- name: string;
43
- address: UblAddress;
44
- /** `cac:PartyTaxScheme/cbc:CompanyID` with `VAT` scheme (BT-31/BT-48). */
45
- vatNumber: string | null;
46
- /** `cac:PartyLegalEntity/cbc:RegistrationName` (BT-27/BT-44). Defaults to `name`. */
47
- legalName: string | null;
48
- /** `cac:PartyLegalEntity/cbc:CompanyID` (BT-30/BT-47). */
49
- companyId: UblCompanyId | null;
50
- }
51
-
52
- /**
53
- * VAT breakdown category. `id` is a UNCL5305 code:
54
- * - `S` Standard rate
55
- * - `Z` Zero-rated goods
56
- * - `E` Exempt from VAT
57
- * - `AE` VAT reverse charge
58
- * - `O` Services outside scope of tax
59
- * - `K` Intra-community supply
60
- * - `G` Export outside the EU
61
- */
62
- export interface UblTaxCategory {
63
- id: string;
64
- percent: number;
65
- /** Required by EN 16931 (BR-E-10/BR-AE-10/…) for non-`S`/`Z` categories. */
66
- exemptionReason?: string | null | undefined;
67
- }
68
-
69
- export interface UblLine {
70
- /** `cbc:ID` (BT-126) — line identifier. */
71
- id: string;
72
- /** `cac:Item/cbc:Name` (BT-153). */
73
- name: string;
74
- /** `cbc:InvoicedQuantity` / `cbc:CreditedQuantity` (BT-129). */
75
- quantity: number;
76
- /** UN/ECE Rec 20 unit code (BT-130). */
77
- unitCode: string;
78
- /** `cbc:LineExtensionAmount` (BT-131) — net of VAT, after line discounts. */
79
- lineExtensionAmount: number;
80
- /** `cac:Price/cbc:PriceAmount` (BT-146) — net unit price. */
81
- priceAmount: number;
82
- /**
83
- * `cac:Price/cbc:BaseQuantity` (BT-149) — the number of units `priceAmount`
84
- * covers. Omitted means 1. Set it when the net doesn't divide evenly into
85
- * cents, so `quantity × (priceAmount ÷ baseQuantity)` reproduces the line
86
- * net exactly (PEPPOL-EN16931-R120); see `deriveUnitPrice`.
87
- */
88
- baseQuantity?: number | undefined;
89
- /** `cac:InvoicePeriod` (BT-134/BT-135) — the line's own service period. */
90
- invoicePeriod?: UblPeriod | null;
91
- taxCategory: UblTaxCategory;
92
- }
93
-
94
- export interface UblTaxSubtotal {
95
- /** `cbc:TaxableAmount` (BT-116). */
96
- taxableAmount: number;
97
- /** `cbc:TaxAmount` (BT-117). */
98
- taxAmount: number;
99
- category: UblTaxCategory;
100
- }
101
-
102
- export interface UblTaxTotal {
103
- /** `cbc:TaxAmount` (BT-110) — sum of subtotal tax amounts. */
104
- taxAmount: number;
105
- subtotals: UblTaxSubtotal[];
106
- }
107
-
108
- export interface UblMonetaryTotal {
109
- /** BT-106 — sum of line net amounts. */
110
- lineExtensionAmount: number;
111
- /** BT-109 — total without VAT. */
112
- taxExclusiveAmount: number;
113
- /** BT-112 — total with VAT. */
114
- taxInclusiveAmount: number;
115
- /**
116
- * BT-113 — sum of amounts paid in advance. **Gross (VAT-inclusive)**, since
117
- * BR-CO-16 subtracts it directly from BT-112. Omitted when absent or zero.
118
- */
119
- prepaidAmount?: number;
120
- /** BT-114 — rounding applied to the payable amount. Omitted when absent or zero. */
121
- payableRoundingAmount?: number;
122
- /**
123
- * BT-115 — amount due for payment, i.e. the *outstanding* amount.
124
- * BR-CO-16: `BT-115 = BT-112 − BT-113 + BT-114`.
125
- */
126
- payableAmount: number;
127
- }
128
-
129
- /** An embedded supporting document (BG-24), e.g. the rendered PDF. */
130
- export interface UblAttachment {
131
- /** `cac:AdditionalDocumentReference/cbc:ID` (BT-122). */
132
- id: string;
133
- /** `cbc:EmbeddedDocumentBinaryObject/@filename`. */
134
- filename: string;
135
- /** MIME type, e.g. `application/pdf`. */
136
- mimeCode: string;
137
- /** Base64-encoded document bytes. */
138
- base64: string;
139
- }
140
-
141
- /**
142
- * A service period: BT-73/BT-74 on the document, BT-134/BT-135 on a line.
143
- * Either bound may stand alone — UBL allows a half-open period — but a period
144
- * with neither is omitted entirely.
145
- */
146
- export interface UblPeriod {
147
- /** `YYYY-MM-DD`. */
148
- startDate: string | null;
149
- /** `YYYY-MM-DD`, inclusive. */
150
- endDate: string | null;
151
- }
152
-
153
- export interface UblDocument {
154
- documentType: "invoice" | "creditNote";
155
- /** Invoice / credit note number (BT-1). */
156
- id: string;
157
- /** Issue date (BT-2), `YYYY-MM-DD`. */
158
- issueDate: string;
159
- /** Payment due date (BT-9). Invoices only. */
160
- dueDate: string | null;
161
- /** Free-text note (BT-22). */
162
- note: string | null;
163
- /** Payment terms note (BT-20, `cac:PaymentTerms/cbc:Note`). */
164
- paymentTermsNote?: string | null;
165
- /** Document currency (BT-5). */
166
- currency: string;
167
- /** Buyer reference (BT-10). */
168
- buyerReference: string | null;
169
- /** Invoicing period (BT-73/BT-74). */
170
- invoicePeriod?: UblPeriod | null;
171
- /** For credit notes: the referenced original invoice number (BT-25). */
172
- precedingInvoiceId: string | null;
173
- supplier: UblParty;
174
- customer: UblParty;
175
- lines: UblLine[];
176
- taxTotal: UblTaxTotal;
177
- monetaryTotal: UblMonetaryTotal;
178
- attachments: UblAttachment[];
179
- }