Node SDK

JavaScriptとTypeScriptからAPIを。

Node SDKは、リクエストとレスポンスの型定義付きで、JavaScriptとTypeScript用のクライアントを提供します。一時的なエラーは自動で再試行し、エラーレスポンスを専用のエラークラスに変換します。

インストール

npmでhandelsregisterパッケージをインストールします。

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から読み込みます。クライアントの作成時に渡すこともできます。BearerトークンはHANDELSREGISTER_BEARER_TOKENまたはbearerTokenで渡します。キーは常にヘッダーで送られ、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でさらに多くのデータを、aiSearch: trueでAIモードを、realtimeMode: trueでリアルタイムをリクエストします。すべての機能はfetch-organizationに記載しています。

JavaScript

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

1時間の間、クライアントは同一のリクエストにキャッシュから応答し、新たなクレジットはかかりません。リアルタイム付きのリクエストは常にAPIに送られます。キャッシュをオフにするにはcacheEnabled: falseを指定してください。

エラーを処理する

APIのエラーレスポンスはすべて、独自のクラスを持つエラーになります。どれもHandelsregisterErrorを継承し、statusCode、responseにレスポンス、metaにコストを持ちます。

例外
例外	ステータス	意味
AuthenticationError	401	APIキーがないか、無効。
InsufficientCreditsError	402	残高がこのリクエストに足りない。
SubscriptionRequiredError	403	リクエストには上位のプランが必要。`requiredPlans`が該当するプランを示す。
NotFoundError	404	一致する企業または人物が見つからない。
RequestTimeoutError	408	登記簿が時間内に応答しなかった。何も課金されていない。
RequestValidationError	400, 422	パラメータの値が無効。
RateLimitError	429	1分あたりのリクエストが多すぎる。
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;
  }
}

ネットワークエラー、ステータス429、サーバーエラーでは、SDKは合計最大3回まで自動で再試行します。APIがRetry-Afterで待ち時間を送れば、それに従います。

デフォルトでは、クライアントはレスポンスを 90 秒待ちます。リアルタイム、人物プロフィール、書類には 120 秒以上、つまりtimeout: 120000をおすすめします。

コマンドライン

パッケージにはhandelsregisterプログラムが付いています。企業プロフィール、人物プロフィール、書類を取得し、企業を検索し、ファイルを補完します。

Terminal

# AIモードなし、財務KPIのみの企業プロフィール
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モードをオンにします。その場合リクエストは、機能なしでも 5 ではなく 25 クレジットかかります。--no-ai-searchを付けると、AIモードなしでリクエストします。

handelsregister documentは、まずAIモードなしの企業プロフィールで企業を調べます。そのため、書類の 15 クレジットに 5 クレジットが加わります。

リファレンス

すべてのメソッドを含む完全なリファレンスは、リポジトリのREADMEにあります。SDKはAPI全体をカバーしています：

すべての機能付きの企業プロフィール。Companyクラスとしても
人物プロフィール。Personクラスとしても
フィルター、並べ替え、自動ページ送り付きの検索とエクスポート
ファイルとしての書類
Signals、モニタリング、Webhookエンドポイント。Webhookの署名検証付き
アカウント、残高、利用状況、APIキー
CSV、JSON、Excelファイル全体の補完

SDKのライセンスはAGPL-3.0です。ソースコードはGitHubに、パッケージはnpmにあります。

fetch-organization 企業プロフィールのすべてのパラメータ、機能、フィールド。 Python SDK 同じAPIをPythonから。