API REFERENCE

バンゴーAPI ドキュメント

法人番号APIとインボイスAPIを統合した7エンドポイントの仕様をまとめています。実行確認は Playground を利用してください。

Playgroundで試す

概要

法人番号APIとインボイスAPIを統合し、法人と個人事業主の両ケースをJSONで返します。

認証

x-api-key ヘッダーにAPIキーを指定します。キーはダッシュボードから発行・失効できます。

レート制限

Freeプランは GET /v1/invoice/{registration_number}/valid のみ（月500件）利用できます。

エラーコード

VALIDATION_ERROR UNAUTHORIZED FORBIDDEN NOT_FOUND BATCH_NOT_COMPLETED BATCH_FAILED を返します。

クイックスタート

最短で疎通確認するための手順です。まずは `/valid` でレスポンス構造と認証ヘッダーを確認します。

1. x-api-key を発行してヘッダーに設定します。
2. GET /v1/invoice/{registration_number}/valid を実行します。
3. 返却された valid registration_date expire_date を実装側の型に反映します。

クイックスタートをPlaygroundで試す

バッチ名寄せの使い方

大量データは `POST /v1/batch/match` を起点に非同期で処理します。進捗確認とダウンロード導線までを一連で確認できます。

1. companies に企業名を複数行で入力してジョブを作成します。
2. GET /v1/batch/{job_id} を2秒間隔で確認し status が completed になるまで待ちます。
3. 完了後に GET /v1/batch/{job_id}/download で json / csv を取得します。

バッチ名寄せの使い方をPlaygroundで試す

個人事業主への対応

個人事業主ケースでは公開方針により企業情報フィールドが `null` になるため、表示・保存ロジックの分岐を事前に設計します。

GET /v1/invoice/{registration_number} の返却で corporate_number name address trade_name popular_name は null になることがあります。
アプリ側では null 前提で表示をフォールバックし、インボイス有効性 (invoice.*) を中心に業務判定を行ってください。

個人事業主への対応をPlaygroundで試す

過去日付での有効性確認

`date=YYYY-MM-DD` を渡すことで、過去時点での登録有効性を判定できます。監査・経費精算用途では必須の確認です。

GET /v1/invoice/{registration_number}/valid?date=2024-10-01 のように実行します。
date は時刻・タイムゾーンを持たない暦日（YYYY-MM-DD）です。
取消日・失効日は当日から無効として判定されます。
返却される valid と cancel_date expire_date を使って、対象日での取引妥当性を判断します。

過去日付での有効性確認をPlaygroundで試す

GET

/v1/companies/{corporate_number}

法人番号検索

13桁の法人番号から法人情報とインボイス情報を返します。

パラメータ

name	in	type	required	description
corporate_number	path	string	Yes	13桁の法人番号

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.example.com/v1/companies/1234567890123'

レスポンス例

{
  "corporate_number": "1234567890123",
  "name": "株式会社サンプル",
  "kind": "株式会社",
  "invoice": {
    "found": true,
    "registration_number": "T1234567890123",
    "valid": true
  }
}

レスポンス項目

field	type	nullable	description
corporate_number	string	No	13桁の法人番号
name	string	No	商号または名称
name_kana	string	Yes	商号または名称（カナ表記）
name_en	string	Yes	商号または名称（英語表記）
kind	string	No	法人種別（例: 株式会社）
address.full	string	Yes	本店所在地の完全住所
status.active	boolean	No	現時点で活動中かどうか
assignment_date	string	Yes	法人番号指定日（YYYY-MM-DD）
updated_at	string	Yes	最終更新日（YYYY-MM-DD）
invoice.found	boolean	No	インボイス情報が見つかったかどうか
invoice.registration_number	string	Yes	インボイス登録番号（T + 13桁）
invoice.valid	boolean	Yes	現時点で有効な登録番号かどうか

このエンドポイントをPlaygroundで試す

GET

/v1/invoice/{registration_number}

T番号検索

T番号から法人情報または個人事業主情報（個人情報はnull）を返します。

パラメータ

name	in	type	required	description
registration_number	path	string	Yes	T + 13桁の登録番号

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.example.com/v1/invoice/T1234567890123'

レスポンス例

{
  "corporate_number": null,
  "kind": "individual",
  "name": null,
  "address": null,
  "invoice": {
    "registration_number": "T9999999999999",
    "registration_date": "2023-10-01",
    "valid": true
  }
}

レスポンス項目

field	type	nullable	description
corporate_number	string	Yes	法人の場合は13桁の法人番号、個人事業主はnull
kind	string	No	種別（法人または individual）
name	string	Yes	名称。個人事業主ケースではnull
name_kana	string	Yes	名称カナ。個人事業主ケースではnull
trade_name	string	Yes	個人事業主の屋号。存在しない場合はnull
popular_name	string	Yes	個人事業主の通称・旧姓。存在しない場合はnull
address	object	Yes	所在地情報。個人事業主ケースではnull
invoice.found	boolean	No	インボイス情報が見つかったかどうか
invoice.registration_number	string	No	インボイス登録番号（T + 13桁）
invoice.registration_date	string	Yes	登録日（YYYY-MM-DD）
invoice.cancel_date	string	Yes	取消日（YYYY-MM-DD）
invoice.expire_date	string	Yes	失効日（YYYY-MM-DD）
invoice.valid	boolean	No	現時点で有効な登録番号かどうか

