@fin.cx/opendata 4.2.0 → 4.3.0

package/ts/vatid/classes.vatiderror.ts

@@ -0,0 +1,83 @@
+import type { IVatIdServiceAnswer } from './interfaces.js';
+
+/**
+ * Why a VAT ID could not be confirmed. Every code means that the service gave no answer about the
+ * validity of the VAT ID asked about:
+ * - `invalid_input`: what was asked is incomplete or not a VAT ID of a member state (checked before
+ *   sending, or refused by the service: eVatR `evatr-0002`, `evatr-0003`, `evatr-0007`, VIES
+ *   `INVALID_INPUT`);
+ * - `vat_id_malformed`: the service says the VAT ID asked about does not have the form its member
+ *   state gives (eVatR `evatr-0005`, `evatr-0012`, `evatr-2003`);
+ * - `requester_invalid`: the requester's own VAT ID is malformed or not valid (eVatR `evatr-0004`,
+ *   `evatr-2005`, VIES `INVALID_REQUESTER_INFO`);
+ * - `not_permitted`: a German VAT ID asked about by a German one (eVatR `evatr-0006`);
+ * - `qualified_limit_reached`: the qualified confirmations of this session are used up (eVatR
+ *   `evatr-0008`); a simple one is still possible;
+ * - `unavailable`: the service cannot answer now (eVatR `evatr-0011`, `-0013`, `-1001`…`-1004`,
+ *   `-2004`, `-2011`, `-3011`; VIES `SERVICE_UNAVAILABLE`);
+ * - `member_state_unavailable`: the member state's system did not answer or failed (eVatR
+ *   `evatr-2007`; VIES `MS_UNAVAILABLE`, `TIMEOUT`);
+ * - `busy`: too many requests at once (VIES `GLOBAL_MAX_CONCURRENT_REQ`, `MS_MAX_CONCURRENT_REQ`
+ *   and their `_TIME` forms);
+ * - `blocked`: the service blocks this address or this VAT ID (VIES `IP_BLOCKED`, `VAT_BLOCKED`);
+ * - `unreachable`: no answer arrived — the name, the connection or TLS failed;
+ * - `timeout`: the answer did not arrive within the client's time;
+ * - `aborted`: the caller's signal ended the request;
+ * - `unexpected_answer`: an answer this client cannot read, or a status it does not know.
+ */
+export type TVatIdErrorCode =
+  | 'invalid_input'
+  | 'vat_id_malformed'
+  | 'requester_invalid'
+  | 'not_permitted'
+  | 'qualified_limit_reached'
+  | 'unavailable'
+  | 'member_state_unavailable'
+  | 'busy'
+  | 'blocked'
+  | 'unreachable'
+  | 'timeout'
+  | 'aborted'
+  | 'unexpected_answer';
+
+export interface IVatIdErrorDetails {
+  service: 'bzst-evatr' | 'vies';
+  /** the service's own code: `evatr-0008`, `MS_UNAVAILABLE` */
+  serviceCode?: string;
+  /** the HTTP status of the answer, where one arrived */
+  httpStatus?: number;
+  /** which input a local check refused */
+  field?: 'requesterVatId' | 'vatId' | 'trader';
+  /** the answer as it arrived, where one did */
+  answer?: IVatIdServiceAnswer;
+}
+
+/** The typed error of the VAT ID clients. */
+export class VatIdError extends Error {
+  public readonly code: TVatIdErrorCode;
+  public readonly service: IVatIdErrorDetails['service'];
+  public readonly serviceCode?: string;
+  public readonly httpStatus?: number;
+  public readonly field?: IVatIdErrorDetails['field'];
+  /** the answer as it arrived, where one did: a refusal, or an answer this client cannot read */
+  public readonly answer?: IVatIdServiceAnswer;
+
+  constructor(code: TVatIdErrorCode, message: string, detailsArg: IVatIdErrorDetails, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'VatIdError';
+    this.code = code;
+    this.service = detailsArg.service;
+    if (detailsArg.serviceCode !== undefined) {
+      this.serviceCode = detailsArg.serviceCode;
+    }
+    if (detailsArg.httpStatus !== undefined) {
+      this.httpStatus = detailsArg.httpStatus;
+    }
+    if (detailsArg.field !== undefined) {
+      this.field = detailsArg.field;
+    }
+    if (detailsArg.answer !== undefined) {
+      this.answer = detailsArg.answer;
+    }
+  }
+}

