Das neue Node.js Package für das Handelsregister

Das neue Node.js SDK von handelsregister.ai liefert umfassende Unternehmensdaten: Managementinformationen, Finanzberichte und vieles mehr. Mit diesem offiziellen handelsregister.ai NPM-Paket kannst du ab sofort noch einfacher auf strukturierte Firmendaten des deutschen Handelsregisters zugreifen und sie in deinen Node.js-Projekten nutzen. Ob du Finanzkennzahlen analysieren, Führungskräfte abfragen oder große Datensätze anreichern möchtest – mit diesem Paket hast du alle wichtigen Funktionen in einem schlanken, modernen Client vereint.

Neues Node.js-Paket für den Zugriff auf das Handelsregister veröffentlicht

Wir freuen uns, dir heute unser brandneues Node.js SDK für die handelsregister.ai-API vorzustellen. Damit erhalten nun auch JavaScript/TypeScript-Entwickler:innen einen einfachen Weg, aktuelle Firmendaten aus dem deutschen Handelsregister in ihre Anwendungen zu integrieren. Das SDK kapselt die REST-API von handelsregister.ai und bietet bequeme Methoden, um Unternehmensinformationen programmgesteuert abzurufen – ohne sich mit unstrukturierten PDF-Dokumenten oder komplexen Schnittstellen beschäftigen zu müssen.

Was kann das neue Paket?

• Einfache Suche: Finde Unternehmen anhand von Namen, Standorten und weiteren Parametern.
• Finanzdaten: Greife auf Jahresabschlüsse, Finanz-KPIs sowie Gewinn- und Verlustrechnungen zu.
• Management-Informationen: Erfahre mehr über aktuelle und ehemalige Führungskräfte, inklusive Rollen und Amtszeiten.
• Detaillierte Firmendaten: Erhalte umfassende Infos zu Rechtsform, Status, Registernummer, Unternehmenszweck und mehr.
• Batch-Processing: Automatisiere die Anreicherung großer Firmendatenbestände mit aktuellen Registerdaten.
• Resilientes Design: Dank eingebauter Fehlertoleranz (Retries, Caching, Snapshots) musst du dir auch bei komplexen Abfragen keine Sorgen machen.

Diese Funktionen vereinfachen zahlreiche Anwendungsfälle – von der gezielten Unternehmenssuche bis zur automatischen Datenanreicherung in großem Maßstab. Besonders Startups und Entwickler:innen in Deutschland profitieren davon, dass sie offizielle Firmendaten nun schnell und unkompliziert in ihre Produkte einbinden können, ohne eigene Scraper oder manuelle Prozesse entwickeln zu müssen.

Installation und erster Einstieg

Die Installation ist denkbar einfach. Du kannst das Paket direkt über npm installieren:

npm install handelsregister

Anschließend musst du nur noch deinen API-Key von handelsregister.ai hinterlegen – entweder als Umgebungsvariable oder direkt im Code. Der empfohlene Weg ist die Umgebungsvariable HANDELSREGISTER_API_KEY:

export HANDELSREGISTER_API_KEY=YOUR_API_KEY

Alternativ kannst du den API-Key auch beim Initialisieren des Clients übergeben.

Beispiel 1: Quick Start

Mit nur wenigen Zeilen Code kannst du direkt auf Unternehmensinformationen zugreifen. Das folgende Beispiel zeigt, wie du das SDK einsetzt, um Firmendaten zu einer Suche abzurufen:

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

// Client initialisieren (API-Key aus Umgebungsvariable oder direkt übergeben)
const client = new Handelsregister();  // nutzt automatisch HANDELSREGISTER_API_KEY

// Unternehmensinformationen abrufen (Suche nach Namen + Standort)
const companyData = await client.fetchOrganization('KONUX GmbH München');
console.log(companyData.name);               // z.B. "KONUX GmbH"
console.log(companyData.status);             // z.B. "aktiv"
console.log(companyData.registrationNumber); // z.B. "HRB 30065"

Damit stehen dir sofort wichtige Basisinformationen zur Verfügung – ideal, wenn du schnell einen Überblick zu einer Firma bekommen willst. Im obigen Beispiel suchen wir nach "KONUX GmbH München" und geben den Namen, Status und die Handelsregister-Nummer des gefundenen Unternehmens aus. Selbstverständlich kannst du anstelle eines Firmennamens auch andere Kriterien wie Standort oder Registergericht in die Suche einbeziehen.

