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 从环境变量 HANDELSREGISTER_API_KEY 读取你的 API 密钥。你也可以在创建客户端时传入。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'],
});

在一小时内，客户端会从缓存中响应相同的请求，不再消耗积分。使用实时模式的请求始终发往 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	每分钟请求过多。
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 会自行重试，总共最多三次尝试。如果 API 在 Retry-After 中给出等待时间，SDK 会遵守。

默认情况下，客户端等待响应 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 模式。此时即使不请求功能，一个请求也要花费 25 积分，而不是 5。使用 --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 在 Python 中使用同一 API。