package/ts/vatid/classes.viesclient.ts

@@ -0,0 +1,123 @@
+import { VatIdError, type TVatIdErrorCode } from './classes.vatiderror.js';
+import { traderOf } from './classes.evatrclient.js';
+import { viesBaseUrl, viesCheckPath } from './constants.js';
+import type { IViesCheck, IViesCheckInput, IVatIdClientOptions, TViesMatch } from './interfaces.js';
+import { postJson, textField } from './request.js';
+import { splitVatId } from './vatid.js';
+
+/** The error codes of VIES's `errorWrappers`, as its test service answers them (read on 2026-09-27). */
+const REFUSALS: Readonly<Record<string, TVatIdErrorCode>> = {
+  INVALID_INPUT: 'invalid_input',
+  INVALID_REQUESTER_INFO: 'requester_invalid',
+  SERVICE_UNAVAILABLE: 'unavailable',
+  MS_UNAVAILABLE: 'member_state_unavailable',
+  TIMEOUT: 'member_state_unavailable',
+  VAT_BLOCKED: 'blocked',
+  IP_BLOCKED: 'blocked',
+  GLOBAL_MAX_CONCURRENT_REQ: 'busy',
+  GLOBAL_MAX_CONCURRENT_REQ_TIME: 'busy',
+  MS_MAX_CONCURRENT_REQ: 'busy',
+  MS_MAX_CONCURRENT_REQ_TIME: 'busy',
+};
+
+const MATCHES: readonly TViesMatch[] = ['VALID', 'INVALID', 'NOT_PROCESSED'];
+
+const matchOf = (bodyArg: unknown, keyArg: string): TViesMatch | undefined => {
+  const value = textField(bodyArg, keyArg);
+  return value !== undefined && (MATCHES as readonly string[]).includes(value) ? (value as TViesMatch) : undefined;
+};
+
+/** VIES writes `---` where a member state gives no name or address. */
+const givenText = (bodyArg: unknown, keyArg: string): string | undefined => {
+  const value = textField(bodyArg, keyArg)?.trim();
+  return value && value !== '---' ? value : undefined;
+};
+
+/**
+ * The European Commission's VIES over its REST API ("Vies on-the-Web", `swagger_publicVAT.yaml`):
+ * whether a VAT ID is valid, and with the business data a comparison of each field. A request that
+ * names the requester's own VAT ID gets VIES's request identifier. Errors arrive with HTTP 200 and
+ * `actionSucceed: false`; they are thrown as `VatIdError`. Nothing is kept.
+ */
+export class ViesClient {
+  constructor(private readonly options: IVatIdClientOptions = {}) {}
+
+  public async check(inputArg: IViesCheckInput): Promise<IViesCheck> {
+    const asked = splitVatId(inputArg.vatId);
+    if (!asked) {
+      throw new VatIdError('invalid_input', 'the VAT ID asked about starts with no member state\'s code', { service: 'vies', field: 'vatId' });
+    }
+    const requester = inputArg.requesterVatId === undefined ? undefined : splitVatId(inputArg.requesterVatId);
+    if (inputArg.requesterVatId !== undefined && !requester) {
+      throw new VatIdError('invalid_input', 'the requester\'s VAT ID starts with no member state\'s code', { service: 'vies', field: 'requesterVatId' });
+    }
+    const trader = inputArg.trader ? traderOf(inputArg.trader) : undefined;
+    if (inputArg.trader && !trader) {
+      throw new VatIdError('invalid_input', 'a comparison needs the name and the city', { service: 'vies', field: 'trader' });
+    }
+    const answer = await postJson(this.options, 'vies', `${this.options.baseUrl ?? viesBaseUrl}${viesCheckPath}`, {
+      countryCode: asked.countryCode,
+      vatNumber: asked.number,
+      ...(requester ? { requesterMemberStateCode: requester.countryCode, requesterNumber: requester.number } : {}),
+      ...(trader
+        ? {
+          traderName: trader.name,
+          traderCity: trader.city,
+          ...(trader.street ? { traderStreet: trader.street } : {}),
+          ...(trader.postalCode ? { traderPostalCode: trader.postalCode } : {}),
+        }
+        : {}),
+    }, inputArg.signal);
+    const body = answer.body;
+    const succeeded: unknown = body && typeof body === 'object' ? Reflect.get(body, 'actionSucceed') : undefined;
+    if (succeeded === false) {
+      const wrappers: unknown = Reflect.get(body as object, 'errorWrappers');
+      const first: unknown = Array.isArray(wrappers) ? wrappers[0] : undefined;
+      const serviceCode = textField(first, 'error');
+      throw new VatIdError(serviceCode ? (REFUSALS[serviceCode] ?? 'unexpected_answer') : 'unexpected_answer', `VIES answered ${serviceCode ?? 'an error without a code'}`, {
+        service: 'vies',
+        httpStatus: answer.httpStatus,
+        ...(serviceCode ? { serviceCode } : {}),
+        answer: answer.answer,
+      });
+    }
+    const valid: unknown = body && typeof body === 'object' ? Reflect.get(body, 'valid') : undefined;
+    const requestedAt = textField(body, 'requestDate');
+    const requestedAtMs = requestedAt ? Date.parse(requestedAt) : Number.NaN;
+    if (answer.httpStatus !== 200 || typeof valid !== 'boolean' || !requestedAt || Number.isNaN(requestedAtMs)) {
+      throw new VatIdError('unexpected_answer', `VIES answered HTTP ${answer.httpStatus} in a form this client cannot read`, {
+        service: 'vies',
+        httpStatus: answer.httpStatus,
+        answer: answer.answer,
+      });
+    }
+    const requestId = textField(body, 'requestIdentifier');
+    const name = givenText(body, 'name') ?? givenText(body, 'traderName');
+    const address = givenText(body, 'address');
+    const compared = trader
+      ? {
+        asked: trader,
+        ...optionalMatch('name', matchOf(body, 'traderNameMatch')),
+        ...optionalMatch('street', matchOf(body, 'traderStreetMatch')),
+        ...optionalMatch('postalCode', matchOf(body, 'traderPostalCodeMatch')),
+        ...optionalMatch('city', matchOf(body, 'traderCityMatch')),
+      }
+      : undefined;
+    return {
+      service: 'vies',
+      valid,
+      requestedAt,
+      requestedAtMs,
+      ...(requestId ? { requestId } : {}),
+      vatId: asked.vatId,
+      ...(requester ? { requesterVatId: requester.vatId } : {}),
+      ...(name ? { name } : {}),
+      ...(address ? { address } : {}),
+      ...(compared ? { compared } : {}),
+      answer: answer.answer,
+    };
+  }
+}
+
+const optionalMatch = <TKey extends string>(keyArg: TKey, matchArg: TViesMatch | undefined): Partial<Record<TKey, TViesMatch>> =>
+  (matchArg ? { [keyArg]: matchArg } : {}) as Partial<Record<TKey, TViesMatch>>;