注意事項

個人事業主ケースでは name / address / trade_name / popular_name は null です。

このエンドポイントをPlaygroundで試す

GET

/v1/invoice/{registration_number}/valid

過去日付有効性確認

指定日付時点で登録番号が有効かを判定します。

パラメータ

name	in	type	required	description
registration_number	path	string	Yes	T + 13桁
date	query	string	Yes	判定対象の暦日（YYYY-MM-DD、時刻・タイムゾーンなし）

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.example.com/v1/invoice/T1234567890123/valid?date=2024-10-01'

レスポンス例

{
  "date": "2024-10-01",
  "valid": true,
  "registration_date": "2023-10-01",
  "expire_date": null,
  "cancel_date": null
}

レスポンス項目

field	type	nullable	description
date	string	No	判定対象日（YYYY-MM-DD）
valid	boolean	No	対象日での有効性
registration_date	string	Yes	登録日（YYYY-MM-DD）
expire_date	string	Yes	失効日（YYYY-MM-DD）
cancel_date	string	Yes	取消日（YYYY-MM-DD）

注意事項

Freeプランで利用できる唯一のエンドポイントです。
date は時刻を持たない暦日として扱います。取消日・失効日は当日から無効です。

このエンドポイントをPlaygroundで試す

GET

/v1/companies/search

法人名検索

部分一致（partial）または法人格除去完全一致（exact）で検索します。

パラメータ

name	in	type	required	description
q	query	string	Yes	検索クエリ（partial時は2文字以上）
mode	query	string	No	partial / exact
prefecture	query	string	No	都道府県コード（2桁）
limit	query	number	No	件数（1〜50）

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.example.com/v1/companies/search?q=オープンコレクター&mode=partial&limit=10'

レスポンス例

{
  "results": [
    {
      "corporate_number": "1234567890123",
      "name": "株式会社オープンコレクター",
      "score": 0.92
    }
  ],
  "total": 1
}

レスポンス項目

field	type	nullable	description
results	array	No	検索結果の配列
results[].corporate_number	string	No	候補企業の法人番号
results[].name	string	No	候補企業の名称
results[].name_kana	string	Yes	候補企業の名称カナ
results[].address.prefecture	string	Yes	都道府県名
results[].address.city	string	Yes	市区町村名
results[].score	number	No	一致スコア（0〜1）
total	number	No	返却した候補件数

注意事項

mode=partial で q が1文字の場合は 400 VALIDATION_ERROR です。
mode=exact は1文字でも検索できます。

このエンドポイントをPlaygroundで試す

POST

/v1/batch/match

バッチ名寄せ受付

企業名リストを投稿して非同期ジョブを作成します。

パラメータ

name	in	type	required	description
companies	body	string[]	Yes	企業名配列（最大1,000件）

リクエスト例

curl -X POST -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"companies":["株式会社サンプル","合同会社サンプル"]}' \
  'https://api.example.com/v1/batch/match'

レスポンス例

{
  "job_id": "batch_abc123",
  "status": "queued",
  "total": 2
}

レスポンス項目

field	type	nullable	description
job_id	string	No	作成されたバッチジョブID
status	string	No	初期状態（queued）
total	number	No	受付件数

このエンドポイントをPlaygroundで試す

GET

/v1/batch/{job_id}

バッチ進捗取得

job_id の進捗と結果を取得します。

パラメータ

name	in	type	required	description
job_id	path	string	Yes	バッチジョブID

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.example.com/v1/batch/batch_abc123'

レスポンス例

{
  "job_id": "batch_abc123",
  "status": "processing",
  "progress": { "done": 450, "total": 1000 }
}

レスポンス項目

field	type	nullable	description
job_id	string	No	対象バッチジョブID
status	string	No	ジョブ状態（queued / processing / completed / failed）
progress.done	number	Yes	処理済み件数
progress.total	number	Yes	総件数
summary.confident	number	Yes	confident 判定件数（completed時）
summary.review	number	Yes	review 判定件数（completed時）
summary.unmatched	number	Yes	unmatched 判定件数（completed時）
results	array	Yes	名寄せ結果配列（completed時）

このエンドポイントをPlaygroundで試す

GET

/v1/batch/{job_id}/download

バッチ結果ダウンロード

完了済みジョブの結果を json または csv で取得します。

パラメータ

name	in	type	required	description
job_id	path	string	Yes	バッチジョブID
format	query	string	No	json / csv

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.example.com/v1/batch/batch_abc123/download?format=csv'

レスポンス例

{
  "error": {
    "code": "BATCH_NOT_COMPLETED",
    "message": "バッチジョブはまだ完了していません"
  }
}

レスポンス項目

field	type	nullable	description
results	array	Yes	format=json かつ completed 時の名寄せ結果配列
error.code	string	Yes	未完了・失敗時のエラーコード
error.message	string	Yes	未完了・失敗時の説明メッセージ
raw csv	text/csv	Yes	format=csv かつ completed 時はCSV文字列を返却

注意事項

status=queued/processing では 409 BATCH_NOT_COMPLETED を返します。
status=failed では 409 BATCH_FAILED を返します。

このエンドポイントをPlaygroundで試す

概要

認証

レート制限

エラーコード

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

関連ガイド

パラメータ

リクエスト例

レスポンス例

レスポンス項目

注意事項