@fin.cx/einvoice 8.1.0 → 8.2.1

package/ts/formats/utils/document.typecode.ts

@@ -7,6 +7,7 @@ import { EInvoiceFormatError } from '../../errors.js';
  */
 const DOCUMENT_TYPE_CODES: Record<TAccountingDocType, string> = {
   'invoice': '380',
+  'corrected-invoice': '384',
   'creditnote': '381',
   'debitnote': '383',
   'self-billed-invoice': '389',
@@ -42,9 +43,9 @@ export const getDocumentTypeCode = (accountingDocType: TAccountingDocType): stri
 };
 
 /**
- * The accounting document type of a decoded type code. 383 and 389 have a
- * type of their own; the remaining credit note related codes are credit
- * notes; everything else is an invoice, which covers 380, 384 and the other
+ * The accounting document type of a decoded type code. 383, 384 and 389 have
+ * a type of their own; the remaining credit note related codes are credit
+ * notes; everything else is an invoice, which covers 380 and the other
  * invoice related codes (326, 386, 875, ...) the envelope has no name for.
  * A missing or unlisted code stays an invoice as well: the document is an
  * invoice document, and reporting the code is the validators' job (BR-04,
@@ -55,6 +56,9 @@ export const getAccountingDocType = (typeCode: string): TAccountingDocType => {
   if (code === DOCUMENT_TYPE_CODES['debitnote']) {
     return 'debitnote';
   }
+  if (code === DOCUMENT_TYPE_CODES['corrected-invoice']) {
+    return 'corrected-invoice';
+  }
   if (code === DOCUMENT_TYPE_CODES['self-billed-invoice']) {
     return 'self-billed-invoice';
   }

package/ts/formats/utils/format.detector.ts

@@ -80,7 +80,9 @@ export class FormatDetector {
       );
       const customizationId = customizationIdMatch?.[1] ?? '';
 
-      if (/xrechnung/i.test(customizationId) || /urn:xoev-de:kosit:standard:xrechnung/i.test(customizationId)) {
+      // both identifier families: urn:xeinkauf.de:kosit:xrechnung_3.0 (XRechnung 3.0) and
+      // urn:xoev-de:kosit:standard:xrechnung_x.y (XRechnung 1.x and 2.x)
+      if (/xrechnung/i.test(customizationId)) {
         return InvoiceFormat.XRECHNUNG;
       }
       return InvoiceFormat.UBL;
@@ -133,10 +135,8 @@ export class FormatDetector {
     }
 
     // Check for obvious XRechnung indicators
-    if (
-      /xrechnung/i.test(sample) ||
-      /urn:xoev-de:kosit:standard:xrechnung/i.test(sample)
-    ) {
+    // covers both identifier families (urn:xeinkauf.de:kosit:xrechnung_, urn:xoev-de:kosit:standard:xrechnung_)
+    if (/xrechnung/i.test(sample)) {
       return InvoiceFormat.XRECHNUNG;
     }
 

package/ts/formats/utils/payment.terms.ts

@@ -0,0 +1,37 @@
+import { getWritableDueDate } from './date.value.js';
+
+/**
+ * The payment terms note (BT-20) the encoders write: the due date (BT-9) the
+ * document states, in the document language (German for `de`, English
+ * otherwise). It names the date rather than a count of days, so it reads
+ * correctly for every term:
+ * - a term of 0 days: "Zahlbar sofort" / "Payable immediately";
+ * - a later due date: "Zahlbar bis 04.10.2026" / "Payable by 2026-10-04";
+ * - an earlier due date, which is legitimate when the payment fell due before
+ *   the invoice was issued, as with an agreed advance payment or an invoice
+ *   issued after the contractual due date: "Fällig seit dem 03.09.2026" /
+ *   "Due since 2026-09-03".
+ * A term that is no whole number of days is refused by `getWritableDueDate`.
+ * @param issueTimestamp The issue date (BT-2)
+ * @param dueInDays The payment term in days, as the document states it
+ * @param language The document language
+ * @param targetFormat The format being written
+ */
+export const getPaymentTermsNote = (
+  issueTimestamp: unknown,
+  dueInDays: unknown,
+  language: string | undefined,
+  targetFormat: string,
+): string => {
+  const dueDate = getWritableDueDate(issueTimestamp, dueInDays, targetFormat);
+  const isoDate = dueDate.toISOString().slice(0, 10);
+  const german = (language ?? '').toLowerCase().startsWith('de');
+  const germanDate = `${isoDate.slice(8, 10)}.${isoDate.slice(5, 7)}.${isoDate.slice(0, 4)}`;
+  if (dueInDays === 0) {
+    return german ? 'Zahlbar sofort' : 'Payable immediately';
+  }
+  if ((dueInDays as number) > 0) {
+    return german ? `Zahlbar bis ${germanDate}` : `Payable by ${isoDate}`;
+  }
+  return german ? `Fällig seit dem ${germanDate}` : `Due since ${isoDate}`;
+};

