@firmenakte/api-client

TypeScript/JavaScript client for the Firmenakte API.

Installation

npm install @firmenakte/api-client

or with pnpm:

pnpm add @firmenakte/api-client

Quick start

import { createApiClient } from "@firmenakte/api-client";

const api = createApiClient({
  apiKey: "your-api-key",
  baseUrl: "https://api.firmenakte.at", // optional, defaults to production
  timeoutMs: 10_000, // optional, defaults to 10 seconds
});

// Use the API, e.g. list businesses
const { data } = await api.v1BusinessesList();

The timeout starts separately for every request and also covers reading its response body. Pass an AbortSignal in an endpoint's request parameters when the caller needs to cancel sooner:

const controller = new AbortController();
const request = api.v1BusinessesList(undefined, { signal: controller.signal });
controller.abort();
await request;

v2

The v2 API is the subpath @firmenakte/api-client/v2; the package's root export stays v1. Its client has one method per operation, named by the operation's operationId in the v2 reference:

import { createApiClient, isApiError } from "@firmenakte/api-client/v2";

const client = createApiClient({ apiKey: process.env.FIRMENAKTE_KEY });
const { data: company, response } = await client.getCompany({ path: { id: "fnr:56247t" } });
console.log(company.name, response.headers.get("X-Credits-Charged"));

try {
  await client.getCompany({ path: { id: "fnr:999999x" } });
} catch (error) {
  if (!isApiError(error)) throw error; // no answer: network failure, timeout or abort
  console.log(error.status, error.problem?.detail);
}

Each method takes { path, query, body, headers } as the operation defines them, plus any fetch option such as signal; path parameters are encoded for you. A 2xx answer resolves with { data, request, response }. Anything else rejects with an ApiError: status, the problem JSON as problem, and the response. File downloads (getExportFile, getDocumentContent, getLicenseExtract) take parseAs: "blob" or "stream".

Credits and rate limits

API calls use your account's weekly credits, shared across all its keys. Free includes 50, Starter 500, Business 5,000, and Enterprise an agreed allowance. It resets on Monday at 00:00 UTC. Purchased credits never expire and pay for calls the weekly allowance cannot cover. See credit pricing.

Operations declare x-credit-class in the OpenAPI spec: basic costs 1 credit and expensive costs 3. Charged responses include X-Credits-Charged and X-Credits-Remaining. The client exposes these on the response's headers:

const response = await api.v1BusinessesList();
const charged = response.headers.get("X-Credits-Charged");
const remaining = response.headers.get("X-Credits-Remaining");

Endpoint responses cost credits even for 400 or 404. Authentication failures, 401, requests rejected with 429, and server errors, 5xx, cost no credits. Credit exhaustion returns 429, an error message starting with Credits aufgebraucht, and Retry-After in seconds until Monday 00:00 UTC. The separate burst limit returns Retry-After: 60. A longer wait means credit exhaustion; near Monday, check the error message because the reset can be 60 seconds or less away.

Documentation

Full API reference, authentication, and guides: https://docs.firmenakte.at