Node SDK

De API vanuit JavaScript en TypeScript.

De Node SDK biedt een client voor JavaScript en TypeScript, met typedefinities voor aanvragen en antwoorden. Hij probeert tijdelijke fouten zelf opnieuw en zet foutantwoorden om in eigen foutklassen.

Installeren

Installeer het pakket handelsregister met npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=JOUW_API_SLEUTEL

Wat
Wat	Waarde
Pakket	`handelsregister`
Huidige versie	0.7.0
Node.js	22.13 of nieuwer
TypeScript	Typedefinities inbegrepen
Licentie	AGPL-3.0
Broncode	github.com/Handelsregister-AI/handelsregister-js

De SDK leest je API-sleutel uit de omgevingsvariabele HANDELSREGISTER_API_KEY. Je kunt hem ook meegeven bij het aanmaken van de client. Een bearer-token gaat via HANDELSREGISTER_BEARER_TOKEN of bearerToken. De sleutel gaat altijd in de header mee, nooit in de URL.

Eerste aanvraag

fetchOrganization haalt een bedrijfsprofiel op en geeft het API-antwoord terug als object. De parameter q accepteert een naam, registerrechtbank met registernummer, of een entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

Het antwoord is hetzelfde als bij fetch-organization. Hier een fragment:

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 · Fragment uit ons voorbeeldantwoord voor Hetzner Online GmbH, Ansbach HRB 6089, alleen basisgegevens

Meer gegevens vraag je op met features, de AI-modus met aiSearch: true en Realtime met realtimeMode: true. Alle features staan onder fetch-organization.

JavaScript

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

Een uur lang beantwoordt de client identieke aanvragen uit zijn cache, zonder nieuwe credits. Aanvragen met Realtime gaan altijd naar de API. Zet cacheEnabled: false om de cache uit te zetten.

Fouten afhandelen

Elk foutantwoord van de API wordt een fout met een eigen klasse. Ze erven allemaal van HandelsregisterError en hebben statusCode, het antwoord in response en de kosten in meta.

Exception
Exception	Status	Betekenis
AuthenticationError	401	API-sleutel ontbreekt of is ongeldig.
InsufficientCreditsError	402	Je saldo is niet genoeg voor deze aanvraag.
SubscriptionRequiredError	403	De aanvraag vraagt een hoger plan. `requiredPlans` noemt de plannen die passen.
NotFoundError	404	Geen passend bedrijf of passende persoon gevonden.
RequestTimeoutError	408	Het register heeft niet op tijd geantwoord. Er is niets berekend.
RequestValidationError	400, 422	Een parameter heeft een ongeldige waarde.
RateLimitError	429	Te veel aanvragen per minuut.
ServerError	5xx	De gegevensbron is op dit moment niet beschikbaar of overbelast. Probeer het later opnieuw.

JavaScript

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

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

try {
  const bedrijf = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Geen passend bedrijf gevonden');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Niet genoeg credits:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Het register antwoordt nu niet, probeer het later opnieuw');
  } else if (error instanceof HandelsregisterError) {
    console.log('Fout:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Bij netwerkfouten, status 429 en serverfouten probeert de SDK het zelf opnieuw, met in totaal maximaal drie pogingen. Stuurt de API een wachttijd in Retry-After, dan houdt hij zich daaraan.

Standaard wacht de client 90 seconden op een antwoord. Voor Realtime, persoonsprofielen en documenten raden we minstens 120 seconden aan, dus timeout: 120000.

Opdrachtregel

Het pakket bevat het programma handelsregister. Het haalt bedrijfsprofielen, persoonsprofielen en documenten op, zoekt bedrijven en verrijkt bestanden.

Terminal

# Bedrijfsprofiel zonder AI-modus, alleen met Financiële KPI’s
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

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

Zonder verdere opties zet handelsregister fetch de AI-modus aan. Een aanvraag kost dan 25 credits in plaats van 5, ook zonder features. Met --no-ai-search vraag je op zonder AI-modus.

handelsregister document zoekt het bedrijf eerst op via een bedrijfsprofiel zonder AI-modus. Bij de 15 credits van het document komen dus 5 credits.

Referentie

De volledige referentie met alle methoden staat in de README van de repository. De SDK dekt de hele API:

Bedrijfsprofielen met alle features, ook als Company-klasse
Persoonsprofielen, ook als Person-klasse
Zoeken & exporteren met filters, sortering en automatisch bladeren
Documenten als bestand
Signals, Monitoring en webhook-endpoints, met verificatie van de webhookhandtekening
Account, saldo, gebruik en API-sleutels
Verrijking van hele CSV-, JSON- en Excel-bestanden

De SDK valt onder de licentie AGPL-3.0. De broncode vind je op GitHub, het pakket op npm.

fetch-organization Alle parameters, features en velden van het bedrijfsprofiel. Python SDK Dezelfde API vanuit Python.