@fin.cx/opendata 4.2.0 → 4.3.0

package/dist_ts/vatid/interfaces.d.ts

@@ -0,0 +1,141 @@
+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/dist_ts/vatid/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3ZhdGlkL2ludGVyZmFjZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist_ts/vatid/request.d.ts

@@ -0,0 +1,16 @@
+import { type IVatIdErrorDetails } from './classes.vatiderror.js';
+import type { IVatIdClientOptions, IVatIdServiceAnswer } 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 declare const postJson: (optionsArg: IVatIdClientOptions, serviceArg: IVatIdErrorDetails["service"], urlArg: string, bodyArg: unknown, signalArg: AbortSignal | undefined) => Promise<IJsonAnswer>;
+/** A string field of an answer, where it is one and not empty. */
+export declare const textField: (bodyArg: unknown, keyArg: string) => string | undefined;

package/dist_ts/vatid/request.js

@@ -0,0 +1,65 @@
+import { VatIdError } from './classes.vatiderror.js';
+import { defaultVatIdTimeoutMs } from './constants.js';
+/**
+ * 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, serviceArg, urlArg, bodyArg, signalArg) => {
+    const fetchFn = 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) => {
+        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;
+    let text;
+    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;
+    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, keyArg) => {
+    if (!bodyArg || typeof bodyArg !== 'object') {
+        return undefined;
+    }
+    const value = Reflect.get(bodyArg, keyArg);
+    return typeof value === 'string' && value !== '' ? value : undefined;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVxdWVzdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3ZhdGlkL3JlcXVlc3QudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFVBQVUsRUFBMkIsTUFBTSx5QkFBeUIsQ0FBQztBQUM5RSxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQVV2RDs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sUUFBUSxHQUFHLEtBQUssRUFDM0IsVUFBK0IsRUFDL0IsVUFBeUMsRUFDekMsTUFBYyxFQUNkLE9BQWdCLEVBQ2hCLFNBQWtDLEVBQ1osRUFBRTtJQUN4QixNQUFNLE9BQU8sR0FBZ0IsVUFBVSxDQUFDLEtBQUssSUFBSSxDQUFDLENBQUMsUUFBUSxFQUFFLE9BQU8sRUFBRSxFQUFFLENBQUMsS0FBSyxDQUFDLFFBQVEsRUFBRSxPQUFPLENBQUMsQ0FBQyxDQUFDO0lBQ25HLE1BQU0sT0FBTyxHQUFHLElBQUksZUFBZSxFQUFFLENBQUM7SUFDdEMsTUFBTSxLQUFLLEdBQUcsVUFBVSxDQUFDLEdBQUcsRUFBRSxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsSUFBSSxLQUFLLENBQUMsNEJBQTRCLENBQUMsQ0FBQyxFQUFFLFVBQVUsQ0FBQyxTQUFTLElBQUkscUJBQXFCLENBQUMsQ0FBQztJQUN0SSxNQUFNLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FBQyxDQUFDLFdBQVcsQ0FBQyxHQUFHLENBQUMsQ0FBQyxTQUFTLEVBQUUsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUM7SUFDekYsTUFBTSxNQUFNLEdBQUcsQ0FBQyxRQUFpQixFQUFjLEVBQUU7UUFDL0MsSUFBSSxTQUFTLEVBQUUsT0FBTyxFQUFFLENBQUM7WUFDdkIsT0FBTyxJQUFJLFVBQVUsQ0FBQyxTQUFTLEVBQUUscUNBQXFDLEVBQUUsRUFBRSxPQUFPLEVBQUUsVUFB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

package/dist_ts/vatid/vatid.d.ts

@@ -0,0 +1,8 @@
+import type { IVatIdParts } from './interfaces.js';
+/**
+ * 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 declare const splitVatId: (valueArg: string) => IVatIdParts | undefined;

package/dist_ts/vatid/vatid.js

@@ -0,0 +1,22 @@
+import { vatIdCountryCodes } from './constants.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) => {
+    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.includes(countryCode) || !NUMBER_PART.test(number)) {
+        return undefined;
+    }
+    return { countryCode: countryCode, number, vatId: `${countryCode}${number}` };
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmF0aWQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy92YXRpZC92YXRpZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUduRCwrRkFBK0Y7QUFDL0YsTUFBTSxVQUFVLEdBQUcsWUFBWSxDQUFDO0FBRWhDLDBIQUEwSDtBQUMxSCxNQUFNLFdBQVcsR0FBRyxxQkFBcUIsQ0FBQztBQUUxQzs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRyxDQUFDLFFBQWdCLEVBQTJCLEVBQUU7SUFDdEUsTUFBTSxPQUFPLEdBQUcsUUFBUSxDQUFDLE9BQU8sQ0FBQyxVQUFVLEVBQUUsRUFBRSxDQUFDLENBQUMsV0FBVyxFQUFFLENBQUM7SUFDL0QsTUFBTSxNQUFNLEdBQUcsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDbkMsTUFBTSxXQUFXLEdBQUcsTUFBTSxLQUFLLElBQUksQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUM7SUFDcEQsTUFBTSxNQUFNLEdBQUcsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUNoQyxJQUFJLENBQUUsaUJBQXVDLENBQUMsUUFBUSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsV0FBVyxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDO1FBQ2pHLE9BQU8sU0FBUyxDQUFDO0lBQ25CLENBQUM7SUFDRCxPQUFPLEVBQUUsV0FBVyxFQUFFLFdBQWdDLEVBQUUsTUFBTSxFQUFFLEtBQUssRUFBRSxHQUFHLFdBQVcsR0FBRyxNQUFNLEVBQUUsRUFBRSxDQUFDO0FBQ3JHLENBQUMsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/opendata",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "private": false,
   "description": "Open business and financial data for TypeScript: register lookups on the German register portal (handelsregister.de) without storage, the statutory public holidays of the German federal states, the base rate of § 247 BGB, and stock and crypto prices and fundamentals from several providers.",
   "main": "dist_ts/index.js",
@@ -22,6 +22,10 @@
       "types": "./dist_ts/baserate/index.d.ts",
       "import": "./dist_ts/baserate/index.js"
     },
+    "./vatid": {
+      "types": "./dist_ts/vatid/index.d.ts",
+      "import": "./dist_ts/vatid/index.js"
+    },
     "./package.json": "./package.json"
   },
   "type": "module",
@@ -30,8 +34,8 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^5.0.0",
     "@git.zone/tsbundle": "^2.15.0",
-    "@git.zone/tsrun": "^3.0.0",
-    "@git.zone/tstest": "^6.3.1",
+    "@git.zone/tsrun": "^3.0.1",
+    "@git.zone/tstest": "^6.3.2",
     "@types/node": "^26.6.2"
   },
   "dependencies": {

package/readme.md

@@ -2,13 +2,14 @@
 
 `@fin.cx/opendata` is a TypeScript toolbox for open business and market data: stock and crypto prices, SEC fundamentals, lookups in the German registers through the register portal of the federal states, the statutory public holidays of the German federal states, and the base rate of § 247 BGB. It is built for programmers who want scriptable APIs and real workflows instead of a thin wrapper around one remote endpoint.
 
-It gives you five practical lanes in one package:
+It gives you six practical lanes in one package:
 
 - `StockPriceService` for stock and crypto prices with caching, retries, failover, historical ranges, and intraday support
 - `FundamentalsService` and `StockDataService` for SEC fundamentals and combined price + fundamentals payloads
 - `HandelsregisterClient`, from `@fin.cx/opendata/handelsregister`, for single lookups in the commercial, cooperative, partnership, association and civil-law partnership registers over plain HTTP, without any storage
 - the holiday calendar, from `@fin.cx/opendata/holidays`, for the statutory public holidays of each German federal state and the working days of § 193 BGB, computed per year without data files or requests
 - the base rate, from `@fin.cx/opendata/baserate`, for the Basiszinssatz of § 247 BGB per half-year as the Deutsche Bundesbank publishes it, for default interest under § 288 BGB
+- VAT ID confirmation, from `@fin.cx/opendata/vatid`, over the BZSt's eVatR REST API (the confirmation of § 18e UStG, simple or qualified) and the European Commission's VIES REST API, without any storage
 
 ## Issue Reporting and Security
 
@@ -70,6 +71,40 @@ Everything here comes from `@fin.cx/opendata/baserate`. That entry point imports
   A span of days split where the rate changes, as interest under § 288 BGB is computed.
 - `baseRatePeriods`, `baseRateFirstDay`, `baseRatesReadOn`, `baseRateSource`
 
+### VAT ID Confirmation
+
+Everything here comes from `@fin.cx/opendata/vatid`. That entry point imports nothing else of the package and has no dependencies. It keeps nothing: each answer goes to the caller, with the answer as it arrived (`answer`: the HTTP status and the body, byte for byte), so the caller can keep it as evidence where the law asks for it. For an intra-Community supply that is the books' record of the buyer's foreign VAT ID (§ 17d Abs. 1 UStDV); a confirmation also shows the care of a prudent businessman on which the exemption rests in good faith (§ 6a Abs. 4 UStG).
+
+- `EvatrClient#confirm({ requesterVatId, vatId, trader? })`
+  The BZSt's confirmation of a foreign VAT ID (§ 18e Nr. 1 UStG). The requester is a business with a German VAT ID. With `trader` (name and city, optionally street and postal code) it is a qualified confirmation. Where the VAT ID is valid the answer carries the member state's result for each field (`qualified.answered: true`; `A` matches, `B` does not match, `C` not asked, `D` not given), or, for `evatr-2008`, that the comparison has a particularity the BZSt explains on request (`qualified.answered: false`). A valid answer to a qualified request without a documented result for each field sent is refused as `unexpected_answer`, never passed on as a simple confirmation.
+- `ViesClient#check({ vatId, requesterVatId?, trader? })`
+  The European Commission's VIES check, with the registered name and address where the member state gives them, a comparison of the trader data (`VALID`, `INVALID`, `NOT_PROCESSED`), and VIES's request identifier where the requester is named. The name is VIES's `name`, or, where it gives none, its `traderName`: the contract lists `traderName` in the answer but does not say whether it is the registered name or the one asked about; the test service answers a comparison with the registered name there. Everything else VIES answers is in `answer`.
+- `splitVatId(value)`, `vatIdCountryCodes`, `evatrStatusCodes`
+- `VatIdError` with a code for every reason no answer about validity arrived, and the answer as it arrived where one did (`answer`)
+
+Both clients take a `fetch` (for example `createPublicOnlyFetch` of `@push.rocks/smartrequest`), a `baseUrl` for a test server, a `timeoutMs` (30 seconds by default; its timer ends with the request) and a caller's `signal`. Nothing is retried.
+
+```typescript
+import { EvatrClient, ViesClient, VatIdError } from '@fin.cx/opendata/vatid';
+
+const evatr = new EvatrClient();
+const confirmation = await evatr.confirm({
+  requesterVatId: 'DE123456789',
+  vatId: 'ATU12345678',
+  trader: { name: 'Musterhaus GmbH & Co KG', street: 'Musterstrasse 22', postalCode: '12345', city: 'musterort' },
+});
+// { service: 'bzst-evatr', requestId, requestedAt, status: 'evatr-0000', valid: true,
+//   qualified: { answered: true, name: 'A', city: 'A', ... }, answer: { httpStatus: 200, text: '{"id":…}' } }
+
+try {
+  await new ViesClient().check({ vatId: 'ATU12345678', requesterVatId: 'DE123456789' });
+} catch (error) {
+  if (error instanceof VatIdError) {
+    console.log(error.code, error.serviceCode); // for example 'member_state_unavailable', 'MS_UNAVAILABLE'
+  }
+}
+```
+
 ## Before You Start
 
 - No stock or fundamentals providers are pre-registered. You must register them before calling the services.
@@ -461,6 +496,12 @@ Four holidays apply only in part of a state:
 - `holidayCalendarFirstYear`, `holidayLawsReadOn`
 - `HolidayCalendarError` with the codes `invalid_date`, `unsupported_year`, `unknown_state` and `invalid_options`
 
+### VAT ID (`@fin.cx/opendata/vatid`)
+
+- `EvatrClient` with `confirm(input)`; `ViesClient` with `check(input)`
+- `splitVatId(value)`, `vatIdCountryCodes`, `evatrStatusCodes`, `evatrBaseUrl`, `viesBaseUrl`, `defaultVatIdTimeoutMs`
+- `VatIdError` with the codes `invalid_input`, `vat_id_malformed`, `requester_invalid`, `not_permitted`, `qualified_limit_reached`, `unavailable`, `member_state_unavailable`, `busy`, `blocked`, `unreachable`, `timeout`, `aborted` and `unexpected_answer`
+
 ### Base rate (`@fin.cx/opendata/baserate`)
 
 - `getBaseRate(date)`
@@ -517,6 +558,12 @@ The holiday calendar is derived from the holiday laws of the federal states, rea
 
 The base rate of `@fin.cx/opendata/baserate` (`ts/baserate/data.baserate.ts`) is the table "Basiszinssatz nach § 247 BGB" of the Deutsche Bundesbank (https://www.bundesbank.de/de/bundesbank/organisation/agb-und-regelungen/basiszinssatz-607820), which the Bundesbank publishes under § 247 Abs. 2 BGB, read on 2026-09-27 and reproduced unaltered: every half-year from 1 July 2002, the first row it lists, to the half-year from 1 July 2026 (1,52 %). The rate changes on 1 January and 1 July (§ 247 Abs. 1 Satz 2 BGB); a day after 31 December 2026 answers `not_published` until a release carries the next row.
 
+The VAT ID clients of `@fin.cx/opendata/vatid` ask two official services at run time, one request at a time, read on 2026-09-27:
+
+- The BZSt's eVatR REST API (`https://api.evatr.vies.bzst.de/app`, OpenAPI at `https://api.evatr.vies.bzst.de/api-docs`, version "v:1.2.3.19.886"): `POST /v1/abfrage` with `anfragendeUstid`, `angefragteUstid` and, for a qualified confirmation, `firmenname` and `ort` (and optionally `strasse`, `plz`). The status codes are those of `/v1/info/statusmeldungen`, and the country codes those of `/v1/info/eu_mitgliedstaaten`. The BZSt's page on foreign VAT IDs names the online form (`https://www.bzst.de/evatr`) and the REST API, and says the former XML-RPC interface is obsolete from 30 November 2025.
+- The European Commission's VIES REST API (`https://ec.europa.eu/taxation_customs/vies/rest-api`, contract `swagger_publicVAT.yaml`): `POST /check-vat-number`. Its errors arrive with HTTP 200 and `actionSucceed: false`, as its test service (`/check-vat-test-service`) shows.
+- Not verified: the terms of use of either service, whether eVatR needs a registration (its documentation names none), how many qualified confirmations the BZSt allows per session (`evatr-0008`), and the form of `gueltigAb`/`gueltigBis`, which are passed on as the BZSt writes them. The OpenAPI document lists `evatr-0008` under HTTP 400 and the status list under 403, so the client decides by the code.
+
 ## Behavior And Caveats
 
 - Historical market data is cached aggressively because it is treated as immutable.
@@ -532,7 +579,7 @@ The base rate of `@fin.cx/opendata/baserate` (`ts/baserate/data.baserate.ts`) is
 pnpm test
 ```
 
-Some market data tests hit live remote services, so they may depend on network access or optional API credentials. The register lookup is tested against minimal hand-written pages and structured content with synthetic values only; the tests never contact the register portal.
+Some market data tests hit live remote services, so they may depend on network access or optional API credentials. The register lookup is tested against minimal hand-written pages and structured content with synthetic values only; the tests never contact the register portal. The VAT ID clients are tested against the answers the two services gave on 2026-09-27 to their documented test values (`test/fixtures/vatid/`); the tests never contact them.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '4.2.0',
+  version: '4.3.0',
   description: 'Open business and financial data for TypeScript: register lookups on the German register portal (handelsregister.de) without storage, the statutory public holidays of the German federal states, the base rate of § 247 BGB, and stock and crypto prices and fundamentals from several providers.'
 }

package/ts/vatid/classes.evatrclient.ts

@@ -0,0 +1,182 @@
+import { VatIdError, type TVatIdErrorCode } from './classes.vatiderror.js';
+import { evatrBaseUrl, evatrConfirmationPath, evatrStatusCodes } from './constants.js';
+import type {
+  IEvatrConfirmation,
+  IEvatrConfirmationInput,
+  IVatIdClientOptions,
+  IVatIdTraderData,
+  TEvatrFieldResult,
+  TEvatrQualifiedResult,
+  TEvatrStatusCode,
+} from './interfaces.js';
+import { postJson, textField } from './request.js';
+import { splitVatId } from './vatid.js';
+
+/** The status codes that are an answer about the VAT ID asked about, and whether they say it is valid. */
+const ANSWERS: Readonly<Partial<Record<TEvatrStatusCode, boolean>>> = {
+  'evatr-0000': true,
+  'evatr-2008': true,
+  'evatr-2001': false,
+  'evatr-2002': false,
+  'evatr-2006': false,
+};
+
+/** What every other status code means for the caller (`VatIdError`). */
+const REFUSALS: Readonly<Partial<Record<TEvatrStatusCode, TVatIdErrorCode>>> = {
+  'evatr-0001': 'invalid_input',
+  'evatr-0002': 'invalid_input',
+  'evatr-0003': 'invalid_input',
+  'evatr-0004': 'requester_invalid',
+  'evatr-0005': 'vat_id_malformed',
+  'evatr-0006': 'not_permitted',
+  'evatr-0007': 'invalid_input',
+  'evatr-0008': 'qualified_limit_reached',
+  'evatr-0011': 'unavailable',
+  'evatr-0012': 'vat_id_malformed',
+  'evatr-0013': 'unavailable',
+  'evatr-1001': 'unavailable',
+  'evatr-1002': 'unavailable',
+  'evatr-1003': 'unavailable',
+  'evatr-1004': 'unavailable',
+  'evatr-2003': 'vat_id_malformed',
+  'evatr-2004': 'unavailable',
+  'evatr-2005': 'requester_invalid',
+  'evatr-2007': 'member_state_unavailable',
+  'evatr-2011': 'unavailable',
+  'evatr-3011': 'unavailable',
+};
+
+const FIELD_RESULTS: readonly TEvatrFieldResult[] = ['A', 'B', 'C', 'D'];
+
+const fieldResult = (bodyArg: unknown, keyArg: string): TEvatrFieldResult | undefined => {
+  const value = textField(bodyArg, keyArg);
+  return value !== undefined && (FIELD_RESULTS as readonly string[]).includes(value) ? (value as TEvatrFieldResult) : undefined;
+};
+
+/**
+ * The BZSt's confirmation of foreign VAT IDs (§ 18e Nr. 1 UStG) over its eVatR REST API
+ * (`https://api.evatr.vies.bzst.de/api-docs`). A simple confirmation says whether a VAT ID is valid
+ * when asked; a qualified one also compares the business's name, city, and where given street and
+ * postal code with what its member state registered. The BZSt confirms to a business with a German
+ * VAT ID of its own, which every request names. Nothing is kept: each answer goes to the caller.
+ */
+export class EvatrClient {
+  constructor(private readonly options: IVatIdClientOptions = {}) {}
+
+  public async confirm(inputArg: IEvatrConfirmationInput): Promise<IEvatrConfirmation> {
+    const requester = splitVatId(inputArg.requesterVatId);
+    if (!requester || requester.countryCode !== 'DE') {
+      throw new VatIdError('invalid_input', 'the requester is named by its German VAT ID', { service: 'bzst-evatr', field: 'requesterVatId' });
+    }
+    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: 'bzst-evatr', field: 'vatId' });
+    }
+    const trader = inputArg.trader ? traderOf(inputArg.trader) : undefined;
+    if (inputArg.trader && !trader) {
+      throw new VatIdError('invalid_input', 'a qualified confirmation needs the name and the city', { service: 'bzst-evatr', field: 'trader' });
+    }
+    const answer = await postJson(this.options, 'bzst-evatr', `${this.options.baseUrl ?? evatrBaseUrl}${evatrConfirmationPath}`, {
+      anfragendeUstid: requester.vatId,
+      angefragteUstid: asked.vatId,
+      ...(trader
+        ? {
+          firmenname: trader.name,
+          ort: trader.city,
+          ...(trader.street ? { strasse: trader.street } : {}),
+          ...(trader.postalCode ? { plz: trader.postalCode } : {}),
+        }
+        : {}),
+    }, inputArg.signal);
+    const status = textField(answer.body, 'status');
+    if (!status || !(evatrStatusCodes as readonly string[]).includes(status)) {
+      throw new VatIdError('unexpected_answer', `the BZSt answered HTTP ${answer.httpStatus} without a status it documents`, {
+        service: 'bzst-evatr',
+        httpStatus: answer.httpStatus,
+        ...(status ? { serviceCode: status } : {}),
+        answer: answer.answer,
+      });
+    }
+    const code = status as TEvatrStatusCode;
+    const valid = ANSWERS[code];
+    if (valid === undefined) {
+      throw new VatIdError(REFUSALS[code] ?? 'unexpected_answer', `the BZSt answered ${code}`, {
+        service: 'bzst-evatr',
+        serviceCode: code,
+        httpStatus: answer.httpStatus,
+        answer: answer.answer,
+      });
+    }
+    const requestedAt = textField(answer.body, 'anfrageZeitpunkt');
+    const requestedAtMs = requestedAt ? Date.parse(requestedAt) : Number.NaN;
+    if (!requestedAt || Number.isNaN(requestedAtMs)) {
+      throw new VatIdError('unexpected_answer', 'the BZSt answered without the moment of the request', {
+        service: 'bzst-evatr',
+        serviceCode: code,
+        httpStatus: answer.httpStatus,
+        answer: answer.answer,
+      });
+    }
+    const requestId = textField(answer.body, 'id');
+    const validFrom = textField(answer.body, 'gueltigAb');
+    const validTo = textField(answer.body, 'gueltigBis');
+    const qualified = trader && valid ? qualifiedResultOf(trader, code, answer.body) : undefined;
+    if (qualified === null) {
+      // a qualified request answered valid without a result for each field sent would read as a simple
+      // confirmation; it is refused instead of being passed on as one
+      throw new VatIdError('unexpected_answer', `the BZSt answered ${code} to a qualified request without a documented result for each field sent`, {
+        service: 'bzst-evatr',
+        serviceCode: code,
+        httpStatus: answer.httpStatus,
+        answer: answer.answer,
+      });
+    }
+    return {
+      service: 'bzst-evatr',
+      ...(requestId ? { requestId } : {}),
+      requestedAt,
+      requestedAtMs,
+      status: code as IEvatrConfirmation['status'],
+      valid,
+      ...(validFrom ? { validFrom } : {}),
+      ...(validTo ? { validTo } : {}),
+      requesterVatId: requester.vatId,
+      vatId: asked.vatId,
+      ...(qualified ? { qualified } : {}),
+      answer: answer.answer,
+    };
+  }
+}
+
+/**
+ * The comparison of a qualified request whose VAT ID is valid: `evatr-2008` says it has a
+ * particularity and gives no result (`answered: false`); otherwise every field sent has a documented
+ * result (`A`…`D`), or the answer is not one this client reads (`null`). A result the BZSt gives for a
+ * field not sent is kept as it is.
+ */
+const qualifiedResultOf = (traderArg: IVatIdTraderData, codeArg: TEvatrStatusCode, bodyArg: unknown): TEvatrQualifiedResult | null => {
+  if (codeArg === 'evatr-2008') {
+    return { asked: traderArg, answered: false };
+  }
+  const name = fieldResult(bodyArg, 'ergFirmenname');
+  const city = fieldResult(bodyArg, 'ergOrt');
+  // a field not sent may still carry its result (`C`, not asked); one sent must
+  const street = fieldResult(bodyArg, 'ergStrasse');
+  const postalCode = fieldResult(bodyArg, 'ergPlz');
+  if (!name || !city || (traderArg.street && !street) || (traderArg.postalCode && !postalCode)) {
+    return null;
+  }
+  return { asked: traderArg, answered: true, name, city, ...(street ? { street } : {}), ...(postalCode ? { postalCode } : {}) };
+};
+
+/** The business data as a qualified confirmation sends it: trimmed, with the name and the city required. */
+export const traderOf = (traderArg: IVatIdTraderData): IVatIdTraderData | undefined => {
+  const name = traderArg.name.trim();
+  const city = traderArg.city.trim();
+  if (!name || !city) {
+    return undefined;
+  }
+  const street = traderArg.street?.trim();
+  const postalCode = traderArg.postalCode?.trim();
+  return { name, city, ...(street ? { street } : {}), ...(postalCode ? { postalCode } : {}) };
+};