package/ts/vatid/constants.ts

@@ -0,0 +1,40 @@
+/**
+ * The BZSt's eVatR REST API (Bestätigungsverfahren of § 18e UStG), as its OpenAPI document names it
+ * (`https://api.evatr.vies.bzst.de/api-docs`, read on 2026-09-27): the server, and the path of a
+ * confirmation. The XML-RPC interface the BZSt offered before is obsolete from 30 November 2025.
+ */
+export const evatrBaseUrl = 'https://api.evatr.vies.bzst.de/app';
+export const evatrConfirmationPath = '/v1/abfrage';
+
+/**
+ * The European Commission's "Vies on-the-Web" REST API: the base under which its contract's paths
+ * (`swagger_publicVAT.yaml`) answer, read on 2026-09-27 (`/check-status` answered there, and so did
+ * `/check-vat-test-service`). The contract itself names no host.
+ */
+export const viesBaseUrl = 'https://ec.europa.eu/taxation_customs/vies/rest-api';
+export const viesCheckPath = '/check-vat-number';
+
+/** How long one request may take by default, the answer included. */
+export const defaultVatIdTimeoutMs = 30_000;
+
+/**
+ * The country codes a VAT identification number starts with, as the eVatR API's list of member
+ * states gives them (`/v1/info/eu_mitgliedstaaten`, read on 2026-09-27): the 27 member states,
+ * Greece as `EL`, and `XI` for Northern Ireland.
+ */
+export const vatIdCountryCodes = [
+  'AT', 'BE', 'BG', 'CY', 'CZ', 'DE', 'DK', 'EE', 'EL', 'ES', 'FI', 'FR', 'HR', 'HU',
+  'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'PL', 'PT', 'RO', 'SE', 'SI', 'SK', 'XI',
+] as const;
+
+/**
+ * Every status code of the eVatR API with the HTTP status its list of messages gives it
+ * (`/v1/info/statusmeldungen`, read on 2026-09-27). The OpenAPI document lists `evatr-0008` under
+ * 400 and the list under 403, so the code decides, never the HTTP status.
+ */
+export const evatrStatusCodes = [
+  'evatr-0000', 'evatr-0001', 'evatr-0002', 'evatr-0003', 'evatr-0004', 'evatr-0005', 'evatr-0006',
+  'evatr-0007', 'evatr-0008', 'evatr-0011', 'evatr-0012', 'evatr-0013', 'evatr-1001', 'evatr-1002',
+  'evatr-1003', 'evatr-1004', 'evatr-2001', 'evatr-2002', 'evatr-2003', 'evatr-2004', 'evatr-2005',
+  'evatr-2006', 'evatr-2007', 'evatr-2008', 'evatr-2011', 'evatr-3011',
+] as const;

