国税庁の法人番号システム API を利用して、法人情報を検索する
この記事について
「法人番号システム API 」を利用して法人検索の機能を実装したので、実装の備忘録を残します。
あくまで個人的な備忘録なので、利用方法によっては必要な情報が不足しているかもしれません。公開されている仕様書に目を通すことを推奨します。
仕様書: https://www.houjin-bangou.nta.go.jp/pc/webapi/images/k-web-api-kinou-gaiyo.pdf
※この記事を執筆している時点では、法人番号システムの API の最新バージョンは「4」です。
API 概要
法人番号システム API とは
法人番号システム API とは、国税庁が公開している API。法人情報の検索が可能。
API の仕様に関しては、 こちらの PDF を見れば必要な情報は一通り記載されている。
アプリケーション ID
法人番号システムを利用するためには、アプリケーション ID が必要。
自分らのケースでは、申請から交付までに1ヶ月近くかかったので、早めの申請が良さそう。
期限によるアプリケーション ID の失効については、特に記述を見つけられなかった。なのでそのようなケースはあまり考慮していないが、その場合には 404 エラーが返却されるはずなので、それをハンドリングすれば良い。
ちなみに、法人番号システムの利用を停止する場合は、国税庁に連絡が必要。
利用したパラメータ
この文章を執筆している時点では、API のバージョンは「1, 2, 3, 4」がある。ひとまず最新の「4」を利用した。
それ以外のパラメータとしては、以下のような指定をしている。
- type="12": レスポンスを XML 形式で受け取る（JSON はなく、XML か CSV の 2 択）
- history="0": 履歴情報は取得しない
- close="0": 閉鎖済み法人は取得しない
API 送信時に version=4&type=12&history=0&close=0 のようにクエリパラメータを付与すればよい。
指定可能なクエリパラメータは、API エンドポイントによって異なる。
3つのエンドポイント
API エンドポイントとしては、以下の3つが公開されている。
- 法人番号による検索
- 取得期間による検索
- 法人名による検索
法人番号を指定して情報を取得するエンドポイント
法人番号(必須)による検索。
API: https://api.houjin-bangou.nta.go.jp/{version}/num?id={application_id}&...(検索条件)
「法人番号 桁数」で検索すると12桁か13桁のような情報が出てくるが、法人番号システム API としては13桁のみ受け付けている。
取得期間を指定して情報を取得するエンドポイント
利用していないため省略。
法人名を指定して情報を取得するエンドポイント
法人名(必須)や都道府県コード(任意)や市区町村コード（任意）による検索。
API: https://api.houjin-bangou.nta.go.jp/{version}/name?id={application_id}&...(検索条件)
送信する法人名は URL エンコードされた全角文字列である必要がある。
検索方式 mode （前方一致と部分一致）と検索対象 target （あいまい検索と完全一致検索） の 2 つの概念があることに注意。
target の完全一致検索とは Case Sensitive という意味であることに留意。例えば、 ｢A｣ で ｢株式会社ABC｣ が検索ヒットするが、｢株式会社abc｣はヒットしない。
ちなみに、海外を表す都道府県コードは 99 となっている。
実装に際しての注意点
以下、実装しながら発覚した、法人番号システム API を利用するうえでの注意点など。
検索結果が多すぎるエラー
｢あ｣などの法人名で検索を行うと、検索結果が多すぎるというエラーが返却される。
ステータスコードは400で、レスポンス内に 180,検索結果件数が多いため結果をお返しできません。条件を追加するか、又は条件を変更してください のような文字列が含まれる。
このような場合、検索条件を厳しくして再検索する必要があるかもしれない。都道府県コード･市区町村コードを指定する、など。
ちなみに ?mode=1&target=2 というクエリパラメータの指定を行うと、検索の仕方としては最小の結果になる。 逆に ?mode=2&target=1 だと検索結果が多くなる。
アクセス制限
多数のリクエストを送ると、アプリケーション ID に対してアクセス制限が適用される。アクセス制限中は 403 エラーが返却される。
具体的な基準数は不明。
アクセス制限の基準となる具体的なアクセス回数・時間については、セキュリティ上の理由によりお答えできません。
https://www.houjin-bangou.nta.go.jp/shitsumon/shosai.html?selQaId=00100
アクセス制限は、一定の時間経過によって自動で解除される。
エラーハンドリング
法人番号システム API がエラーを返すケースについて。
クエリパラメータに誤りがある場合、400 エラーが返される。これは自分たちのアプリケーションの問題なので、エラーのクリティカル度合いは高くない。
400以外のエラーとしては、以下の3つがある。
- 403: アクセス制限
- 404: アプリケーション ID に問題あり
- 500: 法人番号システム API の障害
これらはアプリケーションにとってクリティカルなエラーなので、ハンドリングすることが望ましい。
Discussion