基本概念

企業を一意に特定する

fetch-organizationのパラメータqは3種類の入力を受け付けます。このページの例は、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はそのうちの1社（目的の企業とは限りません）を返すか、404を返すことがあります。正しい企業であることが重要な場合は、登記裁判所と登記番号、またはentity_idで照会してください。

APIが企業を見つけられない場合は404を返し、何も課金しません。あいまいな入力にはAIモード（ai_search=on-default）があります。名称の一部からでも企業を見つけ、Webで調査します。企業が見つからなくても 20 クレジットが追加でかかります。複数の候補を一度に得るには検索とエクスポートを使ってください。

機能

すべての企業プロフィールには、名称、法的形態、ステータス、登記事項、住所、目的、業種、資本金、代表権の定めを含む基本データが入っています。それ以外はすべて機能としてリクエストします。例えば、業務執行者にはrelated_persons、財務KPIにはfinancial_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は各リクエストの前に、残高が最大限の料金をまかなえるかを確認します。足りない場合は402を返し、何も課金しません。実際に課金された額はmeta.request_credit_costに、その後の残高はmeta.credits_remainingにあります。

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

200 · 基本データのみの例のリクエストのmeta

クレジットは、スタートクレジットとして、クレジットサブスクリプションで毎月、またはチャージクレジットとして1回限りで得られます。クレジットサブスクリプションがない場合、スタートクレジットとチャージクレジットは 30 日間有効です。サブスクリプションが有効な間は失効しません。その他はすべて課金にあります。

データの鮮度とリアルタイム

デフォルトでは、企業プロフィールは私たちのデータベースから提供されます。情報の鮮度は、その情報源によって異なります。

商業登記簿

基本データ、人物、登記公告は、登記簿から私たちのデータベースで最新の状態に保っています。高速で、ほとんどの用途には十分です。

リアルタイム（realtime_mode=handelsregister-default）を使うと、APIはリクエストの時点で商業登記簿（Handelsregister）から現在事項抄本（Aktueller Abdruck、AD）をライブで取得し、JSONで返します。related_persons.currentに現在登記されている人物も含まれ、その機能の料金はかかりません。

ライブ取得が成功したかどうかは_realtime_mode.statusに表示されます。リアルタイムの 10 クレジットはsuccessの場合にのみ課金します。

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を返し、何も課金しません。その場合は後でもう一度試してください。

年次財務諸表

新しく公開された年次財務諸表を毎日探しています。ただし企業は事業年度末から最大12か月以内に公開すればよく（§ 325 HGB）、多くの企業がその期限をいっぱいまで使います。法定期限を意図的に守らず、さらに遅れて公開する企業もあります。

そのため、最新の財務諸表が前々年のものであることもよくあります。詳しくは鮮度で。

倒産公告

倒産裁判所は通常、決定の当日かその直後に公告を公開します。機能insolvency_publicationsで、それぞれ裁判所、事件番号、日付付きで受け取れます。

ニュース

機能newsは、Webから企業に関するニュースをタイトル、情報源、日付、リンク付きで返します。鮮度は、その企業が最後に報道された時期によります。小規模な企業では、該当する報道が少ないことがよくあります。

履歴と有効期間

多くの情報は時間とともに変わります。そのためAPIは、現在の状態と履歴を並べて返します：

currentは今日時点の状態です。
historyは登記されたすべての状態をeffective_fromとeffective_to付きで列挙します。effective_toがnullなら、その状態は現在も有効です。
人物はrelated_persons.currentとrelated_persons.pastにあり、それぞれstart_dateとend_dateが付きます。

履歴を持つ情報はすべて登記簿と公告から来ています。例えば商業登記簿の履歴抄本（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はこれを2つの方法で示します：

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: 組織再編とM&A	含まれない	含まれない	含まれる

APIは、プラン外の機能をエラーなしで省き、課金しません。プラン外の人物プロフィールと検索フィルターは403で拒否し、これも無料です。Signalsでは、明示的にリクエストしたトピックにこれが適用されます。指定しなければ、プランのすべてのトピックを受け取れます。

プランの料金とクレジットは料金ページで確認できます。