Node SDK

Az API JavaScriptből és TypeScriptből.

A Node SDK klienst ad JavaScripthez és TypeScripthez, típusdefiníciókkal a kérésekhez és válaszokhoz. Az átmeneti hibákat magától újrapróbálja, a hibaválaszokat pedig saját hibaosztályokká alakítja.

Telepítés

Telepítsd a handelsregister csomagot npm-mel.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=AZ_API_KULCSOD

Mi
Mi	Érték
Csomag	`handelsregister`
Aktuális verzió	0.7.0
Node.js	22.13 vagy újabb
TypeScript	Típusdefiníciók mellékelve
Licenc	AGPL-3.0
Forráskód	github.com/Handelsregister-AI/handelsregister-js

Az SDK az API-kulcsodat a HANDELSREGISTER_API_KEY környezeti változóból olvassa. A kliens létrehozásakor át is adhatod. Bearer tokent a HANDELSREGISTER_BEARER_TOKEN vagy a bearerToken révén adsz meg. A kulcsot mindig a headerben küldi, soha nem az URL-ben.

Első kérés

A fetchOrganization lekér egy cégprofilt, és az API válaszát objektumként adja vissza. A q paraméter nevet, cégbíróságot cégjegyzékszámmal vagy entity_id-t fogad.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

A válasz ugyanaz, mint a fetch-organization esetén. Íme egy részlet:

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 · Részlet a Hetzner Online GmbH-ra (Ansbach HRB 6089) adott példaválaszunkból, csak alapadatokkal

Több adatot a features, AI módot az aiSearch: true, valós idejű módot a realtimeMode: true beállítással kérsz. Az összes funkció a fetch-organization alatt szerepel.

JavaScript

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

Egy órán át a kliens az azonos kérésekre a gyorsítótárából válaszol, új kreditek nélkül. A valós idejű kérések mindig az API-hoz mennek. A gyorsítótárat a cacheEnabled: false beállítással kapcsolod ki.

Hibakezelés

Az API minden hibaválaszából saját osztályú hiba lesz. Mindegyik a HandelsregisterError osztályból származik, és hordozza a statusCode értéket, a választ a response, a költségeket a meta mezőben.

Kivétel
Kivétel	Státusz	Jelentés
AuthenticationError	401	Hiányzó vagy érvénytelen API-kulcs.
InsufficientCreditsError	402	Az egyenleged nem elég ehhez a kéréshez.
SubscriptionRequiredError	403	A kéréshez magasabb csomag kell. A `requiredPlans` megnevezi a megfelelő csomagokat.
NotFoundError	404	Nincs megfelelő cég vagy személy.
RequestTimeoutError	408	A nyilvántartás nem válaszolt időben. Semmit nem számoltunk fel.
RequestValidationError	400, 422	Egy paraméter értéke érvénytelen.
RateLimitError	429	Túl sok kérés percenként.
ServerError	5xx	Az adatforrás most nem érhető el, vagy túlterhelt. Próbáld újra később.

JavaScript

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

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

try {
  const ceg = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Nincs megfelelő cég');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Nincs elég kredit:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('A nyilvántartás most nem válaszol, próbáld újra később');
  } else if (error instanceof HandelsregisterError) {
    console.log('Hiba:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Hálózati hibáknál, 429-es státusznál és szerverhibáknál az SDK magától újrapróbál, összesen legfeljebb három kísérlettel. Ha az API a Retry-After headerben várakozási időt küld, azt betartja.

Alapértelmezésként a kliens 90 másodpercig vár a válaszra. A valós idejű módhoz, a személyprofilokhoz és a dokumentumokhoz legalább 120 másodpercet javaslunk, azaz timeout: 120000.

Parancssor

A csomag tartalmazza a handelsregister programot. Cégprofilokat, személyprofilokat és dokumentumokat kér le, cégeket keres, és fájlokat dúsít.

Terminal

# Cégprofil AI mód nélkül, csak pénzügyi KPI-kkal
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# A tagjegyzék (Gesellschafterliste) mentése PDF-ként
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

További opciók nélkül a handelsregister fetch bekapcsolja az AI módot. Egy kérés ekkor 5 helyett 25 kreditbe kerül, funkciók nélkül is. A --no-ai-search opcióval AI mód nélkül kérsz.

A handelsregister document először egy AI mód nélküli cégprofillal keresi meg a céget. Így a dokumentum 15 kreditjéhez 5 kredit adódik.

Referencia

A teljes referencia az összes metódussal a repository README-jében található. Az SDK a teljes API-t lefedi:

Cégprofilok az összes funkcióval, Company osztályként is
Személyprofilok, Person osztályként is
Keresés és export szűrőkkel, rendezéssel és automatikus lapozással
Dokumentumok fájlként
Signals, Monitoring és webhook-végpontok, a webhook-aláírás ellenőrzésével
Fiók, egyenleg, felhasználás és API-kulcsok
Teljes CSV-, JSON- és Excel-fájlok dúsítása

Az SDK AGPL-3.0 licenc alatt áll. A forráskódot a GitHubon, a csomagot az npm-en találod.

fetch-organization A cégprofil összes paramétere, funkciója és mezője. Python SDK Ugyanaz az API Pythonból.