Node SDK

Το API από JavaScript και TypeScript.

Το Node SDK παρέχει έναν client για JavaScript και TypeScript, με ορισμούς τύπων για αιτήματα και απαντήσεις. Επαναλαμβάνει μόνο του τα προσωρινά σφάλματα και μετατρέπει τις απαντήσεις σφάλματος σε ειδικές κλάσεις σφαλμάτων.

Εγκατάσταση

Εγκατάστησε το πακέτο handelsregister με npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=YOUR_API_KEY

Τι
Τι	Τιμή
Πακέτο	`handelsregister`
Τρέχουσα έκδοση	0.7.0
Node.js	22.13 ή νεότερη
TypeScript	Περιλαμβάνονται ορισμοί τύπων
Άδεια	AGPL-3.0
Πηγαίος κώδικας	github.com/Handelsregister-AI/handelsregister-js

Το SDK διαβάζει το κλειδί API σου από τη μεταβλητή περιβάλλοντος HANDELSREGISTER_API_KEY. Μπορείς επίσης να το περάσεις όταν δημιουργείς τον client. Ένα bearer token περνά μέσω του HANDELSREGISTER_BEARER_TOKEN ή του bearerToken. Το κλειδί στέλνεται πάντα στο header, ποτέ στο URL.

Πρώτο αίτημα

Το fetchOrganization ανακτά ένα προφίλ εταιρείας και επιστρέφει την απάντηση του API ως αντικείμενο. Η παράμετρος q δέχεται επωνυμία, δικαστήριο μητρώου με αριθμό μητρώου ή ένα entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

Η απάντηση είναι ίδια με του fetch-organization. Ένα απόσπασμα:

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 · Απόσπασμα από το παράδειγμα απάντησής μας για τη Hetzner Online GmbH, Ansbach HRB 6089, μόνο βασικά στοιχεία

Περισσότερα δεδομένα ζητάς με το features, τη Λειτουργία AI με aiSearch: true και τον Πραγματικό χρόνο με realtimeMode: true. Όλα τα features παρατίθενται στο fetch-organization.

JavaScript

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

Για μία ώρα, ο client απαντά σε πανομοιότυπα αιτήματα από την cache του, χωρίς νέες πιστώσεις. Τα αιτήματα με Πραγματικό χρόνο πηγαίνουν πάντα στο API. Όρισε cacheEnabled: false για να απενεργοποιήσεις την cache.

Χειρισμός σφαλμάτων

Κάθε απάντηση σφάλματος του API γίνεται σφάλμα με δική του κλάση. Όλες κληρονομούν από το HandelsregisterError και φέρουν statusCode, την απάντηση στο response και το κόστος στο meta.

Εξαίρεση
Εξαίρεση	Status	Σημασία
AuthenticationError	401	Το κλειδί API λείπει ή δεν είναι έγκυρο.
InsufficientCreditsError	402	Το υπόλοιπό σου δεν επαρκεί για αυτό το αίτημα.
SubscriptionRequiredError	403	Το αίτημα χρειάζεται υψηλότερο πλάνο. Το `requiredPlans` κατονομάζει τα κατάλληλα πλάνα.
NotFoundError	404	Δεν βρέθηκε εταιρεία ή πρόσωπο που να ταιριάζει.
RequestTimeoutError	408	Το μητρώο δεν απάντησε εγκαίρως. Δεν χρεώθηκε τίποτα.
RequestValidationError	400, 422	Μια παράμετρος έχει μη έγκυρη τιμή.
RateLimitError	429	Πάρα πολλά αιτήματα ανά λεπτό.
ServerError	5xx	Η πηγή δεδομένων δεν είναι διαθέσιμη ή είναι υπερφορτωμένη αυτή τη στιγμή. Δοκίμασε ξανά αργότερα.

JavaScript

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

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

try {
  const company = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Δεν βρέθηκε εταιρεία που να ταιριάζει');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Δεν επαρκούν οι πιστώσεις:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Το μητρώο δεν απαντά αυτή τη στιγμή, δοκίμασε ξανά αργότερα');
  } else if (error instanceof HandelsregisterError) {
    console.log('Σφάλμα:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Σε σφάλματα δικτύου, status 429 και σφάλματα διακομιστή, το SDK επαναλαμβάνει μόνο του, με έως τρεις προσπάθειες συνολικά. Αν το API στείλει χρόνο αναμονής στο Retry-After, τον τηρεί.

Από προεπιλογή, ο client περιμένει 90 δευτερόλεπτα για απάντηση. Για Πραγματικό χρόνο, προφίλ προσώπων και έγγραφα, προτείνουμε τουλάχιστον 120 δευτερόλεπτα, δηλαδή timeout: 120000.

Γραμμή εντολών

Το πακέτο περιλαμβάνει το πρόγραμμα handelsregister. Ανακτά προφίλ εταιρειών, προφίλ προσώπων και έγγραφα, αναζητά εταιρείες και εμπλουτίζει αρχεία.

Terminal

# Προφίλ εταιρείας χωρίς Λειτουργία AI, μόνο με Οικονομικούς δείκτες
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Αποθήκευση της λίστας εταίρων ως PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Χωρίς άλλες επιλογές, το handelsregister fetch ενεργοποιεί τη Λειτουργία AI. Ένα αίτημα κοστίζει τότε 25 πιστώσεις αντί για 5, ακόμη και χωρίς features. Με --no-ai-search, κάνεις αίτημα χωρίς Λειτουργία AI.

Το handelsregister document αναζητά πρώτα την εταιρεία μέσω ενός προφίλ εταιρείας χωρίς Λειτουργία AI. Έτσι στις 15 πιστώσεις του εγγράφου προστίθενται 5 πιστώσεις.

Αναφορά

Η πλήρης αναφορά με όλες τις μεθόδους βρίσκεται στο README του repository. Το SDK καλύπτει ολόκληρο το API:

Προφίλ εταιρειών με όλα τα features, και ως κλάση Company
Προφίλ προσώπων, και ως κλάση Person
Αναζήτηση & Εξαγωγή με φίλτρα, ταξινόμηση και αυτόματη σελιδοποίηση
Έγγραφα ως αρχεία
Signals, Monitoring και endpoints webhook, με επαλήθευση υπογραφής webhook
Λογαριασμός, υπόλοιπο, χρήση και κλειδιά API
Εμπλουτισμός ολόκληρων αρχείων CSV, JSON και Excel

Το SDK διατίθεται με άδεια AGPL-3.0. Τον πηγαίο κώδικα τον βρίσκεις στο GitHub και το πακέτο στο npm.

fetch-organization Όλες οι παράμετροι, τα features και τα πεδία του προφίλ εταιρείας. Python SDK Το ίδιο API από την Python.