/** * DATEV BU-Schlüssel (Steuerschlüssel) — single source of truth. * * Provenance (2026-07-09): cross-checked against multiple independent German * bookkeeping sources. Key semantics that v1 (skr.postingkeys.ts) and the * finance.plus reference implementation got wrong are corrected here: * - 18/19 are steuerpflichtiger innergemeinschaftlicher Erwerb (§1a UStG) * at 7%/19% — NOT generic "Vorsteuer ig Lieferungen". * - 91/94 are Leistungsempfänger schuldet die Steuer (§13b UStG) at 7%/19%. * The official DATEV Steuerschlüssel-Tabelle (Hilfe-Center Dokument 0904313) * is portal-gated; verification against it plus one manual DATEV import per * release candidate is the final gate (see readme.plan.md, M0 Phase 0). */ import type { TBuKey, TTaxScenario } from './core.types.js'; export interface IBuKeyRule { key: TBuKey; description: string; taxType: 'none' | 'ust' | 'vst' | 'vst_ust' | 'automatik_aufhebung'; ratePercent: number | null; scenarios: TTaxScenario[]; } export const BU_KEY_RULES: Record, IBuKeyRule> = { '1': { key: '1', description: 'Umsatzsteuerfrei (§4 UStG)', taxType: 'ust', ratePercent: 0, scenarios: ['domestic_tax_free', 'intra_eu_supply', 'export_third_country'], }, '2': { key: '2', description: 'Umsatzsteuer 7 %', taxType: 'ust', ratePercent: 7, scenarios: ['domestic_reduced'], }, '3': { key: '3', description: 'Umsatzsteuer 19 %', taxType: 'ust', ratePercent: 19, scenarios: ['domestic_standard'], }, '8': { key: '8', description: 'Vorsteuer 7 %', taxType: 'vst', ratePercent: 7, scenarios: ['domestic_reduced'], }, '9': { key: '9', description: 'Vorsteuer 19 %', taxType: 'vst', ratePercent: 19, scenarios: ['domestic_standard'], }, '18': { key: '18', description: 'Steuerpflichtiger innergemeinschaftlicher Erwerb 7 % (§1a UStG)', taxType: 'vst_ust', ratePercent: 7, scenarios: ['intra_eu_acquisition'], }, '19': { key: '19', description: 'Steuerpflichtiger innergemeinschaftlicher Erwerb 19 % (§1a UStG)', taxType: 'vst_ust', ratePercent: 19, scenarios: ['intra_eu_acquisition'], }, '40': { key: '40', description: 'Aufhebung der Automatik', taxType: 'automatik_aufhebung', ratePercent: null, scenarios: [ 'domestic_standard', 'domestic_reduced', 'domestic_tax_free', 'intra_eu_supply', 'intra_eu_acquisition', 'reverse_charge_13b', 'export_third_country', ], }, '91': { key: '91', description: 'Leistungsempfänger schuldet die Steuer 7 % (§13b UStG)', taxType: 'vst_ust', ratePercent: 7, scenarios: ['reverse_charge_13b'], }, '94': { key: '94', description: 'Leistungsempfänger schuldet die Steuer 19 % (§13b UStG)', taxType: 'vst_ust', ratePercent: 19, scenarios: ['reverse_charge_13b'], }, }; export function isKnownBuKey(value: string): value is TBuKey { return value === '' || Object.prototype.hasOwnProperty.call(BU_KEY_RULES, value); } /** * Whether a BU key is one of § 13b UStG, by which DATEV books the tax the * recipient owes and deducts on the base (91, 94): the only keys a line's * `reverseChargeParagraph` may stand beside. Key 40, which every scenario * takes, is none. */ export function isReverseChargeBuKey(key: string): boolean { if (key === '' || !isKnownBuKey(key)) return false; const rule = BU_KEY_RULES[key as Exclude]; return rule.taxType === 'vst_ust' && rule.scenarios.includes('reverse_charge_13b'); } export function getBuKeyRule(key: TBuKey): IBuKeyRule | null { if (key === '') return null; return BU_KEY_RULES[key]; } /** * Suggest the BU key for the expense/revenue line of a booking. * * targetIsAutomatik: Automatikkonten compute tax themselves on DATEV import. * When the entry carries explicit VAT lines, the automatism must be cancelled * with key 40; a plain automatik line without explicit VAT gets no key. * * vatAsStated: the entry books a tax as its document states it, which is not * what DATEV would compute from the base at the rate (SKR-VAT1). No key may * then have DATEV compute it: none, or 40 on an Automatikkonto, so the tax * line stays a booking of its own. */ export function suggestBuKey(params: { direction: 'inbound' | 'outbound'; scenario: TTaxScenario; ratePercent: number; targetIsAutomatik: boolean; hasExplicitVatLines: boolean; vatAsStated?: boolean; }): TBuKey { if (params.targetIsAutomatik) { // a tax booked as stated, also one of 0 where the rate gives a cent, is none the automatism may compute return params.hasExplicitVatLines || params.vatAsStated === true ? '40' : ''; } if (params.vatAsStated === true) { return ''; } const reduced = params.ratePercent === 7; switch (params.scenario) { case 'domestic_standard': case 'domestic_reduced': if (params.direction === 'inbound') return reduced ? '8' : '9'; return reduced ? '2' : '3'; case 'intra_eu_acquisition': return reduced ? '18' : '19'; case 'reverse_charge_13b': return params.direction === 'inbound' ? (reduced ? '91' : '94') : '1'; case 'domestic_tax_free': case 'intra_eu_supply': case 'export_third_country': return params.direction === 'outbound' ? '1' : ''; case 'domestic_zero_rate': // taxable at 0 %, not tax-free: its accounts are Automatikkonten at 0 % (handled above), and key 1 would report // it as tax-free; a purchase under it carries no input tax return ''; case 'other_eu_state_taxable': // no key: the other state's VAT is booked explicitly, and no German key may put the sale into the UStVA return ''; case 'other_eu_state_recipient_liable': case 'not_taxable_here': // their DATEV accounts are Automatikkonten, which carry no key (handled above); on another account none either return ''; } }