# HojinCheck APIドキュメント

状態基準日: 2026-07-14 ・ [English version](https://hojincheck.com/docs/en) ・ [llms.txt](https://hojincheck.com/llms.txt)

日本の法人・政府オープンデータを、世界のあらゆるAIエージェントが扱えるようにする標準ツール。 HojinCheckは、日本の**政府オープンデータのみ**を源とする法人確認のリモートMCPサーバー＋REST APIです。法人名→法人番号の解決、法人番号の実在検証、適格請求書発行事業者（インボイス）登録番号の検証、法人プロファイル取得、日本住所の正規化、祝日・営業日計算の6ツールを提供します。全ての成功応答に、データ源・取得日時・各源の規約所定の表示文言（notices）が含まれます。

- ベースURL: `https://hojincheck.com`
- MCPエンドポイント（Streamable HTTP）: `https://hojincheck.com/mcp`
- RESTエンドポイント: `POST https://hojincheck.com/v1/{ツール名}`

## ツール別の提供状態（最初にお読みください）

| ツール | 状態 |
|---|---|
| `resolve_company` | 実装済み。政府API（法人番号システムWeb-API）のアプリケーションID発行待ち（2026-07-13届出済み・発行目安2026年7月末〜8月末）。接続までの間、本番では UPSTREAM_UNAVAILABLE（HTTP 503）を返します。 |
| `verify_company` | 実装済み。政府API（法人番号システムWeb-API）のアプリケーションID発行待ち（2026-07-13届出済み・発行目安2026年7月末〜8月末）。接続までの間、本番では UPSTREAM_UNAVAILABLE（HTTP 503）を返します。 |
| `verify_invoice_number` | 実装済み。適格請求書発行事業者公表システムWeb-APIは国税庁の審査承認制で、審査待ちです（2026-07-12申請・目安2026年8月中旬〜下旬）。承認までの間、本番では UPSTREAM_UNAVAILABLE（HTTP 503）を返します。 |
| `get_company_profile` | 稼働中（Gビズインフォ REST API v2 に実接続済み）。 |
| `normalize_address` | 稼働中（政府マスターデータのローカル同梱駆動・政府API停止の影響を受けません）。 |
| `jp_calendar` | 稼働中（政府マスターデータのローカル同梱駆動・政府API停止の影響を受けません）。 |

過大な表示を避けるため、未接続の状態をそのまま記載しています。政府APIの認証情報が発行され次第、本表を更新します。

## 認証

ツール呼び出し（MCP・RESTとも）にはAPIキーが必要です。以下いずれかのヘッダで渡してください。

```
Authorization: Bearer hjc_live_...
X-Api-Key: hjc_live_...
```

- Freeプラン: **100リクエスト/日**（日本時間の日付で更新）＋バースト**60リクエスト/分**。超過時は `RATE_LIMITED`（HTTP 429・`Retry-After` 付き）。応答ヘッダ `X-RateLimit-Remaining-Day` で当日の残数を返します。
- キーは自己申込ページ [https://hojincheck.com/signup](https://hojincheck.com/signup) で発行します。キーは発行時に**一度だけ**表示され、再表示・復旧はできません。受付を一時停止している場合は drogerdluffy@gmail.com までご連絡ください。
- `GET /v1/tools`（ツール一覧）と `GET /health` は認証不要です。

## 料金プラン

料金ティア（v0.2）の公表値です。JPY建てを主とし、USDは**参考値**（¥150/US$換算）です。課金通貨（JPY/USD）は課金開始時に確定します。**有償プランの購入受付は未開始**です——現時点で発行できるのはFreeのみで、受付開始は本ページで案内します。

| プラン | 料金 | 含まれる利用量 | 備考 |
|---|---|---|---|
| Free | ¥0（US$0） | 100リクエスト/日（JST）＋60/分バースト | 自己申込 |
| Starter | ¥2,980/月（参考 ~US$20/月） | 10,000リクエスト/月 |  |
| Pro | ¥9,800/月（参考 ~US$65/月） | 100,000リクエスト/月 | 優先レート |
| Business | ¥29,800/月（参考 ~US$199/月） | 500,000リクエスト/月 | 優先レート・セルフサーブ |
| Enterprise | 応相談 | 個別 | SLA・個別契約要件がある場合のみ——drogerdluffy@gmail.com まで |

**超過時もサービスを停止しません。** 含まれる利用量を超えた場合、リクエストを遮断するのではなくレート制限を強化し、正規のエラーエンベロープ——HTTP 429 `RATE_LIMITED`（課金開始後はHTTP 402）——で上位プランをご案内します。

## MCPでの接続

MCPエンドポイントはステートレスなStreamable HTTPです（`https://hojincheck.com/mcp`）。設定例（Claude Code）:

```
claude mcp add --transport http hojincheck https://hojincheck.com/mcp --header "Authorization: Bearer hjc_live_YOUR_KEY"
```

一般的なMCPクライアント設定:

```json
{
  "mcpServers": {
    "hojincheck": {
      "type": "http",
      "url": "https://hojincheck.com/mcp",
      "headers": { "Authorization": "Bearer hjc_live_YOUR_KEY" }
    }
  }
}
```

6ツールはREST APIと同一の名称・入力スキーマ・応答エンベロープで公開されます（ツール結果はJSONエンベロープのテキスト）。

## RESTでの呼び出し

`POST https://hojincheck.com/v1/{ツール名}` にJSONボディを送ります。例:

```
curl -X POST https://hojincheck.com/v1/jp_calendar \
  -H "Authorization: Bearer hjc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"is_business_day","date":"2026-07-14"}'
```

## 応答エンベロープ

全応答が共通形式です。成功時:

```json
{
  "ok": true,
  "result": { "...ツール固有..." },
  "sources": [
    {
      "name": "国税庁法人番号システムWeb-API",
      "url": "https://www.houjin-bangou.nta.go.jp/webapi/",
      "retrieved_at": "2026-07-12T04:10:00Z",
      "cache": { "hit": true, "stored_at": "2026-07-12T01:00:00Z", "stale": false }
    }
  ],
  "notices": ["...各データ源の規約所定の表示文言..."]
}
```

- `sources[].retrieved_at` は上流（データ源）から実際に取得した日時です。キャッシュ応答でも取得時点を保持します（鮮度メタ）。
- `notices` には各政府データ源の規約が求める出典表示・非保証文言が入ります。**データを表示・再提示する際はこの文言を保持してください。**

エラー時:

```json
{ "ok": false, "error": { "code": "RATE_LIMITED", "message": "...", "retryable": true }, "sources": [] }
```

| コード | HTTP | 意味 |
|---|---|---|
| `INVALID_ARGUMENT` | 400 | 入力の検証エラー（詳細は `message`） |
| `UNAUTHORIZED` | 401 | APIキーの欠落・不正・無効化済み |
| `NOT_FOUND` | 404 | 未知のツール・パス |
| `RATE_LIMITED` | 429 | キーの日次/バースト上限超過（`Retry-After` 付き） |
| `UPSTREAM_UNAVAILABLE` | 503 | 政府APIに接続不可（未接続を含む）かつキャッシュ不在 |
| `UPSTREAM_RATE_LIMITED` | 503 | 上流のレート制限中。時間をおいて再試行 |
| `INTERNAL` | 500 | 予期しないサーバーエラー |

補足: 「データとしての不存在」（例: 登録のない法人番号）はエラーではなく、`ok: true` のまま `exists: false` / `found: false` / `registered: false` で返します。

MCPでは、エラーもツール結果内で同じJSONエンベロープとして返します（`isError: true`）。

## キャッシュと鮮度

応答はデータ源ごとにキャッシュされます（法人番号照会: 6〜24時間／インボイス公表データ: 翌朝6時JSTの公表更新まで／gBizINFO: 7日）。政府API停止時は、期限切れキャッシュを `cache.stale: true`＋元の `retrieved_at` 付きで返すことがあり、鮮度は常に判別できます。`normalize_address` と `jp_calendar` はローカルマスター駆動のため政府API停止の影響を受けません。**例外: 個人事業主のインボイス情報を含む応答は一切キャッシュしません**（後述）。

## ツール

### resolve_company — 法人名から法人番号を解決

状態: 実装済み。政府API（法人番号システムWeb-API）のアプリケーションID発行待ち（2026-07-13届出済み・発行目安2026年7月末〜8月末）。接続までの間、本番では UPSTREAM_UNAVAILABLE（HTTP 503）を返します。

法人名（「(株)」等の略記・全半角・かな/カナ・旧字体の表記ゆれ対応）から法人番号の候補を検索し、確度スコア（0〜1）と根拠ラベル付きで返します。

入力:

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| `name` | string（1〜100） | ○ | 法人名（表記ゆれ可） |
| `address` | string | − | 所在地絞り込み: 都道府県コード2桁（JIS X 0401）または＋市区町村コード3桁の計5桁 |
| `include_closed` | boolean | − | 閉鎖法人を含める（既定 `true`） |
| `limit` | integer 1〜50 | − | 候補数上限（既定10） |

結果: `query`（正規化形・検索名・法人格）、`total_count`、`returned`、`truncated`、`candidates[]`（`corporate_number`・`name`・`furigana`・`kind`（コード＋ラベル）・`address`・`status`（`active`/`closed`）・`confidence`・`match`）。

データ源: 国税庁法人番号システムWeb-API。

### verify_company — 法人番号の実在検証

状態: 実装済み。政府API（法人番号システムWeb-API）のアプリケーションID発行待ち（2026-07-13届出済み・発行目安2026年7月末〜8月末）。接続までの間、本番では UPSTREAM_UNAVAILABLE（HTTP 503）を返します。

法人番号13桁をチェックディジット検証のうえ（不正は `INVALID_ARGUMENT`）、実在・商号・本店所在地・法人種別・閉鎖ステータスを返します。`include_history: true` で商号変更・所在地変更・閉鎖等の履歴も返します。

入力:

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| `corporate_number` | string | ○ | 法人番号13桁（全角・ハイフン・空白は吸収） |
| `include_history` | boolean | − | 履歴を含める（既定 `false`） |

結果: `corporate_number`・`exists`・`company`（レコード。なければ `null`）・`history[]`（任意）。登録がない番号は `ok: true`＋`exists: false` で返します。

データ源: 国税庁法人番号システムWeb-API。

### verify_invoice_number — 適格請求書発行事業者登録番号の検証

状態: 実装済み。適格請求書発行事業者公表システムWeb-APIは国税庁の審査承認制で、審査待ちです（2026-07-12申請・目安2026年8月中旬〜下旬）。承認までの間、本番では UPSTREAM_UNAVAILABLE（HTTP 503）を返します。

登録番号（T＋13桁）を国税庁公表システムに照会し、登録有無・登録年月日・取消/失効を返します。`on_date` 指定時はその基準日時点の有効性を `as_of` で返します。`include_history: true` で公表履歴も返します。

入力:

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| `registration_number` | string | ○ | T＋13桁（Tなし13桁・全角・ハイフン/空白は吸収） |
| `on_date` | `YYYY-MM-DD` | − | 基準日時点の有効性判定 |
| `include_history` | boolean | − | 公表履歴を含める（既定 `false`） |

結果: `registered`・`status`（`active`/`revoked`/`expired`/`null`）・`kind`・`name`・`trade_name`・`address`・`corporate_number`（法人の場合）・登録/更新/取消/失効の各日付・`as_of`（任意）・`history[]`（任意）。

**個人事業主の取り扱い（プライバシー設計）**: 入力は登録番号のみで、**氏名等による検索・逆引き機能はありません**。個人事業主の公表情報は登録番号確認の応答返却に限定し、**キャッシュ・保存を一切行いません**。本ツールを個人の名簿作成等に用いることは利用規約で禁止しています。

データ源: 国税庁適格請求書発行事業者公表システムWeb-API。

### get_company_profile — 法人プロファイル取得（gBizINFO）

状態: 稼働中（Gビズインフォ REST API v2 に実接続済み）。

法人番号（チェックディジット検証つき）からgBizINFOの法人プロファイル（所在地・代表者・資本金・従業員数等）を返します。gBizINFO v2の**項目別の出典・最終取得日メタ**（`metadata`）を透過し、規約所定の出典表示文字列（利用日付き・`attribution`）を含みます。

入力:

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| `corporate_number` | string | ○ | 法人番号13桁（全角・ハイフン・空白は吸収） |

結果: `found`（gBizINFOに掲載がない場合は `ok: true`＋`found: false`）・`profile`・`metadata`（項目別メタ）・`attribution`。

データ源: Gビズインフォ REST API v2（経済産業省）。

### normalize_address — 日本住所の正規化・要素分解・郵便番号照合

状態: 稼働中（政府マスターデータのローカル同梱駆動・政府API停止の影響を受けません）。

日本の住所文字列を正規化し、都道府県／市区町村／町字（大字・町名＋丁目）に分解、アドレス・ベース・レジストリの町字IDを解決し、郵便番号と照合します（不一致は不一致として明示し、勝手に補正しません）。

**v1の粒度と限界（必読）**: 分解は町字（大字・丁目）までです。**街区符号・住居番号・地番・小字・京都の通り名は解析対象外**で、未解析部分は `residual`（市区町村と町字の間は `skipped`）にそのまま返します。**推測による補完は行いません。**

入力:

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | string（1〜200） | ○ | 日本の住所文字列（郵便番号含み可・表記ゆれ可） |
| `postal_code` | `NNN-NNNN` | − | 郵便番号を別引数で渡す場合（住所内の記載より優先） |

結果: `normalized`・`resolved`（`prefecture`/`city`/`town`＝各コード＋ABR町字ID）・`residual`・`skipped`・`ambiguous_cities`（同名市で一意化不能な場合）・`postal`（照合結果）・`confidence`・`match`・`master_versions`（マスターのデータ日付）。

データ源: アドレス・ベース・レジストリ町字マスター（デジタル庁）＋日本郵便郵便番号データ（ローカルマスター駆動）。

### jp_calendar — 日本の祝日・営業日計算

状態: 稼働中（政府マスターデータのローカル同梱駆動・政府API停止の影響を受けません）。

内閣府「国民の祝日」CSV準拠の祝日判定・営業日計算です。営業日＝土日・祝日以外。`year_end_as_holiday: true` で12/29〜1/3も非営業日として扱います（官公庁・銀行休業の慣行）。

入力:

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| `op` | enum | ○ | `is_business_day`／`next_business_day`／`prev_business_day`／`add_business_days`／`list_holidays` |
| `date` | `YYYY-MM-DD` | 日付系opで○ | 基準日 |
| `days` | integer −1000〜1000 | `add_business_days`で○ | 加算する営業日数（負数=遡り） |
| `from`・`to` | `YYYY-MM-DD` | `list_holidays`で○ | 期間 |
| `year_end_as_holiday` | boolean | − | 12/29〜1/3を非営業日扱い（既定 `false`） |

祝日データ収録範囲: **1955-01-01〜2027-12-31**（内閣府CSVは毎年2月頃に翌年分が追加され、同梱スナップショットを月次で追随）。範囲外の日付は `INVALID_ARGUMENT`（収録範囲付き）を返します。

データ源: 内閣府「国民の祝日」CSV。

## データ源と出典表示

| データ源 | 提供元 |
|---|---|
| 法人番号システムWeb-API | 国税庁 |
| 適格請求書発行事業者公表システムWeb-API | 国税庁 |
| Gビズインフォ REST API v2 | 経済産業省 |
| アドレス・ベース・レジストリ（町字マスター） | デジタル庁 |
| 郵便番号データ | 日本郵便 |
| 「国民の祝日」CSV | 内閣府 |

本サービスは上記データを編集・加工して提供するものであり、**サービスの内容が国税庁その他の政府機関によって保証されたものではありません**。各応答の `notices` に、各源の規約が定める表示文言をそのまま含めています。データの再表示時はこの文言を保持してください。

## 法務・その他

- [利用規約](https://hojincheck.com/legal/terms) ・ [プライバシーポリシー](https://hojincheck.com/legal/privacy) ・ [特定商取引法に基づく表記](https://hojincheck.com/legal/tokusho)
- 与信判断は提供しません: 本サービスは公的登録情報の事実と出典を返すものであり、信用力の判断・格付けを提供するものではありません。
- お問い合わせ: drogerdluffy@gmail.com