Validate Steuernummer

Validation of German Steuernummern. Written in TypeScript, exposed as ESM and UMD.

Installation

npm i validate-steuernummer

Or:

yarn add validate-steuernummer

Usage

import { validateSteuernummer } from 'validate-steuernummer'

// Providing a Steuernummer in the "Vereinheitlichtes Bundesschema zur
// elektronischen Übermittlung":
const err1 = validateSteuernummer('9/198/0/815/08152');
// err1 is `undefined`, because this is a valid Steuernummer from Bavaria

// Providing a Steuernummer in the "Vereinheitlichtes Bundesschema":
const err2 = validateSteuernummer('24 75 815 08154');
// err2 is `Die Prüfziffer der Steuernummer stimmt nicht`, because 4 is not the
// valid Prüfziffer for this Steuernummer from Bremen

// Providing a Steuernummer in the "Standardschema der Länder", and additionally
// passing the Bundesland that issued the Steuernummer:
const err3 = validateSteuernummer('24/815/08151', { bundesland: 'DE-NI' });
// err3 is `undefined`, because this is a valid Steuernummer from Niedersachsen

This library exposes a single validateSteuernummer function that takes one or two arguments:

A string value containing (possibly) a German Steuernummer
Optionally: an options object

The function returns undefined if it deems the given value to be a valid Steuernummer, or an error string denoting why not.

What's being validated?

This library checks that:

The given string contains only digits, spaces (" "), and slashes ("/")
The number of digits in the given string is between 10 and 13
The state ("Bundesland") issuing the Steuernummer is known
- Either, because the Steuernummer contains a valid state prefix (which means it must be of length >= 12)
- Or, because the bundesland option was used to deliberately name the issuing state (this is useful when providing a Steuernummer in the commonly used Standardschema der Länder, which means it is contains 11 or 12 digits only)
The state information contained in the Steuernummer matches the bundesland option, in case both are given
The Bundesfinanzamtsnummer part of the Steuernummer references a known Bundesfinanzamt. This library checks against "GemFA 2.0" (GEMeinden und FinanzAemter 2.0) data, which lists 610 Finanzämter as of October 5th 2022.
The Bezirksnummer part of the Steuernummer is valid (checking state-specific constraints)
The Unterscheidungsnummer and Prüfziffer fulfill requirements specific to Nordrhein-Westfalen
The Prüfziffer is valid. Relies on the "11er Verfahren", "2er Verfahren", or "Modifiziertes 11er Verfahren" depending on the issuing state. In the case of a Steuernummer from Berlin, validation passes if the Prüfziffer matches that calculated either for the Berlin-A or the Berlin-B scheme (cf. section 7.2 of this document).

For details about the validation requirements for Steuernummern, refer to this document.

Options

bundesland: A string denoting one of the 16 German states using ISO 3166-2 notation. E.g., DE-BE for Berlin.

errorMessages: An object allowing to overwrite the default (German) error messages returned. For example:

validateSteuernummer(/* ... */, { errorMessages: {
  allowedCharactersError:
    'Please only use digits, spaces, dashes, underscores, or slashes'
}});

lax: If true, validation will ignore state-specific checks if the state issuing the given Steuernummer cannot be determined (i.e., if the Steuernummer does not include a state prefix, and the bundesland option was not used). In this case, validation will only check that the given string contains only valid characters, and that it contains a valid number of digits. Defaults to false.

kontist/normalize-steuernummer for translating Steuernummern in the "Standardschema der Länder" or "Vereinheitlichtes Bundesschema" into the normalized "Vereinheitlichtes Bundesschema zur elektronischen Übermittlung"
kontist/denormalize-steuernummer for translating a Steuernummer in the "Vereinheitlichtes Bundesschema zur elektronischen Übermittlung" into one in the "Standardschema der Länder" + the issuing state
kontist/validate-steuerid for validating German Steuer-IDs (Steuernummer and Steuer-ID are not the same)

License

MIT