package/ts/vatid/index.ts

@@ -0,0 +1,17 @@
+// This entry point stands alone: it imports nothing from the rest of the package and has no
+// dependencies. It keeps nothing: every answer goes to the caller, who keeps it as evidence where the
+// law asks for it.
+export * from './interfaces.js';
+export { VatIdError, type IVatIdErrorDetails, type TVatIdErrorCode } from './classes.vatiderror.js';
+export {
+  defaultVatIdTimeoutMs,
+  evatrBaseUrl,
+  evatrConfirmationPath,
+  evatrStatusCodes,
+  vatIdCountryCodes,
+  viesBaseUrl,
+  viesCheckPath,
+} from './constants.js';
+export { splitVatId } from './vatid.js';
+export { EvatrClient } from './classes.evatrclient.js';
+export { ViesClient } from './classes.viesclient.js';

package/ts/vatid/interfaces.ts

@@ -0,0 +1,154 @@
+import type { evatrStatusCodes, vatIdCountryCodes } from './constants.js';
+
+/** A country code a VAT identification number starts with (`EL` for Greece, `XI` for Northern Ireland). */
+export type TVatIdCountryCode = (typeof vatIdCountryCodes)[number];
+
+/** A status code of the eVatR API. */
+export type TEvatrStatusCode = (typeof evatrStatusCodes)[number];
+
+/** A VAT identification number taken apart: its country code and the number after it. */
+export interface IVatIdParts {
+  countryCode: TVatIdCountryCode;
+  number: string;
+  /** both together, without spaces, dots or hyphens, in capitals: `ATU12345678` */
+  vatId: string;
+}
+
+/**
+ * The fetch a client sends its requests with: the runtime's `fetch`, or one that decides which
+ * addresses may be reached (for example `createPublicOnlyFetch` of `@push.rocks/smartrequest`).
+ */
+export type TVatIdFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+export interface IVatIdClientOptions {
+  /** default: the runtime's `fetch` */
+  fetch?: TVatIdFetch;
+  /** default: the official address (`evatrBaseUrl`, `viesBaseUrl`); a test's own server otherwise */
+  baseUrl?: string;
+  /** how long one request may take, the answer included; default `defaultVatIdTimeoutMs` */
+  timeoutMs?: number;
+  /** sent as `User-Agent` where given */
+  userAgent?: string;
+}
+
+/**
+ * A service's answer as it arrived: its HTTP status and its body, byte for byte as text. It is what the
+ * service said, whatever of it this client reads, so a caller can keep it as the evidence of a
+ * confirmation (§ 17d Abs. 1 UStDV asks the VAT ID of the buyer of an intra-Community supply to be
+ * shown in the books).
+ */
+export interface IVatIdServiceAnswer {
+  httpStatus: number;
+  text: string;
+}
+
+/** The business data a qualified confirmation compares with what the member state registered. */
+export interface IVatIdTraderData {
+  name: string;
+  street?: string;
+  postalCode?: string;
+  city: string;
+}
+
+/**
+ * What the member state says about one field of a qualified confirmation (eVatR):
+ * - `A`: it matches the registered data;
+ * - `B`: it does not match;
+ * - `C`: it was not asked about;
+ * - `D`: the member state did not give it.
+ */
+export type TEvatrFieldResult = 'A' | 'B' | 'C' | 'D';
+
+export interface IEvatrConfirmationInput {
+  /** the German VAT ID of the business that asks (`anfragendeUstid`); § 18e UStG confirms to a business */
+  requesterVatId: string;
+  /** the VAT ID asked about (`angefragteUstid`) */
+  vatId: string;
+  /** with the business data, a qualified confirmation; `name` and `city` are what makes it one */
+  trader?: IVatIdTraderData;
+  signal?: AbortSignal;
+}
+
+/**
+ * The BZSt's answer about one VAT ID. `valid` holds for `evatr-0000` and `evatr-2008` (valid, with a
+ * particularity of the qualified confirmation the BZSt explains on request); `evatr-2002` (not yet
+ * valid, from `validFrom`), `evatr-2006` (was valid from `validFrom` to `validTo`) and `evatr-2001`
+ * (not assigned) are answers that it is not.
+ */
+export interface IEvatrConfirmation {
+  service: 'bzst-evatr';
+  /** the BZSt's id of the request (`id`), the reference of the confirmation */
+  requestId?: string;
+  /** when the BZSt answered, as it wrote it (`anfrageZeitpunkt`, ISO 8601 with its offset) */
+  requestedAt: string;
+  /** the same, as epoch milliseconds */
+  requestedAtMs: number;
+  status: 'evatr-0000' | 'evatr-2001' | 'evatr-2002' | 'evatr-2006' | 'evatr-2008';
+  valid: boolean;
+  /** `gueltigAb`, as the BZSt wrote it; its form is not documented */
+  validFrom?: string;
+  /** `gueltigBis`, as the BZSt wrote it */
+  validTo?: string;
+  /** what was asked, as it was sent */
+  requesterVatId: string;
+  vatId: string;
+  /**
+   * A qualified request (`trader` given) whose VAT ID is valid: what was compared and the member
+   * state's result for each field sent (`answered: true`), or, for `evatr-2008`, that the comparison
+   * has a particularity the BZSt explains on request and gives no result (`answered: false`). Absent
+   * for a simple request and for an answer that the VAT ID is not valid, which compares nothing.
+   */
+  qualified?: TEvatrQualifiedResult;
+  /** the answer as it arrived */
+  answer: IVatIdServiceAnswer;
+}
+
+export type TEvatrQualifiedResult =
+  | {
+    asked: IVatIdTraderData;
+    answered: true;
+    name: TEvatrFieldResult;
+    street?: TEvatrFieldResult;
+    postalCode?: TEvatrFieldResult;
+    city: TEvatrFieldResult;
+  }
+  | { asked: IVatIdTraderData; answered: false };
+
+/** What VIES says about one field of the trader data: matches, does not match, or not compared. */
+export type TViesMatch = 'VALID' | 'INVALID' | 'NOT_PROCESSED';
+
+export interface IViesCheckInput {
+  /** the VAT ID asked about, with its country code */
+  vatId: string;
+  /** the business that asks, with its own VAT ID; VIES gives a request identifier only with it */
+  requesterVatId?: string;
+  /** with the business data, VIES compares it ("approximate matching") */
+  trader?: IVatIdTraderData;
+  signal?: AbortSignal;
+}
+
+/** VIES's answer about one VAT ID. */
+export interface IViesCheck {
+  service: 'vies';
+  valid: boolean;
+  /** when VIES answered (`requestDate`, ISO 8601) */
+  requestedAt: string;
+  requestedAtMs: number;
+  /** VIES's reference of the request (`requestIdentifier`); only where the requester was named */
+  requestId?: string;
+  vatId: string;
+  requesterVatId?: string;
+  /** the name and the address the member state registered, where it gives them */
+  name?: string;
+  address?: string;
+  /** the trader data asked about, and VIES's comparison of each field */
+  compared?: {
+    asked: IVatIdTraderData;
+    name?: TViesMatch;
+    street?: TViesMatch;
+    postalCode?: TViesMatch;
+    city?: TViesMatch;
+  };
+  /** the answer as it arrived, with everything VIES gave that is not read into the fields above */
+  answer: IVatIdServiceAnswer;
+}

