Node SDK

API-ul din JavaScript și TypeScript.

Node SDK oferă un client pentru JavaScript și TypeScript, cu definiții de tipuri pentru cereri și răspunsuri. Reîncearcă singur erorile temporare și transformă răspunsurile de eroare în clase de eroare dedicate.

Instalare

Instalează pachetul handelsregister cu npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=CHEIA_TA_API

Ce
Ce	Valoare
Pachet	`handelsregister`
Versiunea actuală	0.7.0
Node.js	22.13 sau mai nou
TypeScript	Definiții de tipuri incluse
Licență	AGPL-3.0
Cod sursă	github.com/Handelsregister-AI/handelsregister-js

SDK-ul citește cheia ta API din variabila de mediu HANDELSREGISTER_API_KEY. O poți transmite și când creezi clientul. Un bearer token merge prin HANDELSREGISTER_BEARER_TOKEN sau bearerToken. Cheia se trimite întotdeauna în header, niciodată în URL.

Prima cerere

fetchOrganization preia un profil de companie și returnează răspunsul API ca obiect. Parametrul q acceptă un nume, instanța de registru cu numărul de registru sau un entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

Răspunsul este același ca la fetch-organization. Iată un 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 din răspunsul nostru exemplu pentru Hetzner Online GmbH, Ansbach HRB 6089, doar date de bază

Mai multe date ceri cu features, Modul AI cu aiSearch: true și Timp real cu realtimeMode: true. Toate funcțiile sunt listate la fetch-organization.

JavaScript

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

Timp de o oră, clientul răspunde la cereri identice din cache, fără credite noi. Cererile cu Timp real merg întotdeauna la API. Setează cacheEnabled: false ca să dezactivezi cache-ul.

Tratarea erorilor

Fiecare răspuns de eroare al API-ului devine o eroare cu propria clasă. Toate moștenesc din HandelsregisterError și poartă statusCode, răspunsul în response și costurile în meta.

Excepție
Excepție	Status	Semnificație
AuthenticationError	401	Cheie API lipsă sau invalidă.
InsufficientCreditsError	402	Soldul tău nu ajunge pentru această cerere.
SubscriptionRequiredError	403	Cererea are nevoie de un plan superior. `requiredPlans` numește planurile potrivite.
NotFoundError	404	Nu s-a găsit nicio companie sau persoană potrivită.
RequestTimeoutError	408	Registrul nu a răspuns la timp. Nu s-a taxat nimic.
RequestValidationError	400, 422	Un parametru are o valoare invalidă.
RateLimitError	429	Prea multe cereri pe minut.
ServerError	5xx	Sursa de date este momentan indisponibilă sau supraîncărcată. Reîncearcă mai târziu.

JavaScript

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

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

try {
  const companie = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Nu s-a găsit nicio companie potrivită');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Credite insuficiente:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Registrul nu răspunde momentan, încearcă din nou mai târziu');
  } else if (error instanceof HandelsregisterError) {
    console.log('Eroare:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

La erori de rețea, statusul 429 și erori de server, SDK-ul reîncearcă singur, cu până la trei încercări în total. Dacă API-ul trimite un timp de așteptare în Retry-After, îl respectă.

Implicit, clientul așteaptă 90 secunde un răspuns. Pentru Timp real, profiluri de persoană și documente recomandăm cel puțin 120 secunde, adică timeout: 120000.

Linie de comandă

Pachetul vine cu programul handelsregister. Preia profiluri de companie, profiluri de persoană și documente, caută companii și îmbogățește fișiere.

Terminal

# Profil companie fără Modul AI, doar cu Indicatori financiari
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Salvează lista asociaților ca PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Fără alte opțiuni, handelsregister fetch activează Modul AI. O cerere costă atunci 25 credite în loc de 5, chiar și fără funcții. Cu --no-ai-search faci cererea fără Modul AI.

handelsregister document caută mai întâi compania printr-un profil de companie fără Modul AI. Astfel, la cele 15 credite ale documentului se adaugă 5 credite.

Referință

Referința completă cu toate metodele se află în README-ul repository-ului. SDK-ul acoperă întregul API:

Profiluri de companie cu toate funcțiile, și ca clasă Company
Profiluri de persoană, și ca clasă Person
Căutare & Export cu filtre, sortare și paginare automată
Documente ca fișiere
Signals, Monitoring și endpointuri webhook, cu verificarea semnăturii webhook
Cont, sold, consum și chei API
Îmbogățirea fișierelor CSV, JSON și Excel întregi

SDK-ul este licențiat sub AGPL-3.0. Codul sursă îl găsești pe GitHub, iar pachetul pe npm.

fetch-organization Toți parametrii, funcțiile și câmpurile profilului de companie. Python SDK Același API din Python.