SDK Node

L’API depuis JavaScript et TypeScript.

Le SDK Node fournit un client pour JavaScript et TypeScript, avec des définitions de types pour les requêtes et les réponses. Il retente seul les erreurs temporaires et transforme les réponses d’erreur en classes d’erreur dédiées.

Installation

Installe le paquet handelsregister avec npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=TA_CLE_API

Quoi
Quoi	Valeur
Paquet	`handelsregister`
Version actuelle	0.7.0
Node.js	22.13 ou plus récent
TypeScript	Définitions de types incluses
Licence	AGPL-3.0
Code source	github.com/Handelsregister-AI/handelsregister-js

Le SDK lit ta clé API dans la variable d’environnement HANDELSREGISTER_API_KEY. Tu peux aussi la passer à la création du client. Un bearer token passe par HANDELSREGISTER_BEARER_TOKEN ou bearerToken. La clé est toujours envoyée dans le header, jamais dans l’URL.

Première requête

fetchOrganization récupère un profil d’entreprise et renvoie la réponse de l’API sous forme d’objet. Le paramètre q accepte un nom, un tribunal du registre avec numéro de registre, ou un entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

La réponse est la même que pour fetch-organization. En voici un extrait :

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 · Extrait de notre exemple de réponse pour Hetzner Online GmbH, Ansbach HRB 6089, données de base uniquement

Tu demandes davantage de données avec features, le mode IA avec aiSearch: true et le mode temps réel avec realtimeMode: true. Toutes les fonctionnalités figurent sous fetch-organization.

JavaScript

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

Pendant une heure, le client répond aux requêtes identiques depuis son cache, sans nouveaux crédits. Les requêtes avec le mode temps réel vont toujours à l’API. Définis cacheEnabled: false pour désactiver le cache.

Gérer les erreurs

Chaque réponse d’erreur de l’API devient une erreur avec sa propre classe. Toutes héritent de HandelsregisterError et portent statusCode, la réponse dans response et les coûts dans meta.

Exception
Exception	Statut	Signification
AuthenticationError	401	Clé API manquante ou invalide.
InsufficientCreditsError	402	Ton solde ne suffit pas pour cette requête.
SubscriptionRequiredError	403	La requête nécessite un plan supérieur. `requiredPlans` nomme les plans qui conviennent.
NotFoundError	404	Aucune entreprise ou personne correspondante trouvée.
RequestTimeoutError	408	Le registre n’a pas répondu à temps. Rien n’a été facturé.
RequestValidationError	400, 422	Un paramètre a une valeur invalide.
RateLimitError	429	Trop de requêtes par minute.
ServerError	5xx	La source de données est indisponible ou surchargée pour le moment. Réessaie plus tard.

JavaScript

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

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

try {
  const entreprise = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Aucune entreprise correspondante trouvée');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Pas assez de crédits :', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Le registre ne répond pas pour le moment, réessaie plus tard');
  } else if (error instanceof HandelsregisterError) {
    console.log('Erreur :', error.statusCode, error.message);
  } else {
    throw error;
  }
}

En cas d’erreurs réseau, de statut 429 et d’erreurs serveur, le SDK retente seul, avec jusqu’à trois tentatives au total. Si l’API envoie un temps d’attente dans Retry-After, il le respecte.

Par défaut, le client attend une réponse pendant 90 secondes. Pour le mode temps réel, les profils de personne et les documents, nous recommandons au moins 120 secondes, soit timeout: 120000.

Ligne de commande

Le paquet fournit le programme handelsregister. Il récupère des profils d’entreprise, des profils de personne et des documents, recherche des entreprises et enrichit des fichiers.

Terminal

# Profil d’entreprise sans mode IA, avec les indicateurs financiers uniquement
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Enregistrer la liste des associés en PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Sans autre option, handelsregister fetch active le mode IA. Une requête coûte alors 25 crédits au lieu de 5, même sans fonctionnalités. Avec --no-ai-search, tu interroges sans mode IA.

handelsregister document recherche d’abord l’entreprise via un profil d’entreprise sans mode IA. 5 crédits s’ajoutent donc aux 15 crédits du document.

Référence

La référence complète avec toutes les méthodes se trouve dans le README du dépôt. Le SDK couvre toute l’API :

Profils d’entreprise avec toutes les fonctionnalités, aussi sous forme de classe Company
Profils de personne, aussi sous forme de classe Person
Recherche & Export avec filtres, tri et pagination automatique
Documents sous forme de fichiers
Signals, Monitoring et endpoints webhook, avec vérification de la signature des webhooks
Compte, solde, consommation et clés API
Enrichissement de fichiers CSV, JSON et Excel entiers

Le SDK est publié sous licence AGPL-3.0. Tu trouves le code source sur GitHub et le paquet sur npm.

fetch-organization Tous les paramètres, fonctionnalités et champs du profil d’entreprise. SDK Python La même API depuis Python.