Node SDK

API z JavaScriptu i TypeScriptu.

Node SDK udostępnia klienta dla JavaScriptu i TypeScriptu, z definicjami typów dla zapytań i odpowiedzi. Sam ponawia przejściowe błędy i zamienia odpowiedzi z błędem na dedykowane klasy błędów.

Instalacja

Zainstaluj pakiet handelsregister przez npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=TWOJ_KLUCZ_API

Co
Co	Wartość
Pakiet	`handelsregister`
Aktualna wersja	0.7.0
Node.js	22.13 lub nowszy
TypeScript	Definicje typów w zestawie
Licencja	AGPL-3.0
Kod źródłowy	github.com/Handelsregister-AI/handelsregister-js

SDK czyta klucz API ze zmiennej środowiskowej HANDELSREGISTER_API_KEY. Możesz go też przekazać przy tworzeniu klienta. Bearer token przekazujesz przez HANDELSREGISTER_BEARER_TOKEN lub bearerToken. Klucz jest zawsze wysyłany w nagłówku, nigdy w URL.

Pierwsze zapytanie

fetchOrganization pobiera profil firmy i zwraca odpowiedź API jako obiekt. Parametr q przyjmuje nazwę, sąd rejestrowy z numerem rejestru albo 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);

Odpowiedź jest taka sama jak w fetch-organization. Oto 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 naszej przykładowej odpowiedzi dla Hetzner Online GmbH, Ansbach HRB 6089, tylko dane podstawowe

Więcej danych zamawiasz przez features, tryb AI przez aiSearch: true, a tryb czasu rzeczywistego przez realtimeMode: true. Wszystkie features znajdziesz w fetch-organization.

JavaScript

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

Przez godzinę klient odpowiada na identyczne zapytania z cache, bez nowych kredytów. Zapytania w trybie czasu rzeczywistego zawsze idą do API. Ustaw cacheEnabled: false, aby wyłączyć cache.

Obsługa błędów

Każda odpowiedź API z błędem staje się błędem z własną klasą. Wszystkie dziedziczą po HandelsregisterError i mają statusCode, odpowiedź w response i koszty w meta.

Wyjątek
Wyjątek	Status	Znaczenie
AuthenticationError	401	Brak klucza API lub nieprawidłowy klucz.
InsufficientCreditsError	402	Twoje saldo nie wystarcza na to zapytanie.
SubscriptionRequiredError	403	Zapytanie wymaga wyższego planu. `requiredPlans` wymienia pasujące plany.
NotFoundError	404	Nie znaleziono pasującej firmy ani osoby.
RequestTimeoutError	408	Rejestr nie odpowiedział na czas. Nic nie naliczono.
RequestValidationError	400, 422	Parametr ma nieprawidłową wartość.
RateLimitError	429	Za dużo zapytań na minutę.
ServerError	5xx	Źródło danych jest w tej chwili niedostępne lub przeciążone. Spróbuj ponownie później.

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('Nie znaleziono pasującej firmy');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Za mało kredytów:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Rejestr w tej chwili nie odpowiada, spróbuj ponownie później');
  } else if (error instanceof HandelsregisterError) {
    console.log('Błąd:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Przy błędach sieci, statusie 429 i błędach serwera SDK sam ponawia zapytanie, łącznie do trzech prób. Jeśli API przyśle czas oczekiwania w Retry-After, SDK go przestrzega.

Domyślnie klient czeka na odpowiedź 90 sekund. Dla trybu czasu rzeczywistego, profili osób i dokumentów zalecamy co najmniej 120 sekund, czyli timeout: 120000.

Wiersz poleceń

Pakiet zawiera program handelsregister. Pobiera profile firm, profile osób i dokumenty, wyszukuje firmy i wzbogaca pliki.

Terminal

# Profil firmy bez trybu AI, tylko z KPI finansowymi
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Zapisz listę wspólników (Gesellschafterliste) jako PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Bez dalszych opcji handelsregister fetch włącza tryb AI. Zapytanie kosztuje wtedy 25 kredytów zamiast 5, nawet bez features. Z --no-ai-search pytasz bez trybu AI.

handelsregister document najpierw wyszukuje firmę przez profil firmy bez trybu AI. Do 15 kredytów za dokument dochodzi więc 5 kredytów.

Dokumentacja

Pełna dokumentacja ze wszystkimi metodami jest w README repozytorium. SDK obejmuje całe API:

Profile firm ze wszystkimi features, także jako klasa Company
Profile osób, także jako klasa Person
Wyszukiwanie i eksport z filtrami, sortowaniem i automatyczną paginacją
Dokumenty jako pliki
Signals, Monitoring i endpointy webhooków, z weryfikacją podpisu webhooków
Konto, saldo, użycie i klucze API
Wzbogacanie całych plików CSV, JSON i Excel

SDK jest na licencji AGPL-3.0. Kod źródłowy znajdziesz na GitHubie, a pakiet na npm.

fetch-organization Wszystkie parametry, features i pola profilu firmy. Python SDK To samo API z Pythona.