Node-SDK

Die API aus JavaScript und TypeScript.

Das Node-SDK bringt einen Client für JavaScript und TypeScript, mit Typdefinitionen für Anfragen und Antworten. Es wiederholt vorübergehende Fehler selbst und wandelt Fehlerantworten in eigene Fehlerklassen um.

Installieren

Installiere das Paket handelsregister mit npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=DEIN_API_SCHLUESSEL

Was
Was	Wert
Paket	`handelsregister`
Aktuelle Version	0.7.0
Node.js	22.13 oder neuer
TypeScript	Typdefinitionen enthalten
Lizenz	AGPL-3.0
Quellcode	github.com/Handelsregister-AI/handelsregister-js

Das SDK liest deinen API-Schlüssel aus der Umgebungsvariablen HANDELSREGISTER_API_KEY. Du kannst ihn auch beim Erstellen des Clients übergeben. Ein Bearer-Token geht über HANDELSREGISTER_BEARER_TOKEN oder bearerToken. Der Schlüssel steht immer im Header, nie in der URL.

Erste Anfrage

fetchOrganization ruft ein Firmenprofil ab und gibt die Antwort der API als Objekt zurück. Der Parameter q nimmt einen Namen, Registergericht mit Registernummer oder eine entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

const client = new Handelsregister({ apiKey: process.env.HANDELSREGISTER_API_KEY });

const firma = await client.fetchOrganization({ q: 'Hetzner Online GmbH' });
console.log(firma.entity_id, firma.name);
console.log(firma.registration); // { court: 'Ansbach', register_type: 'HRB', register_number: '6089' }
console.log(firma.meta.request_credit_cost);

Die Antwort ist dieselbe wie bei fetch-organization. Hier ein Ausschnitt:

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "status": "ACTIVE",5  "legal_form": "GmbH",6  "registration": {7    "court": "Ansbach",8    "register_type": "HRB",9    "register_number": "6089"10  },11  "meta": {12    "request_credit_cost": 5,13    "credits_remaining": 14514  }15}

200 · Ausschnitt aus unserer Beispielantwort für die Hetzner Online GmbH, Ansbach HRB 6089, nur Basisdaten

Weitere Daten forderst du mit features an, den AI-Mode mit aiSearch: true und Echtzeit mit realtimeMode: true. Alle Features stehen bei fetch-organization.

JavaScript

const firma = await client.fetchOrganization({
  q: 'Ansbach HRB 6089',
  features: ['financial_kpi', 'related_persons'],
});

Gleiche Anfragen beantwortet der Client eine Stunde lang aus seinem Zwischenspeicher, ohne neue Credits. Anfragen mit Echtzeit gehen immer an die API. Mit cacheEnabled: false schaltest du den Zwischenspeicher ab.

Fehler behandeln

Jede Fehlerantwort der API wird zu einem Fehler mit eigener Klasse. Alle erben von HandelsregisterError und tragen statusCode, die Antwort in response und die Kosten in meta.

Exception
Exception	Status	Bedeutung
AuthenticationError	401	Kein oder ein ungültiger API-Schlüssel.
InsufficientCreditsError	402	Das Guthaben reicht nicht für diese Anfrage.
SubscriptionRequiredError	403	Die Anfrage braucht einen höheren Plan. `requiredPlans` nennt die passenden Pläne.
NotFoundError	404	Keine passende Firma oder Person gefunden.
RequestTimeoutError	408	Das Register hat nicht rechtzeitig geantwortet. Es wurde nichts berechnet.
RequestValidationError	400, 422	Ein Parameter hat einen ungültigen Wert.
RateLimitError	429	Zu viele Anfragen pro Minute.
ServerError	5xx	Die Datenquelle ist gerade nicht erreichbar oder ausgelastet. Später wiederholen.

JavaScript

import {
  Handelsregister,
  HandelsregisterError,
  InsufficientCreditsError,
  NotFoundError,
  RequestTimeoutError,
} from 'handelsregister';

const client = new Handelsregister({ timeout: 120000 });

try {
  const firma = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Keine passende Firma gefunden');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Guthaben reicht nicht:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Register antwortet gerade nicht, später erneut versuchen');
  } else if (error instanceof HandelsregisterError) {
    console.log('Fehler:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Bei Netzwerkfehlern, dem Status 429 und Serverfehlern versucht es das SDK selbst erneut, mit bis zu drei Versuchen insgesamt. Schickt die API eine Wartezeit in Retry-After, hält es sich daran.

Der Client wartet standardmäßig 90 Sekunden auf eine Antwort. Für Echtzeit, Personenprofile und Dokumente empfehlen wir mindestens 120 Sekunden, also timeout: 120000.

Kommandozeile

Mit dem Paket kommt das Programm handelsregister. Es ruft Firmenprofile, Personenprofile und Dokumente ab, sucht Firmen und reichert Dateien an.

Terminal

# Firmenprofil ohne AI-Mode, nur mit Finanz-KPIs
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Gesellschafterliste als PDF speichern
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

handelsregister fetch schaltet ohne weitere Angabe den AI-Mode ein. Eine Anfrage kostet dann 25 Credits statt 5, auch ohne Features. Mit --no-ai-search fragst du ohne AI-Mode an.

handelsregister document sucht die Firma zuerst über ein Firmenprofil ohne AI-Mode. Zu den 15 Credits des Dokuments kommen deshalb 5 Credits dazu.

Referenz

Die vollständige Referenz mit allen Methoden steht im README des Repositorys. Das SDK deckt die ganze API ab:

Firmenprofile mit allen Features, auch als Klasse Company
Personenprofile, auch als Klasse Person
Suche & Export mit Filtern, Sortierung und automatischem Blättern
Dokumente als Datei
Signals, Monitoring und Webhook-Endpoints, mit Prüfung der Webhook-Signatur
Konto, Guthaben, Nutzung und API-Schlüssel
Anreicherung ganzer CSV-, JSON- und Excel-Dateien

Das SDK steht unter der Lizenz AGPL-3.0. Den Quellcode findest du auf GitHub, das Paket auf npm.

fetch-organization Alle Parameter, Features und Felder des Firmenprofils. Python-SDK Dieselbe API aus Python.