書類をダウンロードする

登記簿抄本、株主名簿、定款をファイルで。

fetch-documentは商業登記簿（Handelsregister）から書類を取得し、ファイルとして返します。PDF、または構造化された登記内容の場合はXMLです。必要なのは企業のentity_idだけです。企業プロフィールを取得するを参照。

書類の種類を選ぶ

書類の種類は5つあります。種類は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）の現在事項抄本を保存しています。

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は必要に応じて登記簿から書類を取得します。これには最大2分かかることがあります。クライアントのタイムアウトを120秒以上に設定するか、バックグラウンドで書類を取得してください。

バックグラウンドで取得する

クライアントがそれほど長く待てない場合は、async=trueを指定します。書類がすでにあればすぐに返ります。そうでなければ、APIはHTTP 202を返し、待ち時間を秒単位でRetry-Afterに示します。例では、SAP SE（Mannheim HRB 719915）の履歴抄本を取得しています。

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の履歴抄本を取得中のレスポンス例

この時間が経ったら同じリクエストを繰り返すと、ファイルがHTTP 200で返ります。クレジットがかかるのは提供されたファイルだけで、202のレスポンスは無料です。現在空きがない場合は、同じくRetry-After付きでHTTP 503が返ります。

繰り返しのたびに制限にカウントされます。短い間隔で何度も問い合わせず、示された時間だけ待ってください。

コストと制限

コストと制限
内容	クレジット
提供された書類1件	15

制限：1分あたり 5 リクエスト。検索、書類、Signalsは1分あたり 60 リクエストの枠を共有します。

提供された書類は、種類にかかわらず1件 15 クレジットです。各書類は登記簿から取得するため、fetch-documentには独自の、より低い制限（1分あたり 5 リクエスト）があります。

Idempotency-Keyを使えば、リクエストが途中で切れて繰り返した場合でも、書類の料金は1回分だけです。詳しくは制限で。

商業登記簿に現在接続できないか、応答が遅すぎる場合は、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を見つける。制限 1分あたりのリクエスト数と、二重課金なしの再試行。