package/ts/formats/utils/preceding.invoice.ts

@@ -0,0 +1,74 @@
+import type {
+  TAccountingDoc,
+  TAccountingDocType,
+  TCorrectedInvoiceReference,
+  TRelatedDocument,
+} from '../../interfaces/common.js';
+
+/**
+ * One preceding invoice reference (BG-3): the number of the preceding invoice
+ * (BT-25) and, when the document states it, its issue date (BT-26).
+ */
+export type TPrecedingInvoiceReference = TCorrectedInvoiceReference;
+
+/**
+ * The preceding invoice references (BG-3) an encoder writes for a document,
+ * taken only from what the document states:
+ * - a corrected invoice: the invoice it corrects (`correctedInvoice`);
+ * - a corrected invoice or a credit note: every related document with the
+ *   relation `'corrects'`.
+ * Other documents and other relations write none.
+ */
+export const getPrecedingInvoiceReferences = (
+  accountingDoc: TAccountingDoc,
+): TPrecedingInvoiceReference[] => {
+  const references: TPrecedingInvoiceReference[] = [];
+  if (accountingDoc.accountingDocType === 'corrected-invoice' && accountingDoc.correctedInvoice) {
+    references.push(accountingDoc.correctedInvoice);
+  }
+  if (
+    accountingDoc.accountingDocType === 'corrected-invoice' ||
+    accountingDoc.accountingDocType === 'creditnote'
+  ) {
+    for (const relatedDocument of accountingDoc.relatedDocuments ?? []) {
+      if (relatedDocument.relationType === 'corrects') {
+        references.push(
+          relatedDocument.issueDate === undefined
+            ? { documentId: relatedDocument.documentId }
+            : { documentId: relatedDocument.documentId, issueDate: relatedDocument.issueDate },
+        );
+      }
+    }
+  }
+  return references;
+};
+
+/**
+ * The envelope fields for the preceding invoice references a decoder read, the
+ * inverse of {@link getPrecedingInvoiceReferences}: on a corrected invoice the
+ * first reference is the invoice it corrects and further ones are related
+ * documents it corrects; on a credit note every reference is a related
+ * document it corrects. Other documents keep no reference, as before.
+ */
+export const getPrecedingInvoiceFields = (
+  accountingDocType: TAccountingDocType,
+  references: TPrecedingInvoiceReference[],
+): { correctedInvoice?: TCorrectedInvoiceReference; relatedDocuments?: TRelatedDocument[] } => {
+  const asRelated = (reference: TPrecedingInvoiceReference): TRelatedDocument => ({
+    relationType: 'corrects',
+    ...reference,
+  });
+  if (references.length === 0) {
+    return {};
+  }
+  if (accountingDocType === 'corrected-invoice') {
+    const [correctedInvoice, ...furtherReferences] = references;
+    return furtherReferences.length === 0
+      ? { correctedInvoice }
+      : { correctedInvoice, relatedDocuments: furtherReferences.map(asRelated) };
+  }
+  if (accountingDocType === 'creditnote') {
+    return { relatedDocuments: references.map(asRelated) };
+  }
+  return {};
+};

package/ts/formats/validation/integrated.validator.ts

@@ -11,6 +11,7 @@ import { EN16931BusinessRulesValidator } from './en16931.business-rules.validato
 import { CodeListValidator } from './codelist.validator.js';
 import type { ValidationResult, ValidationOptions, ValidationReport } from './validation.types.js';
 import type { EInvoice } from '../../einvoice.js';
