Node SDK

API JavaScriptistä ja TypeScriptistä.

Node SDK tarjoaa asiakasohjelman JavaScriptille ja TypeScriptille, tyyppimäärittelyineen pyynnöille ja vastauksille. Se yrittää tilapäisiä virheitä uudelleen itse ja muuttaa virhevastaukset omiksi virheluokikseen.

Asennus

Asenna paketti handelsregister npm:llä.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=SINUN_API_AVAIMESI

Mitä
Mitä	Arvo
Paketti	`handelsregister`
Nykyinen versio	0.7.0
Node.js	22.13 tai uudempi
TypeScript	Tyyppimäärittelyt mukana
Lisenssi	AGPL-3.0
Lähdekoodi	github.com/Handelsregister-AI/handelsregister-js

SDK lukee API-avaimesi ympäristömuuttujasta HANDELSREGISTER_API_KEY. Voit myös antaa sen luodessasi asiakasohjelman. Bearer-token kulkee muuttujan HANDELSREGISTER_BEARER_TOKEN tai parametrin bearerToken kautta. Avain lähetetään aina headerissa, ei koskaan URL-osoitteessa.

Ensimmäinen pyyntö

fetchOrganization hakee yritysprofiilin ja palauttaa API-vastauksen objektina. Parametri q ottaa nimen, rekisterituomioistuimen ja rekisterinumeron tai entity_id:n.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

Vastaus on sama kuin fetch-organizationilla. Tässä ote:

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 · Ote esimerkkivastauksestamme yrityksestä Hetzner Online GmbH, Ansbach HRB 6089, vain perustiedot

Lisää dataa pyydät parametrilla features, AI-tilan asetuksella aiSearch: true ja Reaaliajan asetuksella realtimeMode: true. Kaikki ominaisuudet on lueteltu kohdassa fetch-organization.

JavaScript

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

Tunnin ajan asiakasohjelma vastaa identtisiin pyyntöihin välimuististaan ilman uusia krediittejä. Reaaliaikaa käyttävät pyynnöt menevät aina API:in. Aseta cacheEnabled: false poistaaksesi välimuistin käytöstä.

Virheiden käsittely

Jokaisesta API:n virhevastauksesta tulee virhe omalla luokallaan. Kaikki periytyvät luokasta HandelsregisterError, ja niissä on statusCode, vastaus kentässä response ja kustannukset kentässä meta.

Poikkeus
Poikkeus	Tila	Merkitys
AuthenticationError	401	API-avain puuttuu tai on virheellinen.
InsufficientCreditsError	402	Saldosi ei riitä tähän pyyntöön.
SubscriptionRequiredError	403	Pyyntö vaatii korkeamman tilauksen. `requiredPlans` nimeää sopivat tilaukset.
NotFoundError	404	Sopivaa yritystä tai henkilöä ei löytynyt.
RequestTimeoutError	408	Rekisteri ei vastannut ajoissa. Mitään ei veloitettu.
RequestValidationError	400, 422	Parametrilla on virheellinen arvo.
RateLimitError	429	Liian monta pyyntöä minuutissa.
ServerError	5xx	Tietolähde ei ole juuri nyt käytettävissä tai on ylikuormittunut. Yritä myöhemmin uudelleen.

JavaScript

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

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

try {
  const yritys = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Sopivaa yritystä ei löytynyt');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Krediitit eivät riitä:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Rekisteri ei vastaa juuri nyt, yritä myöhemmin uudelleen');
  } else if (error instanceof HandelsregisterError) {
    console.log('Virhe:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Verkkovirheissä, tilassa 429 ja palvelinvirheissä SDK yrittää uudelleen itse, yhteensä enintään kolme kertaa. Jos API lähettää odotusajan headerissa Retry-After, SDK noudattaa sitä.

Oletuksena asiakasohjelma odottaa vastausta 90 sekuntia. Reaaliajalle, henkilöprofiileille ja asiakirjoille suosittelemme vähintään 120 sekuntia, eli timeout: 120000.

Komentorivi

Paketin mukana tulee ohjelma handelsregister. Se hakee yritysprofiileja, henkilöprofiileja ja asiakirjoja, hakee yrityksiä ja rikastaa tiedostoja.

Terminal

# Yritysprofiili ilman AI-tilaa, vain taloudellisilla tunnusluvuilla
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Tallenna osakasluettelo PDF-tiedostona
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Ilman lisävalintoja handelsregister fetch ottaa käyttöön AI-tilan. Pyyntö maksaa silloin 25 krediittiä 5 sijaan, myös ilman ominaisuuksia. Valinnalla --no-ai-search teet pyynnön ilman AI-tilaa.

handelsregister document etsii yrityksen ensin yritysprofiililla ilman AI-tilaa. Asiakirjan 15 krediittiin tulee siis lisäksi 5 krediittiä.

Referenssi

Täydellinen referenssi kaikkine metodeineen on repositorion README-tiedostossa. SDK kattaa koko API:n:

Yritysprofiilit kaikkine ominaisuuksineen, myös Company-luokkana
Henkilöprofiilit, myös Person-luokkana
Haku & vienti suodattimilla, lajittelulla ja automaattisella sivutuksella
Asiakirjat tiedostoina
Signals, Monitoring ja webhook-päätepisteet, webhook-allekirjoitusten tarkistuksella
Tili, saldo, käyttö ja API-avaimet
Kokonaisten CSV-, JSON- ja Excel-tiedostojen rikastaminen

SDK on lisensoitu AGPL-3.0-lisenssillä. Lähdekoodin löydät GitHubista ja paketin npm:stä.

fetch-organization Kaikki yritysprofiilin parametrit, ominaisuudet ja kentät. Python SDK Sama API Pythonista.