package/ts/vatid/request.ts

@@ -0,0 +1,77 @@
+import { VatIdError, type IVatIdErrorDetails } from './classes.vatiderror.js';
+import { defaultVatIdTimeoutMs } from './constants.js';
+import type { IVatIdClientOptions, IVatIdServiceAnswer, TVatIdFetch } from './interfaces.js';
+
+/** An answer as it arrived (`answer`, its status and its text), and its body read as JSON, or `undefined` where it was none. */
+export interface IJsonAnswer {
+  httpStatus: number;
+  body: unknown;
+  answer: IVatIdServiceAnswer;
+}
+
+/**
+ * Sends one JSON request and reads the answer whole, within the client's time. The caller's signal
+ * ends it as `aborted`, the time as `timeout`, and a request that could not be sent or answered as
+ * `unreachable`; nothing is retried. The timer ends with the request, answered or not.
+ */
+export const postJson = async (
+  optionsArg: IVatIdClientOptions,
+  serviceArg: IVatIdErrorDetails['service'],
+  urlArg: string,
+  bodyArg: unknown,
+  signalArg: AbortSignal | undefined,
+): Promise<IJsonAnswer> => {
+  const fetchFn: TVatIdFetch = optionsArg.fetch ?? ((inputArg, initArg) => fetch(inputArg, initArg));
+  const timeout = new AbortController();
+  const timer = setTimeout(() => timeout.abort(new Error('the client\'s time ran out')), optionsArg.timeoutMs ?? defaultVatIdTimeoutMs);
+  const signal = signalArg ? AbortSignal.any([signalArg, timeout.signal]) : timeout.signal;
+  const failed = (errorArg: unknown): VatIdError => {
+    if (signalArg?.aborted) {
+      return new VatIdError('aborted', 'the request was ended by its caller', { service: serviceArg }, { cause: errorArg });
+    }
+    if (timeout.signal.aborted) {
+      return new VatIdError('timeout', 'the service did not answer in time', { service: serviceArg }, { cause: errorArg });
+    }
+    return new VatIdError('unreachable', 'the service could not be reached', { service: serviceArg }, { cause: errorArg });
+  };
+  let response: Response;
+  let text: string;
+  try {
+    if (signalArg?.aborted) {
+      throw failed(signalArg.reason);
+    }
+    try {
+      response = await fetchFn(urlArg, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/json',
+          ...(optionsArg.userAgent ? { 'user-agent': optionsArg.userAgent } : {}),
+        },
+        body: JSON.stringify(bodyArg),
+        signal,
+      });
+      text = await response.text();
+    } catch (error) {
+      throw failed(error);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+  let body: unknown;
+  try {
+    body = text.trim() === '' ? undefined : JSON.parse(text);
+  } catch {
+    body = undefined;
+  }
+  return { httpStatus: response.status, body, answer: { httpStatus: response.status, text } };
+};
+
+/** A string field of an answer, where it is one and not empty. */
+export const textField = (bodyArg: unknown, keyArg: string): string | undefined => {
+  if (!bodyArg || typeof bodyArg !== 'object') {
+    return undefined;
+  }
+  const value: unknown = Reflect.get(bodyArg, keyArg);
+  return typeof value === 'string' && value !== '' ? value : undefined;
+};

