Installation und Authentifizierung

npm install handelsregister

export HANDELSREGISTER_API_KEY=your-api-key

Das SDK sendet Zugangsdaten ausschließlich als x-api-key oder Authorization: Bearer … Header, nie in URLs. Ein API-Key ist der Standard; Bearer-Tokens eignen sich für zeitlich begrenzte Berechtigungen und haben Vorrang, wenn beides vorhanden ist. Zusätzliche Header für Gateway oder Proxy übergibst du mit extraHeaders oder HANDELSREGISTER_EXTRA_HEADERS; die Authentifizierungs- und User-Agent-Header des SDKs bleiben geschützt.

const { Handelsregister, Company } = require('handelsregister');

const client = new Handelsregister({
  apiKey: process.env.HANDELSREGISTER_API_KEY,
  timeout: 60_000,
  cacheEnabled: true,
  rateLimit: 1,
});

// Bearer tokens take precedence over API keys.
const tokenClient = new Handelsregister({
  bearerToken: process.env.HANDELSREGISTER_BEARER_TOKEN,
});

Unternehmen, Personen und Suche

fetchOrganization() liefert typisierte Daten mit den gewünschten Features. aiSearch akzeptiert einen Boolean oder "on-default"/"off"; realtimeMode akzeptiert einen Boolean oder "handelsregister-default". Die Wrapper Company und Person laden Daten bei Bedarf und bieten praktische Eigenschaften.

const data = await client.fetchOrganization({
  q: 'KONUX GmbH München',
  features: ['related_persons', 'financial_kpi', 'mergers_and_acquisitions'],
  aiSearch: true,
  realtimeMode: false, // true triggers a live lookup (+10 credits)
});

const company = new Company('OroraTech GmbH München', process.env.HANDELSREGISTER_API_KEY);
console.log(await company.getName(), company.registerNumber);
console.log(data.representation_scheme?.current);

searchOrganizations() unterstützt alle dokumentierten Filter für Identität, Branche, Status, Standort und Radius, Register, Beschäftigte, Bilanz und GuV. q ist optional, sobald du Filter setzt. Das SDK übersetzt flache Finanzfilter in das aktuelle verschachtelte Wire-Format und ordnet company_size_category dem aktuellen Wire-Namen emp_size_category zu. Pro Anfrage sind höchstens 30 Ergebnisse möglich; jede Iterator-Seite wird separat berechnet.

const result = await client.searchOrganizations({
  q: 'tech',
  limit: 20,
  filters: {
    postal_code: '80331',
    legal_form_code: ['GmbH', 'UG'],
    active: true,
    pl_revenue: { gte: 1_000_000, lte: 5_000_000 },
  },
  aiMode: false,
});

for await (const organization of client.iterateSearchOrganizations({
  q: 'technology München', pageSize: 30, maxResults: 100,
})) {
  console.log(organization.entity_id, organization.name);
}

fetchPerson() verwendet immer KI-Anreicherung (15 Credits Grundpreis); shareholdings kostet nur bei gelieferten Daten weitere 5 Credits. fetchDocument() akzeptiert Positions- oder Objektparameter und liefert einen Buffer oder schreibt eine Datei. Mit fetchDocumentWithMetadata() erhältst du zusätzlich Content-Type und Server-Dateinamen. Verfügbare Typen sind shareholders_list, articles_of_association, AD, CD und SI.

Signals

Signals liefern Handelsregisterveränderungen mit Cursor-Pagination. Der Katalog ist kostenlos; erfolgreiche Listen- und Detailanfragen kosten jeweils 20 Credits. Eine Seite enthält 20 Einträge.

const { SignalTopic } = require('handelsregister');

const filters = {
  topics: [SignalTopic.CAPITAL_CHANGES, SignalTopic.TRANSFORMATIONS],
  organizationIds: ['organization-id-one', 'organization-id-two'],
  fromDate: '2026-07-01',
  toDate: '2026-07-30',
};

const page = await client.listSignals(filters);
const catalog = await client.getSignalCatalog();
const detail = await client.getSignal(page.signals[0].event.id);

for await (const signal of client.iterateSignals({
  topics: [SignalTopic.NEW_REGISTRATIONS], maxResults: 50,
})) {
  console.log(signal.event.id, signal.organization?.entity_id);
}

Für manuelle Pagination behältst du die Filter bei und übergibst pagination.next_cursor unverändert. Mehrere Unternehmens-IDs verwenden ODER-Semantik. Die sieben Topics sind NEW_REGISTRATIONS, MASTER_DATA_CHANGES, CLOSURES, ROLE_HOLDER_CHANGES, CAPITAL_CHANGES, INSOLVENCIES (Pro/Max) und TRANSFORMATIONS (Max). HTTP 403 PLAN_REQUIRED wird als SubscriptionRequiredError dargestellt und kostet keine Credits.

Konto und Nutzung

