@fin.cx/chartdata 2.17.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/chartdata",
-  "version": "2.17.0",
+  "version": "3.1.0",
   "private": false,
   "description": "Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, UStVA-Kennzahl and Anlage EÜR mappings",
   "main": "dist_ts/index.js",

package/readme.md

@@ -33,6 +33,11 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
   accounts), the costs of a sale, write-downs and write-ups, the taxes withheld
   from their income and the margin interest, listed per chart by
   `getAccountsBySecuritiesRole` and found one by one with `getSecuritiesAccount`
+- Payroll accounts with their payroll role (`payrollRole`): the pay and the
+  flat wage taxes (GuV 6a), the employer's contributions (GuV 6b), the debts
+  of a payroll until they are paid, the company-car benefit and the levy
+  refunds, and the clearing account, one account per role, found with
+  `getPayrollAccount`
 - DATEV's mark "HB" (`commercialOnly`): an account posted in the commercial
   balance sheet only
 - The tax rule an income or expense account is kept for (`taxRule`):
@@ -159,6 +164,59 @@ compensations paid on securities sold short. Their roles (`options_held`,
 `compensation_paid`) name no account of the standard charts: the books give
 them an individual account, or book them on the account of their position.
 
+### Payroll
+
+A payroll run finds its accounts by the payroll role; within a chart each role
+names one account, and every role has its account in both standard charts.
+DATEV states each account's position beside it: the pay under "Löhne und
+Gehälter" (GuV 6a, § 275 Abs. 2 Nr. 6 a HGB), the employer's contributions
+under "Soziale Abgaben und Aufwendungen für Altersversorgung und für
+Unterstützung" (GuV 6b). DATEV's collective accounts (SKR03 4100, SKR04 6000
+and 6100) keep their positions and take no role.
+
+```typescript
+import { getPayrollAccount } from '@fin.cx/chartdata';
+
+getPayrollAccount('SKR03', 2026, 'salaries')?.accountNumber; // '4120' Gehälter
+getPayrollAccount('SKR04', 2026, 'wage_tax')?.accountNumber; // '3730' Verbindlichkeiten aus Lohn- und Kirchensteuer
+getPayrollAccount('SKR04', 2026, 'company_car_benefit')?.ustva; // { kennzahl: 81, role: 'base' }
+```
+
+| Role | What it books | SKR03 | SKR04 |
+| --- | --- | --- | --- |
+| `wages` | Löhne (GuV 6a) | 4110 | 6010 |
+| `salaries` | Gehälter (GuV 6a) | 4120 | 6020 |
+| `managing_director_salaries` | a GmbH's shareholder-managing directors (GuV 6a) | 4124 | 6024 |
+| `temporary_wages` | Aushilfslöhne (GuV 6a) | 4190 | 6030 |
+| `minijob_wages` | Löhne für Minijobs (GuV 6a) | 4195 | 6035 |
+| `benefits_in_kind` | Sachzuwendungen und Dienstleistungen an Arbeitnehmer (GuV 6a) | 4152 | 6072 |
+| `capital_formation_benefits` | vermögenswirksame Leistungen (GuV 6a) | 4170 | 6080 |
+| `commuting_allowances` | Fahrtkostenerstattung Wohnung/Arbeitsstätte (GuV 6a) | 4175 | 6090 |
+| `minijob_flat_tax` | the flat tax of a Minijob (GuV 6a) | 4194 | 6036 |
+| `employee_flat_tax` | the flat tax for employees (GuV 6a) | 4198 | 6039 |
+| `temporary_flat_tax` | the flat tax for temporary staff (GuV 6a) | 4199 | 6040 |
+| `employer_social_security` | the employer's contributions and the levies U1, U2, U3 (GuV 6b) | 4130 | 6110 |
+| `minijob_social_security` | the flat contributions of a Minijob (GuV 6b) | 4144 | 6171 |
+| `accident_insurance` | Berufsgenossenschaft (GuV 6b) | 4138 | 6120 |
+| `pension` | Aufwendungen für Altersversorgung (GuV 6b) | 4165 | 6140 |
+| `pension_flat_tax` | the flat tax on such benefits, Direktversicherungen (GuV 6b) | 4167 | 6147 |
+| `company_car_benefit` | the private use of a company car, 19 % VAT, UStVA Kz 81 (GuV 4) | 8611 | 4947 |
+| `levy_refunds` | Erstattungen nach dem Aufwendungsausgleichsgesetz (GuV 4) | 2749 | 4972 |
+| `levy_refund_claims` | the claim on the health insurer for them | 1520 | 1369 |
+| `net_pay` | the net pay owed | 1740 | 3720 |
+| `wage_tax` | wage tax, church tax and Solidaritätszuschlag owed | 1741 | 3730 |
+| `social_security` | the contributions owed | 1742 | 3740 |
+| `employee_withholdings` | what is withheld from an employee for another (a garnishment) | 1748 | 3725 |
+| `capital_formation_payable` | the savings an employee's contract receives | 1750 | 3770 |
+| `estimated_contributions` | the contributions estimated when due (§ 23 Abs. 1 SGB IV) | 1759 | 3759 |
+| `clearing` | the Lohn- und Gehaltsverrechnungskonto | 1755 | 3790 |
+
+In the Anlage EÜR every payroll expense is Zeile 31 (Kz 120), "einschließlich
+der gezahlten Lohnsteuer (auch Pauschalsteuer nach § 37b EStG) und anderer
+Nebenkosten" (Anleitung 2026); the company-car benefit is a taxable receipt
+(Kz 112), the levy refunds a non-taxable one (Kz 103). An individual account
+takes no payroll role: a role names the DATEV account.
+
 ### Individual accounts
 
 The books may set up accounts of their own (Individualkonten) on the numbers
