Node SDK

API-et fra JavaScript og TypeScript.

Node SDK-en gir en klient for JavaScript og TypeScript, med typedefinisjoner for forespørsler og svar. Den prøver midlertidige feil på nytt selv og gjør feilsvar om til egne feilklasser.

Installer

Installer pakken handelsregister med npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=YOUR_API_KEY

Hva
Hva	Verdi
Pakke	`handelsregister`
Aktuell versjon	0.7.0
Node.js	22.13 eller nyere
TypeScript	Typedefinisjoner inkludert
Lisens	AGPL-3.0
Kildekode	github.com/Handelsregister-AI/handelsregister-js

SDK-en leser API-nøkkelen din fra miljøvariabelen HANDELSREGISTER_API_KEY. Du kan også sende den når du oppretter klienten. Et bearer-token går via HANDELSREGISTER_BEARER_TOKEN eller bearerToken. Nøkkelen sendes alltid i headeren, aldri i URL-en.

Første forespørsel

fetchOrganization henter en firmaprofil og returnerer API-svaret som objekt. Parameteren q tar imot et navn, registerdomstol med registernummer eller en 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);

Svaret er det samme som for fetch-organization. Her er et utdrag:

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 · Utdrag av eksempelsvaret vårt for Hetzner Online GmbH, Ansbach HRB 6089, bare grunndata

Flere data ber du om med features, AI-modus med aiSearch: true og Sanntid med realtimeMode: true. Alle funksjoner står under fetch-organization.

JavaScript

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

I én time svarer klienten på identiske forespørsler fra cachen sin, uten nye kreditter. Forespørsler med Sanntid går alltid til API-et. Sett cacheEnabled: false for å slå av cachen.

Håndter feil

Hvert feilsvar fra API-et blir en feil med sin egen klasse. Alle arver fra HandelsregisterError og har statusCode, svaret i response og kostnadene i meta.

Exception
Exception	Status	Betydning
AuthenticationError	401	Manglende eller ugyldig API-nøkkel.
InsufficientCreditsError	402	Saldoen din holder ikke for denne forespørselen.
SubscriptionRequiredError	403	Forespørselen krever et høyere abonnement. `requiredPlans` nevner abonnementene som passer.
NotFoundError	404	Fant ikke noe passende firma eller person.
RequestTimeoutError	408	Registeret svarte ikke i tide. Ingenting ble belastet.
RequestValidationError	400, 422	En parameter har en ugyldig verdi.
RateLimitError	429	For mange forespørsler per minutt.
ServerError	5xx	Datakilden er utilgjengelig eller overbelastet akkurat nå. Prøv igjen senere.

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('Fant ikke noe passende firma');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Ikke nok kreditter:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Registeret svarer ikke akkurat nå, prøv igjen senere');
  } else if (error instanceof HandelsregisterError) {
    console.log('Feil:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Ved nettverksfeil, status 429 og serverfeil prøver SDK-en på nytt selv, med opptil tre forsøk totalt. Sender API-et en ventetid i Retry-After, respekterer den den.

Som standard venter klienten 90 sekunder på et svar. For Sanntid, personprofiler og dokumenter anbefaler vi minst 120 sekunder, altså timeout: 120000.

Kommandolinje

Pakken inneholder programmet handelsregister. Det henter firmaprofiler, personprofiler og dokumenter, søker etter firmaer og beriker filer.

Terminal

# Firmaprofil uten AI-modus, bare med økonomiske nøkkeltall
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Lagre eierlisten som PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Uten flere valg slår handelsregister fetch på AI-modus. En forespørsel koster da 25 kreditter i stedet for 5, også uten funksjoner. Med --no-ai-search spør du uten AI-modus.

handelsregister document slår først opp firmaet via en firmaprofil uten AI-modus. Derfor kommer 5 kreditter i tillegg til de 15 kredittene for dokumentet.

Referanse

Den fullstendige referansen med alle metoder står i README-filen i repositoryet. SDK-en dekker hele API-et:

Firmaprofiler med alle funksjoner, også som Company-klasse
Personprofiler, også som Person-klasse
Søk & eksport med filtre, sortering og automatisk paginering
Dokumenter som filer
Signals, Monitoring og webhook-endepunkter, med verifisering av webhook-signaturer
Konto, saldo, forbruk og API-nøkler
Berikelse av hele CSV-, JSON- og Excel-filer

SDK-en er lisensiert under AGPL-3.0. Kildekoden finner du på GitHub og pakken på npm.

fetch-organization Alle parametere, funksjoner og felt for firmaprofilen. Python SDK Det samme API-et fra Python.