Kontoanfragen sind kostenlos. Mit API-Key oder Bearer-Token mit account:read kannst du Profil, Credits, Nutzung, Abo und maskierte API-Keys abfragen. Zeiträume sind auf 366 Tage begrenzt; Transaktionen verwenden undurchsichtige Cursor. API-Keys kannst du mit einem im Dashboard erstellten Bearer-Token mit account:keys erstellen oder widerrufen. Den vollständigen Key bekommst du nur einmal.

const account = await client.getAccount();
const credits = await client.getAccountCredits();
const subscription = await client.getAccountSubscription();
const keys = await client.listApiKeys();

for await (const transaction of client.iterateAccountUsageTransactions({
  perPage: 100,
})) {
  console.log(transaction.endpoint, transaction.credits);
}

Monitoring und Webhooks

Monitoring beobachtet Unternehmen und sendet normalisierte Signals an HTTPS-Endpunkte. Lese- und Verwaltungsanfragen sind kostenlos; ein aktivierter Monitor beginnt mit dem aktuellen Mindestbetrag von 10 Credits pro Zyklus. Rufe getMonitoringPricing() auf, bevor du einen Monitor erstellst oder fortsetzt. Für den Monitor-Lebenszyklus brauchst du account:read und monitoring:manage; die Webhook-Endpunktverwaltung benötigt account:read und account:keys.

const admin = new Handelsregister({ bearerToken: process.env.ADMIN_TOKEN });
const createdEndpoint = await admin.createWebhookEndpoint({
  name: 'Production receiver',
  url: 'https://hooks.example.com/handelsregister',
  headers: { 'x-tenant': 'customer-42' },
});
const endpointId = createdEndpoint.endpoint.id;
const signingSecret = createdEndpoint.signing_secret; // returned only once

await admin.verifyWebhookEndpoint(endpointId);
await admin.testWebhookEndpoint(endpointId);

const monitor = (await client.createMonitor({
  entityId: 'organization-entity-id',
  pollIntervalDays: 7,
  endpointIds: [endpointId],
  label: 'Important customer',
})).monitor;

await client.pauseMonitor(monitor.id);
await client.resumeMonitor(monitor.id);
await client.archiveMonitor(monitor.id);

Speichere das einmalig ausgegebene Signing-Secret sofort. Monitoring-Änderungen erhalten automatisch einen Idempotency-Key, der bei sicheren Wiederholungen weiterverwendet wird. Mit idempotencyKey machst du Wiederholungen nach Neustarts dauerhaft sicher und client.lastIdempotencyStatus zeigt ihren Status. HTTP-409-Mehrdeutigkeiten werden nie wiederholt. Prüfe Raw-Bytes mit constructEvent(), beantworte Verifizierungs-Challenges mit verificationResponseHeaders() und dedupliziere mindestens-einmal zugestellte Events anhand ihrer ID.

Tokens, Anreicherung und CLI

Bearer-Tokens kannst du erstellen, auflisten, einzeln oder bewusst alle widerrufen. Die Batch-Anreicherung unterstützt CSV, JSON und XLSX mit Snapshots. Die enthaltene CLI deckt Lookups, reine Filtersuche, Dokumente, Anreicherung, Monitoring, Webhook-Endpunkte, Zustellungen und Events ab.

const { token } = await client.createToken({
  tokenName: 'ci-pipeline',
  abilities: ['*'],
  expiresAt: '2027-01-01 00:00:00',
});
const { tokens } = await client.listTokens();
await client.revokeToken(tokens[0].id);

await client.enrich({
  filePath: 'companies.csv',
  inputType: 'csv',
  queryProperties: { company_name: 'name', city: 'location' },
  snapshotDir: './snapshots',
  params: { features: ['financial_kpi', 'related_persons'] },
});

handelsregister fetch "KONUX GmbH München" --feature financial_kpi
handelsregister search --filters '{"legal_form_code":"GmbH"}' --limit 30
handelsregister document "KONUX GmbH" --type SI --output konux.xml
handelsregister enrich companies.csv --feature related_persons
handelsregister monitors pricing --interval 7
handelsregister webhooks events

TypeScript, Features und Fehler

Das Paket ist in TypeScript geschrieben und bringt vollständige Typdefinitionen mit. Verfügbare Features sind related_persons, financial_kpi, balance_sheet_accounts, profit_and_loss_account, publications, annual_financial_statements, annual_financial_statements__html, insolvency_publications, shareholders, ubos, shareholdings, mergers_and_acquisitions, news und website_content. Aktuelle Antworten verwenden verschachtelte Strukturen wie contact_data und representation_scheme; publications kommt als history zurück.

import { Handelsregister, CompanyData, Feature } from 'handelsregister';

const features: Feature[] = ['financial_kpi', 'related_persons'];
const data: CompanyData = await client.fetchOrganization({
  q: 'company name',
  features,
});

Fehler enthalten response, statusCode, responseHeaders und errorCode. Nutze die spezifischen Fehlerklassen für Authentifizierung, Credits, Abos, Idempotenzkonflikte, Dienstverfügbarkeit, nicht gefundene Einträge, Timeouts, Rate Limits und Validierung. Ältere Basisklassen bleiben mit instanceof kompatibel. Lege API-Keys, Bearer-Tokens und Webhook-Secrets niemals im Quellcode ab.