+import { UBL_CUSTOMIZATION_IDS } from '../ubl/ubl.types.js';
 
 /**
  * Main validator that combines all validation capabilities
@@ -196,9 +197,11 @@ export class MainValidator {
     const profileId = invoice.metadata?.profileId || '';
     const customizationId = invoice.metadata?.customizationId || '';
     
+    // XRechnung 3.0 (its extension and CVD identifiers begin with it), the identifier
+    // family of XRechnung 1.x and 2.x, and any identifier naming XRechnung
     const xrechnungProfiles = [
-      'urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung',
-      'urn:cen.eu:en16931:2017#conformant#urn:xeinkauf.de:kosit:xrechnung',
+      UBL_CUSTOMIZATION_IDS.XRECHNUNG,
+      'urn:xoev-de:kosit:standard:xrechnung_',
       'xrechnung'
     ];
     

package/ts/formats/validation/xrechnung.validator.ts

@@ -8,6 +8,7 @@
 
 import type { EInvoice } from '../../einvoice.js';
 import type { ValidationResult } from './validation.types.js';
+import { UBL_CUSTOMIZATION_IDS } from '../ubl/ubl.types.js';
 
 /**
  * XRechnung-specific validator implementing German CIUS rules
@@ -62,10 +63,11 @@ export class XRechnungValidator {
     const customizationId = invoice.metadata?.customizationId || '';
     
     // XRechnung profile identifiers
+    // XRechnung 3.0 (its extension and CVD identifiers begin with it), the identifier
+    // family of XRechnung 1.x and 2.x, and any identifier naming XRechnung
     const xrechnungProfiles = [
-      'urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0',
-      'urn:cen.eu:en16931:2017#conformant#urn:xeinkauf.de:kosit:xrechnung_3.0',
-      'urn:cen.eu:en16931:2017:xrechnung',
+      UBL_CUSTOMIZATION_IDS.XRECHNUNG,
+      'urn:xoev-de:kosit:standard:xrechnung_',
       'xrechnung'
     ];
     

package/ts/index.ts

@@ -74,6 +74,9 @@ import { ZUGFeRDV1Decoder } from './formats/cii/zugferd/zugferd.v1.decoder.js';
 export type {
   // Common interfaces
   TInvoice,
+  TCorrectedInvoice,
+  TCorrectedInvoiceReference,
+  TInvoiceCorrection,
   TCreditNote,
   TDebitNote,
   TSelfBilledInvoice,

package/ts/interfaces/common.ts

@@ -83,11 +83,16 @@ export interface IPdf {
 // Re-export types from tsclass for convenience
 import type {
   TInvoice,
+  TCorrectedInvoice,
   TDebitNote,
   TSelfBilledInvoice,
 } from '@tsclass/tsclass/dist_ts/finance/index.js';
 
 export type { TInvoice } from '@tsclass/tsclass/dist_ts/finance/index.js';
+export type { TCorrectedInvoice } from '@tsclass/tsclass/dist_ts/finance/index.js';
+export type { TCorrectedInvoiceReference } from '@tsclass/tsclass/dist_ts/finance/index.js';
+export type { TInvoiceCorrection } from '@tsclass/tsclass/dist_ts/finance/index.js';
+export type { TRelatedDocument } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TCreditNote } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TDebitNote } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TSelfBilledInvoice } from '@tsclass/tsclass/dist_ts/finance/index.js';
@@ -100,7 +105,7 @@ export type { TAccountingDocEnvelope } from '@tsclass/tsclass/dist_ts/finance/in
  * `Invoice` root and the CII type codes of the invoice family. Only a credit
  * note has a document shape of its own.
  */
-export type TInvoiceDocument = TInvoice | TDebitNote | TSelfBilledInvoice;
+export type TInvoiceDocument = TInvoice | TCorrectedInvoice | TDebitNote | TSelfBilledInvoice;
 export type { TContact } from '@tsclass/tsclass/dist_ts/business/index.js';
 export type { TLetterEnvelope } from '@tsclass/tsclass/dist_ts/business/index.js';
 export type { TDocumentEnvelope } from '@tsclass/tsclass/dist_ts/business/index.js';