基本概念 – 文档 | handelsregister.ai

唯一地找到公司

fetch-organization 的参数 q 接受三种输入。本页的示例都是对 Hetzner Online GmbH（Ansbach HRB 6089）的请求：

唯一地找到公司
输入	示例	适用场景
公司名称	`Hetzner Online GmbH`	入门使用。名称请尽量写得与登记册中一样完整。
登记法院和登记号	`Ansbach HRB 6089`	对每家登记在册的公司都唯一。法院、登记类型和号码是一个整体。
entity_id	`94eb910fef13f94585c48c263fa446d4`	用于后续请求。每个响应中都会返回。

仅凭登记号不够，因为每个登记法院都自行编号。但顺序不限：在示例中，HRB 6089 Ansbach 也能找到同一家公司。

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Ansbach HRB 6089'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Ansbach HRB 6089",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Ansbach HRB 6089");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

如果多家公司同名，API 可能返回其中一家，不一定是你想要的那家，或返回 404。当找到正确的公司很重要时，请按登记法院和登记号或按 entity_id 查询。

如果 API 没有找到公司，会返回 404 且不收费。对于模糊输入，可以使用 AI 模式（ai_search=on-default）：它能根据名称的一部分找到公司，并在网络上检索。它额外收取 20 积分，即使没有找到公司。如需一次获得多个候选，请使用搜索与导出。

功能

每份公司档案都包含基本数据，包括名称、法律形式、状态、登记条目、地址、经营范围、行业、资本和代表规则。其余一切都作为功能请求，例如用 related_persons 获取总经理，用 financial_kpi 获取财务 KPI。

多个功能可以通过重复 feature 或以列表形式传入：features=related_persons,financial_kpi。每个功能在响应中都有自己的键。只有 publications 在响应中叫 history。

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'feature=related_persons' \
  --data-urlencode 'feature=financial_kpi'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "feature": ["related_persons", "financial_kpi"],
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("feature", "related_persons");
url.searchParams.append("feature", "financial_kpi");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

API 会忽略未知名称且不报错，因此请检查拼写。你的套餐不包含的功能会被省略，且不收费。

所有功能及其价格列于 fetch-organization，每个字段见数据目录。

积分

数据请求消耗积分。对于公司档案，规则如下：

当 API 返回一家公司时，收取 5 积分的基础价格。
功能仅在响应中返回数据时才消耗积分。空的功能免费，包括没有条目的 insolvency_publications。
实时模式和 AI 模式不是功能，而是有各自规则的附加费：
- 实时获取一旦成功，实时模式额外收取 10 积分。即使没有显示任何新内容也是如此。
- AI 模式额外收取 20 积分，即使没有找到公司。只有当 API 因耗时过长以 408 中止请求时，才免收附加费。
其他所有错误均不收费。

每个功能的具体规则见计费，价格见 fetch-organization。

举例：如果两个功能都返回数据，带 related_persons 和 financial_kpi 的基本数据费用为 5 + 2 + 1 = 8 积分。

每次请求前，API 会检查你的余额是否足以支付可能的最高价格。如果不够，API 返回 402 且不收费。实际扣除的积分见 meta.request_credit_cost，之后的余额见 meta.credits_remaining。

1{2  "meta": {3    "request_credit_cost": 5,4    "credits_remaining": 1455  }6}

200 · 我们仅含基本数据的示例请求中的 meta

你可以通过初始积分、积分订阅的每月发放或一次性充值积分获得积分。没有积分订阅时，初始积分和充值积分的有效期为 30 天；订阅有效期间，它们不会过期。其余内容见计费。

数据时效与实时模式

默认情况下，公司档案来自我们的数据库。一条信息有多新，取决于其来源。

Handelsregister

我们根据登记册在数据库中持续更新基本数据、人员和登记公告。这样速度快，足以满足大多数用途。

使用实时模式（realtime_mode=handelsregister-default）时，API 会在你请求的那一刻从 Handelsregister（商业登记册）实时获取 Aktueller Abdruck（AD，当前登记摘录），并以 JSON 返回。你还会在 related_persons.current 中获得当前登记的人员，无需为该功能付费。

实时获取是否成功，见 _realtime_mode.status。只有在 success 时，我们才收取实时模式的 10 积分。

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'realtime_mode=handelsregister-default'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "realtime_mode": "handelsregister-default",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("realtime_mode", "handelsregister-default");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

