@fin.cx/tax 1.1.0 → 2.1.0

package/ts/zm.ts

@@ -0,0 +1,166 @@
+/**
+ * The Zusammenfassende Meldung (§ 18a UStG): its lines, and the CSV the
+ * ELSTER (or BZSt-Online-Portal) online form imports. Pure; the caller
+ * decides which supplies of which period go in (§ 18a Abs. 1, 2, 8 UStG) and
+ * transmits the form itself, authenticated, as § 18a requires.
+ *
+ * Sources, read 2026-09-25:
+ * - ELSTER, "Import von Meldelisten zur Zusammenfassenden Meldung"
+ *   (helpGlobal `zmdo_import_eop`, CSV version 3.0) and the general
+ *   "Anleitung zur Erstellung von CSV-Dateien für die Importfunktion":
+ *   UTF-8; line 1 `#v3.0`; the form's example adds `#ve3.2.1`; one line of
+ *   field names; then the lines, one per record "Meldezeilen (Satzart 1)":
+ *   USt-IdNr. AN(7,14) beginning with a country code of the list; Summe
+ *   (Euro) N(11), "eine ganze Zahl", minus allowed; Art der Leistung A(1),
+ *   `L` innergemeinschaftliche Lieferung, `S` sonstige Leistung, `D`
+ *   Dreiecksgeschäft. At most 1 500 lines. The example separates its lines
+ *   with a line feed and its fields with `,`.
+ * - BZSt, "Zusammenfassende Meldung - Fragen und Antworten"
+ *   (bzst.de …/ZusammenfassendeMeldung/FAQ/faq_zm.html, read 2026-09-27),
+ *   Brexit: a Northern Irish business has a VAT ID with `XI`; the ZM states
+ *   the intra-Community supplies, triangular trades and § 6b transfers to it,
+ *   while services to recipients in Northern Ireland follow the rules for the
+ *   third-country territory and are not reported (Art. 8 of the Protocol on
+ *   Ireland/Northern Ireland covers goods only).
+ * - BZSt, "Anleitung zur Zusammenfassenden Meldung" (USt ZM 1/2021): one line
+ *   per recipient and kind in a period, the bases summed (Tz. 8, 11); a later
+ *   change of the base netted into the period of the change, possibly
+ *   negative (Tz. 10); no "Nullmeldungen" (III.1); a correction states the
+ *   correct totals, and `0` to storno a line (Tz. 12.2, 12.3).
+ */
+import type { TCents } from '@fin.cx/calculation';
+
+/** `L` innergemeinschaftliche Warenlieferung, `S` sonstige Leistung (§ 3a Abs. 2), `D` Dreiecksgeschäft (§ 25b Abs. 2) */
+export type TZmKind = 'L' | 'S' | 'D';
+
+/** One supply (or a later change of its base) of the period: the recipient's VAT ID, its kind, the base in euro cents */
+export interface IZmSupplyInput {
+  vatId: string;
+  kind: TZmKind;
+  /** signed: a later reduction of the base is negative */
+  baseCents: TCents;
+}
+
+/** One line of the report: the recipient, the kind, the summed base in euro cents */
+export interface IZmLine {
+  vatId: string;
+  kind: TZmKind;
+  baseCents: TCents;
+}
+
+export interface IZmCsv {
+  text: string;
+  /** the text as UTF-8, as the import requires */
+  bytes: Uint8Array;
+  lineCount: number;
+}
+
+/** The country codes the ZM takes (ELSTER, "Liste der Länderkennzeichen"); `GB` only for periods before 2021, so not here. */
+export const ZM_COUNTRY_CODES: readonly string[] = [
+  'AT', 'BE', 'BG', 'CY', 'CZ', 'DK', 'EE', 'EL', 'ES', 'FI', 'FR', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'PL', 'PT', 'RO', 'SE', 'SI', 'SK', 'XI',
+];
+
+export const ZM_MAX_LINES = 1500;
+
+/** The CSV version lines and the field names, as the form's example gives them. */
+export const ZM_CSV_HEAD: readonly string[] = [
+  '#v3.0',
+  '#ve3.2.1',
+  'Umsatzsteuer-Identifikationsnummer (USt-IdNr.),Summe (Euro),Art der Leistung',
+];
+
+/**
+ * How a sum with cents becomes the whole euros the CSV's "Summe (Euro)"
+ * takes. No source read states it (ELSTER: "eine ganze Zahl"; ELMA5: "in Euro
+ * ohne Cent"; the paper form: "volle EUR | Ct"). The cents are dropped toward
+ * zero, as the UStVA drops those of its bases ("in vollen Euro (ohne
+ * Centbeträge)", Anleitung zur Umsatzsteuer-Voranmeldung 2026), so that the
+ * ZM and the UStVA's Kz 41 and Kz 21, which the BZSt compares, are cut alike.
+ * This is a recorded decision of 2026-09-27, pending the tax advisor's
+ * confirmation; it is not a rule a source states.
+ */
+export const ZM_EUROS_RULE =
+  'the cents of each line\'s sum are dropped toward zero, as the UStVA drops those of its bases (a recorded decision of 2026-09-27, pending the tax advisor\'s confirmation; no source states the rule)';
+
+/**
+ * The whole euros of a sum in cents, as the CSV's "Summe (Euro)" takes them:
+ * the cents dropped toward zero (`ZM_EUROS_RULE`), so 2 000,50 € is 2000 and
+ * -2 000,50 € is -2000. At most 11 digits (N(11)).
+ */
+export function zmEurosOf(centsArg: TCents): number {
+  if (!Number.isSafeInteger(centsArg)) {
+    throw new Error(`the ZM sum must be an integer number of cents, got ${centsArg}`);
+  }
+  // Math.trunc of a small negative sum is -0, which is written "0"; `+ 0` makes it a plain 0
+  const euros = Math.trunc(centsArg / 100) + 0;
+  if (String(Math.abs(euros)).length > 11) {
+    throw new Error(`the ZM sum has at most 11 digits (N(11)), got ${euros} euros`);
+  }
+  return euros;
+}
+
+/**
+ * A recipient's VAT ID as the form takes it: upper case, without spaces, the
+ * country code first (`GR` written `EL`, as the list has it); 7 to 14
+ * characters of letters, digits, `+` and `*`; a country code of the list.
+ */
+export function normalizeZmVatId(valueArg: string): string {
+  let id = String(valueArg ?? '').replace(/\s+/g, '').toUpperCase();
+  if (id.startsWith('GR')) {
+    id = `EL${id.slice(2)}`;
+  }
+  if (id.length < 7 || id.length > 14) {
+    throw new Error(`a ZM VAT ID has 7 to 14 characters, got '${id}'`);
+  }
+  if (!/^[A-Z]{2}[A-Z0-9+*]+$/.test(id)) {
+    throw new Error(`a ZM VAT ID has a country code and then letters, digits, + or *, got '${id}'`);
+  }
+  if (!ZM_COUNTRY_CODES.includes(id.slice(0, 2))) {
+    throw new Error(`'${id.slice(0, 2)}' is no country code the ZM takes (another member state's, or XI)`);
+  }
+  return id;
+}
+
+/** The lines of a period: one per recipient VAT ID and kind, in the order they first appear, the bases summed. */
+export function aggregateZmLines(suppliesArg: readonly IZmSupplyInput[]): IZmLine[] {
+  const lines = new Map<string, IZmLine>();
+  for (const supply of suppliesArg) {
+    if (supply.kind !== 'L' && supply.kind !== 'S' && supply.kind !== 'D') {
+      throw new Error(`a ZM kind is L, S or D, got '${String(supply.kind)}'`);
+    }
+    if (!Number.isSafeInteger(supply.baseCents)) {
+      throw new Error(`a ZM base must be an integer number of cents, got ${supply.baseCents}`);
+    }
+    const vatId = normalizeZmVatId(supply.vatId);
+    if (vatId.startsWith('XI') && supply.kind === 'S') {
+      throw new Error(
+        `'${vatId}' is a recipient in Northern Ireland, which is Community territory for goods only: a service to it follows the rules for the third-country territory and is not reported in the ZM (BZSt, Zusammenfassende Meldung - Fragen und Antworten, Brexit)`,
+      );
+    }
+    const key = `${vatId}|${supply.kind}`;
+    const line = lines.get(key) ?? { vatId, kind: supply.kind, baseCents: 0 };
+    line.baseCents += supply.baseCents;
+    lines.set(key, line);
+  }
+  return [...lines.values()];
+}
+
+/**
+ * The CSV of one report. An original report leaves out a line that nets to
+ * zero and refuses to be written with no line left (no "Nullmeldung"); a
+ * correction keeps a `0` line, which stornos what was reported under it.
+ * Each line's sum is cut to whole euros by `zmEurosOf`. Refused beyond 1 500
+ * lines.
+ */
+export function writeZmCsv(linesArg: readonly IZmLine[], optionsArg: { purpose: 'original' | 'correction' }): IZmCsv {
+  const lines = aggregateZmLines(linesArg).filter((lineArg) => optionsArg.purpose === 'correction' || lineArg.baseCents !== 0);
+  if (lines.length === 0) {
+    throw new Error('a ZM with no line is no report: "Nullmeldungen" are not given (BZSt Anleitung III.1)');
+  }
+  if (lines.length > ZM_MAX_LINES) {
+    throw new Error(`the ZM online form imports at most ${ZM_MAX_LINES} lines, got ${lines.length}`);
+  }
+  const rows = lines.map((lineArg) => `${lineArg.vatId},${zmEurosOf(lineArg.baseCents)},${lineArg.kind}`);
+  const text = [...ZM_CSV_HEAD, ...rows].join('\n') + '\n';
+  return { text, bytes: new TextEncoder().encode(text), lineCount: rows.length };
+}