Node SDK

API z JavaScriptu a TypeScriptu.

Node SDK poskytuje klienta pro JavaScript a TypeScript s typovými definicemi pro požadavky a odpovědi. Dočasné chyby opakuje sám a chybové odpovědi převádí na vlastní chybové třídy.

Instalace

Nainstaluj balíček handelsregister pomocí npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=TVUJ_API_KLIC

Co
Co	Hodnota
Balíček	`handelsregister`
Aktuální verze	0.7.0
Node.js	22.13 nebo novější
TypeScript	Typové definice v balíčku
Licence	AGPL-3.0
Zdrojový kód	github.com/Handelsregister-AI/handelsregister-js

SDK čte tvůj API klíč z proměnné prostředí HANDELSREGISTER_API_KEY. Můžeš ho předat i při vytváření klienta. Bearer token se předává přes HANDELSREGISTER_BEARER_TOKEN nebo bearerToken. Klíč se posílá vždy v headeru, nikdy v URL.

První požadavek

fetchOrganization načte profil firmy a vrátí odpověď API jako objekt. Parametr q přijímá název, rejstříkový soud s rejstříkovým číslem nebo 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);

Odpověď je stejná jako u fetch-organization. Zde výňatek:

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 · Výňatek z naší ukázkové odpovědi pro Hetzner Online GmbH, Ansbach HRB 6089, jen základní údaje

Další data si vyžádáš pomocí features, AI režim pomocí aiSearch: true a režim v reálném čase pomocí realtimeMode: true. Všechny funkce najdeš v fetch-organization.

JavaScript

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

Po dobu jedné hodiny odpovídá klient na stejné požadavky ze své cache, bez nových kreditů. Požadavky v režimu v reálném čase jdou vždy na API. Cache vypneš pomocí cacheEnabled: false.

Ošetření chyb

Každá chybová odpověď API se stane chybou s vlastní třídou. Všechny dědí z HandelsregisterError a nesou statusCode, odpověď v response a náklady v meta.

Výjimka
Výjimka	Stav	Význam
AuthenticationError	401	Chybějící nebo neplatný API klíč.
InsufficientCreditsError	402	Tvůj zůstatek na tento požadavek nestačí.
SubscriptionRequiredError	403	Požadavek potřebuje vyšší tarif. `requiredPlans` jmenuje vhodné tarify.
NotFoundError	404	Nebyla nalezena odpovídající firma ani osoba.
RequestTimeoutError	408	Rejstřík neodpověděl včas. Nic se neúčtovalo.
RequestValidationError	400, 422	Parametr má neplatnou hodnotu.
RateLimitError	429	Příliš mnoho požadavků za minutu.
ServerError	5xx	Zdroj dat je teď nedostupný nebo přetížený. Zkus to později znovu.

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('Nebyla nalezena žádná odpovídající firma');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Nedostatek kreditů:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Rejstřík teď neodpovídá, zkus to později znovu');
  } else if (error instanceof HandelsregisterError) {
    console.log('Chyba:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Při chybách sítě, stavu 429 a chybách serveru SDK opakuje samo, celkem až třemi pokusy. Pokud API pošle čekací dobu v Retry-After, respektuje ji.

Ve výchozím stavu klient čeká na odpověď 90 sekund. Pro režim v reálném čase, profily osob a dokumenty doporučujeme alespoň 120 sekund, tedy timeout: 120000.

Příkazový řádek

Balíček obsahuje program handelsregister. Načítá profily firem, profily osob a dokumenty, hledá firmy a obohacuje soubory.

Terminal

# Profil firmy bez AI režimu, jen s finančními ukazateli
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Uložit seznam společníků jako PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Bez dalších voleb zapne handelsregister fetch AI režim. Požadavek pak stojí 25 kreditů místo 5, i bez funkcí. S --no-ai-search se ptáš bez AI režimu.

handelsregister document nejprve dohledá firmu přes profil firmy bez AI režimu. K 15 kreditům za dokument se proto přičte 5 kreditů.

Reference

Úplná reference se všemi metodami je v README repozitáře. SDK pokrývá celé API:

Profily firem se všemi funkcemi, také jako třída Company
Profily osob, také jako třída Person
Vyhledávání a export s filtry, řazením a automatickým stránkováním
Dokumenty jako soubory
Signals, Monitoring a webhook endpointy, s ověřením podpisu webhooků
Účet, zůstatek, využití a API klíče
Obohacování celých souborů CSV, JSON a Excel

SDK je licencováno pod AGPL-3.0. Zdrojový kód najdeš na GitHubu a balíček na npm.

fetch-organization Všechny parametry, funkce a pole profilu firmy. Python SDK Stejné API z Pythonu.