Node SDK

L’API da JavaScript e TypeScript.

Il Node SDK fornisce un client per JavaScript e TypeScript, con definizioni di tipo per richieste e risposte. Ripete da solo gli errori temporanei e trasforma le risposte di errore in classi di errore dedicate.

Installazione

Installa il pacchetto handelsregister con npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=LA_TUA_CHIAVE_API

Cosa
Cosa	Valore
Pacchetto	`handelsregister`
Versione attuale	0.7.0
Node.js	22.13 o successiva
TypeScript	Definizioni di tipo incluse
Licenza	AGPL-3.0
Codice sorgente	github.com/Handelsregister-AI/handelsregister-js

L’SDK legge la tua chiave API dalla variabile d’ambiente HANDELSREGISTER_API_KEY. Puoi anche passarla quando crei il client. Un bearer token passa tramite HANDELSREGISTER_BEARER_TOKEN o bearerToken. La chiave viene sempre inviata nell’header, mai nell’URL.

Prima richiesta

fetchOrganization recupera un profilo aziendale e restituisce la risposta dell’API come oggetto. Il parametro q accetta un nome, tribunale del registro con numero di registro o un entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

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

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

La risposta è la stessa di fetch-organization. Eccone un estratto:

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 · Estratto dalla nostra risposta di esempio per Hetzner Online GmbH, Ansbach HRB 6089, solo dati di base

Più dati li richiedi con features, la Modalità AI con aiSearch: true e Tempo reale con realtimeMode: true. Tutte le feature sono elencate in fetch-organization.

JavaScript

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

Per un’ora il client risponde alle richieste identiche dalla sua cache, senza nuovi crediti. Le richieste con Tempo reale vanno sempre all’API. Imposta cacheEnabled: false per disattivare la cache.

Gestire gli errori

Ogni risposta di errore dell’API diventa un errore con una sua classe. Tutte ereditano da HandelsregisterError e riportano statusCode, la risposta in response e i costi in meta.

Eccezione
Eccezione	Stato	Significato
AuthenticationError	401	Chiave API mancante o non valida.
InsufficientCreditsError	402	Il tuo saldo non basta per questa richiesta.
SubscriptionRequiredError	403	La richiesta richiede un piano superiore. `requiredPlans` indica i piani adatti.
NotFoundError	404	Nessuna azienda o persona corrispondente trovata.
RequestTimeoutError	408	Il registro non ha risposto in tempo. Non è stato addebitato nulla.
RequestValidationError	400, 422	Un parametro ha un valore non valido.
RateLimitError	429	Troppe richieste al minuto.
ServerError	5xx	La fonte dei dati al momento non è disponibile o è sovraccarica. Riprova più tardi.

JavaScript

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

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

try {
  const azienda = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Nessuna azienda corrispondente trovata');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Crediti insufficienti:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('Il registro non risponde al momento, riprova più tardi');
  } else if (error instanceof HandelsregisterError) {
    console.log('Errore:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Con errori di rete, stato 429 ed errori del server, l’SDK ripete da solo, con al massimo tre tentativi in totale. Se l’API invia un tempo di attesa in Retry-After, lo rispetta.

Di default il client attende una risposta per 90 secondi. Per Tempo reale, profili persona e documenti consigliamo almeno 120 secondi, cioè timeout: 120000.

Riga di comando

Il pacchetto include il programma handelsregister. Recupera profili aziendali, profili persona e documenti, cerca aziende e arricchisce file.

Terminal

# Profilo aziendale senza Modalità AI, solo con KPI finanziari
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Salva l’elenco soci come PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Senza altre opzioni, handelsregister fetch attiva la Modalità AI. Una richiesta costa allora 25 crediti invece di 5, anche senza feature. Con --no-ai-search richiedi senza Modalità AI.

handelsregister document cerca prima l’azienda tramite un profilo aziendale senza Modalità AI. Ai 15 crediti del documento si aggiungono quindi 5 crediti.

Riferimento

Il riferimento completo con tutti i metodi è nel README del repository. L’SDK copre l’intera API:

Profili aziendali con tutte le feature, anche come classe Company
Profili persona, anche come classe Person
Ricerca & Export con filtri, ordinamento e paginazione automatica
Documenti come file
Signals, Monitoring ed endpoint webhook, con verifica della firma dei webhook
Account, saldo, consumo e chiavi API
Arricchimento di interi file CSV, JSON ed Excel

L’SDK è rilasciato con licenza AGPL-3.0. Il codice sorgente lo trovi su GitHub e il pacchetto su npm.

fetch-organization Tutti i parametri, le feature e i campi del profilo aziendale. Python SDK La stessa API da Python.