1{2  "name": "Hetzner Online GmbH",3  "_realtime_mode": {4    "mode": "handelsregister-default",5    "status": "success"6  },7  "related_persons": {8    "current": [9      {10        "entity_id": "78ad32e16ff779f589a9e88d23356f74",11        "label": "MANAGING_DIRECTOR",12        "role": {13          "en": {14            "long": "Managing Director",15            "short": "MD"16          },17          "de": {18            "long": "Geschäftsführer",19            "short": "GF"20          }21        },22        "name": "Max Mustermann",23        "name_parts": {24          "given": "Max",25          "family": "Mustermann",26          "maiden": null,27          "canonical_name": "Mustermann, Max",28          "aliases": [29            "Mustermann, Max"30          ],31          "previous_names": null32        },33        "start_date": null,34        "end_date": null,35        "birth_date": "1976-01-15",36        "location": {37          "home": {38            "city": "Musterheim"39          }40        },41        "organization_representation_scheme": {42          "current": [43            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."44          ],45          "history": []46        },47        "role_representation_scheme": {48          "current": [49            "einzelvertretungsberechtigt",50            "mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"51          ],52          "history": []53        }54      },55      {56        "entity_id": "73549375ff7d709b9e7e2941ad1ffaa3",57        "label": "MANAGING_DIRECTOR",58        "role": {59          "en": {60            "long": "Managing Director",61            "short": "MD"62          },63          "de": {64            "long": "Geschäftsführer",65            "short": "GF"66          }67        },68        "name": "Paul Musterwald",69        "name_parts": {70          "given": "Paul",71          "family": "Musterwald",72          "maiden": null,73          "canonical_name": "Musterwald, Paul",74          "aliases": [75            "Musterwald, Paul"76          ],77          "previous_names": null78        },79        "start_date": null,80        "end_date": null,81        "birth_date": "1989-07-18",82        "location": {83          "home": {84            "city": "Probebrück"85          }86        },87        "organization_representation_scheme": {88          "current": [89            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."90          ],91          "history": []92        },93        "role_representation_scheme": {94          "current": [95            "einzelvertretungsberechtigt"96          ],97          "history": []98        }99      },100      {101        "entity_id": "cfecded2c1d17946c8ab0379aa786eed",102        "label": "MANAGING_DIRECTOR",103        "role": {104          "en": {105            "long": "Managing Director",106            "short": "MD"107          },108          "de": {109            "long": "Geschäftsführer",110            "short": "GF"111          }112        },113        "name": "Jan Musterhuber",114        "name_parts": {115          "given": "Jan",116          "family": "Musterhuber",117          "maiden": null,118          "canonical_name": "Musterhuber, Jan",119          "aliases": [120            "Musterhuber, Jan"121          ],122          "previous_names": null123        },124        "start_date": null,125        "end_date": null,126        "birth_date": "1955-11-06",127        "location": {128          "home": {129            "city": "Probeingen"130          }131        },132        "organization_representation_scheme": {133          "current": [134            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."135          ],136          "history": []137        },138        "role_representation_scheme": {139          "current": [140            "einzelvertretungsberechtigt"141          ],142          "history": []143        }144      }145    ]146  },147  "meta": {148    "request_credit_cost": 15,149    "credits_remaining": 145150  }151}

200 · Hetzner Online GmbH 使用实时模式的示例响应节选

如果实时获取失败，API 会返回我们数据库中已存储的数据。你可以通过 _realtime_mode.status 判断，此时它不是 success。此时实时模式不计费，meta.request_credit_cost 也会显示这一点。

当今天的状态很重要时，实时模式就很值得。例如在签约前核查新的业务伙伴，或查看目前谁可以代表公司。

实时获取比普通获取耗时更长。请将客户端的超时设置为至少 120 秒。如果请求耗时过长，API 返回 408 且不收费。届时请稍后再试。

年度财务报表

我们每天查找新公布的年度财务报表。然而公司在财年结束后最多有十二个月的时间公布（§ 325 HGB），许多公司会用满期限。有些公司故意错过法定期限，公布得更晚。

因此最新的报表往往是前年的。详见时效。

破产公告

破产法院通常在裁定当天或不久之后公布公告。你可以通过功能 insolvency_publications 获取，每条含法院、案号和日期。

新闻

功能 news 返回网络上关于该公司的新闻，含标题、来源、日期和链接。新闻有多新，取决于该公司最近一次被报道的时间。小公司往往只有少量相关报道。

历史与有效期

许多信息会随时间变化。因此 API 会同时返回当前状态和历史：

current 是今天的状态。
history 列出每个已登记的状态，含 effective_from 和 effective_to。如果 effective_to 为 null，则该状态今天仍然有效。
人员位于 related_persons.current 和 related_persons.past 中，各含 start_date 和 end_date。

每条有历史的信息都来自登记册和公告，例如来自 Handelsregister 的 Chronologischer Abdruck（CD，按时间顺序的登记摘录），或来自所有已公布的年度财务报表。

在我们的示例中，Hetzner Online GmbH 的代表规则如下。在示例响应中，2015 年 7 月 28 日之前列出的是董事会，此后是总经理：

1{2  "representation_scheme": {3    "current": [4      "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."5    ],6    "history": [7      {8        "value": [9          "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."10        ],11        "effective_from": "2002-10-15",12        "effective_to": "2015-07-28"13      },14      {15        "value": [16          "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."17        ],18        "effective_from": "2015-07-28",19        "effective_to": null20      }21    ]22  }23}

示例响应：Hetzner Online GmbH 的 representation_scheme

大多数日期的格式为 YYYY-MM-DD。历史能追溯多久，见年限与历史。

空值

并非每家公司的每个字段都有值。API 以两种方式表示：

null：该字段没有值。
[]：列表没有条目，例如没有破产公告。

请求的功能没有数据时，返回 null 或 []，且不收费。

1{2  "name": "dm-drogerie markt GmbH + Co. KG",3  "legal_form": "GmbH & Co. KG",4  "contact_data": {5    "website": "https://www.dm.de",6    "phone_number": "+49 721 55920",7    "email": null8  },9  "capital": {10    "current": null,11    "history": []12  },13  "mergers_and_acquisitions": null,14  "insolvency_publications": []15}

dm-drogerie markt GmbH + Co. KG 的示例响应节选，含空值

在你的代码中，请将缺失的键、null 和 [] 同等对待，因为有些空对象以 [] 返回。另外请按名称读取字段，因为键的顺序不固定。

如果某个值缺失，通常是公司根本无须公布它。法律根据法律形式和规模要求公布什么，见数据可用性。我们会有意隐去部分信息；它们会带有 redacted: true。

稳定性与版本

API 以增量方式扩展。新数据和新功能以新字段的形式加入。我们绝不删除现有字段，不重命名，也不改变其类型或含义。因此每个版本都保持向后兼容。

会破坏现有代码的变更只会出现在新的 API 版本中，例如 /v2。当前版本运行在 /v1 下。

因此请让你的客户端忽略未知字段，并将未知取值作为一般情况处理。新字段和新功能列于更新日志。

套餐

任何账户都可以使用公司档案、文件、搜索与导出和 Signals，即使没有积分订阅。积分订阅每月带来新积分，并解锁更多数据：

套餐
额外获得的内容	Plus	Pro	Max
人物档案: 人员的职务与持股	包含	包含	包含
搜索与导出: 按所有权、管理层和破产筛选	不包含	包含	包含
公司档案: 90 多项扩展财务指标	不包含	包含	包含
公司档案: 能源供应商的业务活动报表（§ 6b EnWG）	不包含	不包含	包含
公司档案: 深度股东信息 (`shareholders_deep`)	不包含	不包含	包含
公司关系网络 (`network`)	不包含	包含	包含
Signals: 破产	不包含	包含	包含
Signals: 改制与并购	不包含	不包含	包含

API 会省略你套餐以外的功能且不报错，也不收费。对于你套餐以外的人物档案和搜索筛选条件，API 以 403 拒绝，同样不收费。对于 Signals，这适用于你明确请求的主题；不指定时，你只会得到你套餐的所有主题。

各套餐的价格和积分见价格页面。

继续阅读

获取公司档案名称、登记号或 entity_id 的实际用法。数据可用性根据法律形式和规模有哪些数据。计费所有价格，以及如何在每个响应中追溯。错误错误是什么样子，以及你可以怎么做。