package/ts/vatid/vatid.ts

@@ -0,0 +1,25 @@
+import { vatIdCountryCodes } from './constants.js';
+import type { IVatIdParts, TVatIdCountryCode } from './interfaces.js';
+
+/** A VAT ID as it is printed: spaces, dots and hyphens between its characters are left out. */
+const SEPARATORS = /[\s.\-]+/gu;
+
+/** After the country code: letters and digits, 2 to 13 of them (the longest form, France and the Netherlands, has 12). */
+const NUMBER_PART = /^[A-Z0-9+*]{2,13}$/u;
+
+/**
+ * Takes a VAT identification number apart: its country code and the number after it, without the
+ * spaces, dots and hyphens it is often printed with, in capitals. `GR` is written `EL`, as VAT IDs of
+ * Greece are. Answers `undefined` for anything that does not start with a member state's code or has
+ * no number after it; whether the number has its member state's form is the service's to say.
+ */
+export const splitVatId = (valueArg: string): IVatIdParts | undefined => {
+  const compact = valueArg.replace(SEPARATORS, '').toUpperCase();
+  const prefix = compact.slice(0, 2);
+  const countryCode = prefix === 'GR' ? 'EL' : prefix;
+  const number = compact.slice(2);
+  if (!(vatIdCountryCodes as readonly string[]).includes(countryCode) || !NUMBER_PART.test(number)) {
+    return undefined;
+  }
+  return { countryCode: countryCode as TVatIdCountryCode, number, vatId: `${countryCode}${number}` };
+};