Beispiel 2: Objektorientierte Nutzung

Wenn du lieber mit Objektinstanzen arbeiten möchtest, bietet das SDK eine praktische Klassenschnittstelle. Über die Klasse Company kannst du auf Unternehmensdaten zugreifen, als wäre jede Firma ein Objekt mit Eigenschaften und Methoden:

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

// Company-Objekt mit Suchbegriff und optionalen Features instanziieren
const company = new Company('OroraTech GmbH München');  // API-Key wird intern verwendet

// Basisinformationen
console.log(`Name: ${company.name}`);                     // Name der Firma 
console.log(`Registernummer: ${company.registerNumber}`); // z.B. "HRB 251311"
console.log(`Status: ${company.status}`);                 // "aktiv" oder "inaktiv"
console.log(`Adresse: ${company.address}`);               // vollständige Adresse

// Managementinformationen 
for (const person of company.currentRelatedPersons) {
  console.log(`Manager: ${person.name} – Rolle: ${person.role.de.long}`);
}

// Finanzdaten (aktuellstes Jahr)
if (company.latestFinancialKPI) {
  const kpi = company.latestFinancialKPI;
  console.log(`Umsatz (${kpi.year}): ${kpi.revenue}`);
  console.log(`Mitarbeiter (${kpi.year}): ${kpi.employees}`);
}

In diesem Beispiel erstellen wir ein Company-Objekt für OroraTech GmbH München. Das Objekt bietet direkt zugreifbare Eigenschaften wie Name, Registernummer, Status oder die formatierte Adresse. Außerdem können wir über Listen von currentRelatedPersons und pastRelatedPersons bequem die aktuellen bzw. ehemaligen Geschäftsführer abrufen. Die Finanzdaten liegen in strukturierter Form vor – etwa Umsatz oder Mitarbeiterzahl pro Jahr – und lassen sich über Methoden wie latestFinancialKPI oder getFinancialKPIByYear() auslesen.

Diese objektorientierte Herangehensweise eignet sich besonders, wenn du wiederholt auf dieselben Unternehmensdaten zugreifen willst oder mehrere Firmen parallel behandelst. Das SDK kümmert sich um die Abfragen im Hintergrund, während du in deinem Code mit übersichtlichen Objekten arbeitest.

Beispiel 3: Batch-Processing & Datenanreicherung

Gerade wenn du sehr viele Datensätze gleichzeitig verarbeiten möchtest, kann das SDK eine große Zeitersparnis sein. Mit der integrierten enrich-Methode lässt sich z.B. eine Liste von Unternehmen automatisch mit Registerdaten anreichern, ohne jede Firma einzeln abfragen zu müssen.

Angenommen, du hast eine CSV-Datei mit Firmen, die du um aktuelle Registerinfos erweitern willst – dann kannst du Folgendes tun:

// Beispiel: 'companies.csv' mit Spalten "company_name" und "city"
await client.enrich({
  filePath: 'companies.csv',
  inputType: 'csv',
  queryProperties: {
    company_name: 'name',  // CSV-Spalte 'company_name' als Such-Name nutzen 
    city: 'location'       // CSV-Spalte 'city' als Such-Ort nutzen
  },
  snapshotDir: './snapshots',   // optional: Zwischenergebnisse speichern
  params: {
    features: ['related_persons', 'financial_kpi'] // zusätzliche Daten anfordern
  }
});

In diesem Aufruf liest das SDK alle Einträge aus der Datei companies.csv, ruft für jede Zeile die aktuellen Firmendaten ab und schreibt die angereicherten Daten zurück (standardmäßig erstellt es eine neue Datei mit den Ergebnissen). Über queryProperties wird dabei konfiguriert, welche Felder der Eingabedatei als Suchparameter dienen (hier Name und Ort der Firma). Auf diese Weise kannst du beispielsweise große Listen von Unternehmen mit aktuellen Finanz- und Managementdaten automatisiert ergänzen, ohne jede Firma manuell einzeln abzufragen. Dank Snapshotting setzt das Tool abgebrochene Vorgänge an der letzten Stelle fort, sodass du dir keine Sorgen machen musst, falls ein Durchlauf unterbrochen wird – perfekt für die zuverlässige Verarbeitung von Batch-Jobs.

Features und Properties im Überblick