@@ -216,8 +274,8 @@ books.getMappingCoverage(usedAccountNumbers, 'hgb275');
 
 A `BooksChart` is a chart (`IChart`) with the lookups of the chart over the
 DATEV accounts and the books' own: `getAccount`, `getAccountsByRole`,
-`getAccountsBySecuritiesRole`, `getSecuritiesAccount`, `getMappingCoverage`,
-`getEuerLines`.
+`getAccountsBySecuritiesRole`, `getSecuritiesAccount`, `getPayrollAccount`,
+`getMappingCoverage`, `getEuerLines`.
 
 `INDIVIDUAL_ACCOUNT_TEMPLATES` suggests the parent and name of the results the
 law keeps apart: the gains and losses of Termingeschäfte, which § 15 Abs. 4

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/chartdata',
-  version: '2.17.0',
+  version: '3.1.0',
   description: 'Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, UStVA-Kennzahl and Anlage EÜR mappings'
 }

package/ts/chartdata.hgb.ts

@@ -65,7 +65,9 @@ export const HGB_275_GKV_POSITIONS: IHgbPosition[] = [
   { key: 'GuV 3', label: 'Andere aktivierte Eigenleistungen' },
   { key: 'GuV 4', label: 'Sonstige betriebliche Erträge' },
   { key: 'GuV 5', label: 'Materialaufwand' },
-  { key: 'GuV 6', label: 'Personalaufwand' },
+  // Nr. 6 Personalaufwand, by its two parts
+  { key: 'GuV 6a', label: 'Löhne und Gehälter' },
+  { key: 'GuV 6b', label: 'Soziale Abgaben und Aufwendungen für Altersversorgung und für Unterstützung' },
   { key: 'GuV 7', label: 'Abschreibungen' },
   { key: 'GuV 8', label: 'Sonstige betriebliche Aufwendungen' },
   { key: 'GuV 9', label: 'Erträge aus Beteiligungen' },

package/ts/chartdata.individual.ts

@@ -10,6 +10,7 @@ import type {
   TChartName,
   TEuerAccountLines,
   TMappingDimension,
+  TPayrollRole,
   TSecuritiesRole,
   TTaxRule,
 } from './chartdata.types.js';
@@ -304,6 +305,11 @@ export class BooksChart implements IChart {
     return this.getAccountsBySecuritiesRole(roleArg).find((account) => account.taxRule === taxRuleArg) ?? null;
   }
 
+  /** The one account of the books that books the payroll role, or `null`; an individual account takes none. */
+  public getPayrollAccount(roleArg: TPayrollRole): IChartAccount | null {
+    return this.accounts.find((account) => account.payrollRole === roleArg) ?? null;
+  }
+
   public getMappingCoverage(usedAccountsArg: string[], dimensionArg: TMappingDimension): IMappingCoverage {
     return mappingCoverageOf(this.accounts, usedAccountsArg, dimensionArg);
   }

package/ts/chartdata.lookup.ts

@@ -7,6 +7,7 @@ import type {
   TChartName,
   TEuerAccountLines,
   TMappingDimension,
+  TPayrollRole,
   TSecuritiesRole,
   TTaxRule,
 } from './chartdata.types.js';
@@ -113,6 +114,14 @@ export function getSecuritiesAccount(
   return getAccountsBySecuritiesRole(chart, year, role).find((account) => account.taxRule === taxRule) ?? null;
 }
 
+/**
+ * The one account of a chart that books the payroll role (`IChartAccount.payrollRole`), or `null` where the chart
+ * keeps none for it. Throws for unknown chart/year combinations, as `getChart`.
+ */
+export function getPayrollAccount(chart: TChartName, year: number, role: TPayrollRole): IChartAccount | null {
+  return getChart(chart, year).accounts.find((account) => account.payrollRole === role) ?? null;
+}
+
 function hasMapping(account: IChartAccount, dimension: TMappingDimension): boolean {
   switch (dimension) {
     case 'ustva':

package/ts/chartdata.types.ts

@@ -123,6 +123,81 @@ export type TSecuritiesRole =
   | 'short_sale_loss'
   | 'compensation_paid';
 
+/**
+ * What an account books of a business's payroll: the pay and the employer's
+ * costs of it, the pay's taxes and contributions the business owes until it
+ * pays them, and what a payroll leaves to clear. A payroll run finds its
+ * account by this role: within a chart, no two accounts share one, and every
+ * role has its account in both standard charts (DATEV Kontenrahmen SKR 03
+ * Art.-Nr. 11174, pp. 8, 10, 11, 17, 22, 27, and SKR 04 Art.-Nr. 11175,
+ * pp. 4, 13, 18, 21, 22, gültig für 2026). DATEV's collective accounts
+ * ("Löhne und Gehälter", "Soziale Abgaben und Aufwendungen für
+ * Altersversorgung") take no role.
+ *
+ * The pay, under the wages and salaries (§ 275 Abs. 2 Nr. 6 a HGB, `GuV 6a`):
+ * - 'wages' (Löhne), 'salaries' (Gehälter), 'managing_director_salaries' (a
+ *   GmbH's shareholder-managing directors), 'temporary_wages'
+ *   (Aushilfslöhne), 'minijob_wages' (Löhne für Minijobs);
+ * - 'benefits_in_kind' (Sachzuwendungen und Dienstleistungen an
+ *   Arbeitnehmer), 'capital_formation_benefits' (vermögenswirksame
+ *   Leistungen), 'commuting_allowances' (Fahrtkostenerstattung Wohnung/
+ *   Arbeitsstätte);
+ * - the flat wage tax the employer bears: 'minijob_flat_tax',
+ *   'employee_flat_tax', 'temporary_flat_tax'.
+ *
+ * The employer's contributions, under the social security and pensions
+ * (Nr. 6 b, `GuV 6b`): 'employer_social_security' (gesetzliche soziale
+ * Aufwendungen: the employer's share and the levies U1, U2 and U3),
+ * 'minijob_social_security' (the flat contributions for a Minijob),
+ * 'accident_insurance' (Berufsgenossenschaft), 'pension' (Aufwendungen für
+ * Altersversorgung) and 'pension_flat_tax' (the flat tax on such benefits,
+ * Direktversicherungen).
+ *
+ * What a payroll earns, under the other operating income (Nr. 4, `GuV 4`):
+ * 'company_car_benefit' (the private use of a company car as a supply to the
+ * employee, with 19 % VAT) and 'levy_refunds' (Erstattungen nach dem
+ * Aufwendungsausgleichsgesetz, the sick-pay and maternity refunds of U1 and
+ * U2); 'levy_refund_claims' is the claim on the health insurer until it pays.
+ *
+ * What the business owes (§ 266 Abs. 3 C.8 HGB): 'net_pay' (Verbindlichkeiten
+ * aus Lohn und Gehalt), 'wage_tax' (Lohn- und Kirchensteuer, with the
+ * Solidaritätszuschlag), 'social_security' (the contributions of both sides
+ * and the levies), 'employee_withholdings' (what is withheld from an employee
+ * for another, such as a garnishment), 'capital_formation_payable' (the
+ * savings an employee's contract receives), 'estimated_contributions' (the
+ * contributions estimated in the month they are due, § 23 Abs. 1 SGB IV);
+ * and 'clearing', the Lohn- und Gehaltsverrechnungskonto, a balance on
+ * either side (DATEV states it under the other assets or the other
+ * liabilities by its balance).
+ */
+export type TPayrollRole =
+  | 'wages'
+  | 'salaries'
+  | 'managing_director_salaries'
+  | 'temporary_wages'
+  | 'minijob_wages'
+  | 'benefits_in_kind'
+  | 'capital_formation_benefits'
+  | 'commuting_allowances'
+  | 'minijob_flat_tax'
+  | 'employee_flat_tax'
+  | 'temporary_flat_tax'
+  | 'employer_social_security'
+  | 'minijob_social_security'
+  | 'accident_insurance'
+  | 'pension'
+  | 'pension_flat_tax'
+  | 'company_car_benefit'
+  | 'levy_refunds'
+  | 'levy_refund_claims'
+  | 'net_pay'
+  | 'wage_tax'
+  | 'social_security'
+  | 'employee_withholdings'
+  | 'capital_formation_payable'
+  | 'estimated_contributions'
+  | 'clearing';
+
 /**
  * A rule of the income tax law an income or expense account is kept for, as
  * its DATEV name states it:
@@ -266,6 +341,8 @@ export interface IChartAccount {
   accountRole?: TAccountRole;
   /** what the account books of a business's securities; unset = nothing of its own */
   securitiesRole?: TSecuritiesRole;
+  /** what the account books of a business's payroll; unset = nothing of its own */
+  payrollRole?: TPayrollRole;
   /** the income tax rule the account is kept for, as its DATEV name states it; unset = none of its own */
   taxRule?: TTaxRule;
   /**