Node SDK

API:et från JavaScript och TypeScript.

Node SDK:n tillhandahåller en klient för JavaScript och TypeScript, med typdefinitioner för förfrågningar och svar. Den gör själv om tillfälliga fel och omvandlar felsvar till egna felklasser.

Installera

Installera paketet handelsregister med npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=DIN_API_NYCKEL

Vad
Vad	Värde
Paket	`handelsregister`
Aktuell version	0.7.0
Node.js	22.13 eller nyare
TypeScript	Typdefinitioner ingår
Licens	AGPL-3.0
Källkod	github.com/Handelsregister-AI/handelsregister-js

SDK:n läser din API-nyckel från miljövariabeln HANDELSREGISTER_API_KEY. Du kan också skicka den när du skapar klienten. En bearer-token går via HANDELSREGISTER_BEARER_TOKEN eller bearerToken. Nyckeln skickas alltid i headern, aldrig i URL:en.

Första förfrågan

fetchOrganization hämtar en företagsprofil och returnerar API-svaret som objekt. Parametern q tar emot ett namn, registerdomstol med registernummer eller ett entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

Svaret är detsamma som för fetch-organization. Här är ett 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 ur vårt exempelsvar för Hetzner Online GmbH, Ansbach HRB 6089, bara grunddata

Fler data begär du med features, AI-läget med aiSearch: true och Realtid med realtimeMode: true. Alla funktioner finns under fetch-organization.

JavaScript

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

Under en timme besvarar klienten identiska förfrågningar ur sin cache, utan nya krediter. Förfrågningar med Realtid går alltid till API:et. Sätt cacheEnabled: false för att stänga av cachen.

Hantera fel

Varje felsvar från API:et blir ett fel med en egen klass. Alla ärver från HandelsregisterError och har statusCode, svaret i response och kostnaderna i meta.

Undantag
Undantag	Status	Betydelse
AuthenticationError	401	API-nyckel saknas eller är ogiltig.
InsufficientCreditsError	402	Ditt saldo räcker inte för denna förfrågan.
SubscriptionRequiredError	403	Förfrågan kräver en högre plan. `requiredPlans` nämner de planer som passar.
NotFoundError	404	Inget matchande företag eller ingen matchande person hittades.
RequestTimeoutError	408	Registret svarade inte i tid. Ingenting debiterades.
RequestValidationError	400, 422	En parameter har ett ogiltigt värde.
RateLimitError	429	För många förfrågningar per minut.
ServerError	5xx	Datakällan är inte tillgänglig eller överbelastad just nu. Försök igen senare.

JavaScript

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

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

try {
  const foretag = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Inget matchande företag hittades');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Krediterna räcker inte:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Registret svarar inte just nu, försök igen senare');
  } else if (error instanceof HandelsregisterError) {
    console.log('Fel:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Vid nätverksfel, status 429 och serverfel gör SDK:n själv nya försök, med upp till tre försök totalt. Om API:et skickar en väntetid i Retry-After respekterar den den.

Som standard väntar klienten 90 sekunder på ett svar. För Realtid, personprofiler och dokument rekommenderar vi minst 120 sekunder, alltså timeout: 120000.

Kommandorad

Paketet innehåller programmet handelsregister. Det hämtar företagsprofiler, personprofiler och dokument, söker företag och berikar filer.

Terminal

# Företagsprofil utan AI-läge, bara med finansiella nyckeltal
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Spara Gesellschafterliste (delägarförteckningen) som PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Utan ytterligare alternativ slår handelsregister fetch på AI-läget. En förfrågan kostar då 25 krediter i stället för 5, även utan funktioner. Med --no-ai-search frågar du utan AI-läge.

handelsregister document slår först upp företaget via en företagsprofil utan AI-läge. Därför tillkommer 5 krediter till dokumentets 15 krediter.

Referens

Den fullständiga referensen med alla metoder finns i repositoryts README. SDK:n täcker hela API:et:

Företagsprofiler med alla funktioner, även som Company-klass
Personprofiler, även som Person-klass
Sök & export med filter, sortering och automatisk paginering
Dokument som filer
Signals, Bevakning och webhook-endpoints, med verifiering av webhook-signaturer
Konto, saldo, förbrukning och API-nycklar
Berikning av hela CSV-, JSON- och Excel-filer

SDK:n är licensierad under AGPL-3.0. Källkoden hittar du på GitHub och paketet på npm.

fetch-organization Alla parametrar, funktioner och fält för företagsprofilen. Python SDK Samma API från Python.