Falls du dich fragst, welche Datenpunkte konkret abrufbar sind, hier ein kurzer Überblick. Bei jeder Abfrage lassen sich sogenannte Features aktivieren, mit denen du festlegst, welche zusätzlichen Informationen du erhalten möchtest (standardmäßig liefert die API Grunddaten wie Name, Adresse, Registereintrag etc.):

Zusätzlich stellt die Company-Klasse zahlreiche Properties (Eigenschaften) zur Verfügung, mit denen du bequem auf einzelne Datenfelder zugreifen kannst. Einige Beispiele:

// Basisinformationen
company.name               // Unternehmensname
company.entityId           // eindeutige Kennung (UUID)
company.status             // Aktiv/Inaktiv-Status
company.legalForm          // Rechtsform (z.B. "GmbH")
company.registerNumber     // Handelsregister-Nummer

// Adresse
company.address            // Vollständige Adresse als String
company.street             // Straße
company.postalCode         // Postleitzahl
company.city               // Ort/Sitz

// Management
company.currentRelatedPersons   // Aktuelle Geschäftsführung / Management
company.pastRelatedPersons      // Ehemalige Geschäftsführung
company.getRelatedPersonsByRole('Geschäftsführer')  // Personen nach Rolle filtern

// Finanzdaten
company.financialKPIs           // Finanzkennzahlen (alle Jahre verfügbar)
company.latestFinancialKPI      // Finanzkennzahlen des jüngsten Jahres
company.getFinancialKPIByYear(2023)  // Finanzkennzahlen für ein bestimmtes Jahr

// Dokumente
await company.fetchDocument('shareholders_list', 'unternehmen.pdf')  // z.B. Gesellschafterliste herunterladen

Wie man sieht, erhältst du über diese Properties direkten Zugriff auf nahezu alle wichtigen Unternehmensdaten – von der Adresse über Registerdetails bis hin zu Finanzzahlen und Personen im Management. Das macht die Integration in eigene Anwendungen sehr komfortabel: Die gelieferten Daten sind bereits geparst und strukturiert, sodass du sie unmittelbar weiterverarbeiten kannst.

Warum lohnt sich der Einsatz?

Mit dem Handelsregister Node.js SDK sparst du viel Zeit und Nerven, wenn du Daten aus dem deutschen Handelsregister automatisiert verarbeiten möchtest. Anstatt dich durch unstrukturierte PDF-Dokumente zu kämpfen oder eigene Schnittstellen zu entwickeln, kannst du jetzt auf eine gut dokumentierte, robuste Bibliothek zurückgreifen. Du erhältst Zugriff auf aktuelle Managementdaten, Finanzkennzahlen und viele weitere Unternehmensinformationen – alles über eine einzige, einfach zu verwendende API.

Für Projekte in den Bereichen Datenanalyse, Business Intelligence oder Workflow-Automatisierung ist dieses Paket ein echter Mehrwert. Du kannst bequem Hunderte von Unternehmen in Sekunden abfragen und die Ergebnisse direkt in deinen Anwendungen nutzen. Das erleichtert zum Beispiel die Erstellung von Berichten, das Monitoring von Marktteilnehmern oder die Durchführung von Hintergrundrecherchen erheblich. Durch die Abstraktion der komplizierten offiziellen Schnittstellen hin zu einfachen Methoden-Aufrufen kannst du dich auf die Umsetzung deiner Geschäftslogik konzentrieren, während das SDK die Detailarbeit im Hintergrund erledigt.

Lizenz und Ausblick

Das Node.js SDK steht unter der MIT-Lizenz, was dir eine möglichst flexible Nutzung in eigenen Projekten erlaubt. Als Open-Source-Projekt lebt es von der Community – schau dir gern den Quellcode auf GitHub an und zögere nicht, Issues zu erstellen oder mit Pull Requests zur Weiterentwicklung beizutragen. Wir sind gespannt auf dein Feedback und freuen uns über jede Art von Mitwirkung!

Du hast Fragen oder brauchst Hilfe beim Einstieg? Wirf einen Blick in die README und Dokumentation auf GitHub oder schreibe uns direkt. Gemeinsam mit der Entwickler-Community möchten wir das Paket kontinuierlich verbessern und noch besser auf eure Bedürfnisse zuschneiden.

Viel Erfolg beim Ausprobieren wünscht dir das handelsregister.ai-Team!