下载文件

以文件形式获取登记摘录、股东名单和公司章程。

fetch-document 从 Handelsregister（商业登记册）获取一份文件，并以文件形式返回：PDF，或结构化登记内容的 XML。你只需要公司的 entity_id，见获取公司档案。

选择文件类型

共有五种文件类型。在 document_type 中传入类型，写法与表中完全一致，包括大小写。

document_type
document_type	文件	格式	适用于
AD	Aktueller Abdruck（当前登记摘录）：当前有效的所有条目	PDF	每家登记在册的公司
CD	Chronologischer Abdruck（按时间顺序的登记摘录）：按时间顺序的所有条目	PDF	每家登记在册的公司
SI	Strukturierter Registerinhalt（结构化登记内容），XJustiz 格式，机器可读	XML	每家登记在册的公司
shareholders_list	Gesellschafterliste（股东名单）	PDF	GmbH 和 UG
articles_of_association	Satzung 或 Gesellschaftsvertrag（公司章程）	PDF	资合公司和合作社

获取文件

将 entity_id 作为 company_id、类型作为 document_type 传入。响应是文件本身，而不是 JSON。我们的示例请求保存 Hetzner Online GmbH（Ansbach HRB 6089）的 Aktueller Abdruck。

curl -G "https://handelsregister.ai/api/v1/fetch-document" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "company_id=94eb910fef13f94585c48c263fa446d4" \
  --data-urlencode "document_type=AD" \
  --fail-with-body --max-time 120 \
  -o hetzner-ad.pdf

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-document",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "company_id": "94eb910fef13f94585c48c263fa446d4",
        "document_type": "AD",
    },
    timeout=120,
)
response.raise_for_status()
with open("hetzner-ad.pdf", "wb") as file:
    file.write(response.content)
print(response.headers["X-Credits-Charged"], "已扣除积分")

import { writeFile } from "node:fs/promises";

const url = new URL("https://handelsregister.ai/api/v1/fetch-document");
url.searchParams.append("company_id", "94eb910fef13f94585c48c263fa446d4");
url.searchParams.append("document_type", "AD");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
await writeFile("hetzner-ad.pdf", Buffer.from(await response.arrayBuffer()));
console.log(response.headers.get("x-credits-charged"), "已扣除积分");

由于响应不是 JSON，相关信息位于响应头中：

字段
字段	含义
Content-Type	`application/pdf`，结构化登记内容为 `application/xml`。
Content-Disposition	文件名，含 entity_id、类型以及文件取自登记册的日期。
X-Credits-Charged	请求的费用。
X-Credits-Remaining	之后的余额。

如果该公司没有这份文件，你会收到 HTTP 404，不收费。

1{2  "error": "Document fetch failed",3  "message": "Document not available for this company. It may not exist or may become available later.",4  "meta": {5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}

404 · 请求独资商人股东名单时的示例响应

API 在需要时从登记册获取文件。这可能需要长达两分钟。请将客户端的超时设置为至少 120 秒，或在后台获取文件。

在后台获取

如果你的客户端不能等那么久，请设置 async=true。如果文件已经可用，会立即返回。否则 API 返回 HTTP 202，并在 Retry-After 中给出以秒为单位的等待时间。在示例中，我们获取 SAP SE（Mannheim HRB 719915）的 Chronologischer Abdruck。

curl -G "https://handelsregister.ai/api/v1/fetch-document" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'company_id=e3918174fb6c5d04e5e217e6ee4a6ffe' \
  --data-urlencode 'document_type=CD' \
  --data-urlencode 'async=true'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-document",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "company_id": "e3918174fb6c5d04e5e217e6ee4a6ffe",
        "document_type": "CD",
        "async": "true",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-document");
url.searchParams.append("company_id", "e3918174fb6c5d04e5e217e6ee4a6ffe");
url.searchParams.append("document_type", "CD");
url.searchParams.append("async", "true");

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

1{2  "status": "processing",3  "meta": {4    "message": "The document is being retrieved. Repeat this request after Retry-After seconds to receive it.",5    "retry_after": 20,6    "request_credit_cost": 0,7    "credits_remaining": 1458  }9}

202 · 正在获取 SAP SE 的 Chronologischer Abdruck 时的示例响应

在这段时间后重复同一请求，文件就会以 HTTP 200 返回。只有交付的文件消耗积分；202 响应免费。如果当前没有空闲容量，你会收到 HTTP 503，同样带有 Retry-After。

每次重复都计入限制。因此请等待给定的时间，而不是频繁地再次询问。

费用和限制

费用和限制
项目	积分
一份已交付的文件	15

限制：每分钟 5 次请求。搜索、文件和 Signals 共用每分钟 60 次请求的配额。

每份交付的文件收取 15 积分，无论类型。由于每份文件都来自登记册，fetch-document 有自己的、较低的限制：每分钟 5 次请求。

使用 Idempotency-Key，即使请求中断后重复，一份文件也只付一次费。详见限制。

如果 Handelsregister 当前无法访问或响应太慢，你会收到带 Retry-After 的 HTTP 504。API 不收费。请几分钟后再试。

常见陷阱

用登记号代替 entity_id：company_id 只接受 32 位的 entity_id。Ansbach HRB 6089 会返回 HTTP 400。
其他法律形式的股东名单：它只适用于 GmbH 和 UG。对于 KG 或独资商人，你会收到 HTTP 404。
图像文件形式的文件：如果某份文件在登记册中只有 TIFF 格式，API 返回 HTTP 415，不收费。

继续阅读

fetch-document 该端点的参数、响应和错误。文件每份文件包含什么。获取公司档案查找公司的 entity_id。限制每分钟请求数以及重试而不重复计费。