法人番号 API の選び方と使い方

国税庁の法人番号公表サイトと Web-API の違い、差分データの扱い、自前で取り込む場合に詰まる点、そして API を使うべき場合の判断基準。

法人番号のデータは無償で公開されています。それでも API を使う理由があるとすれば、データそのものではなく、取り込みを止めずに運用し続けることの難しさにあります。

国税庁が公開しているもの

法人番号公表サイトから、次の 2 種類がダウンロードできます。

• 全件データ — 登録されている全法人のスナップショット。月次で更新されます。法人番号の全国版は 1 ファイルで、圧縮状態で 250 MB 前後、展開すると 1 GB を超えます。
• 差分データ — 1 営業日ごとの変更分。

加えて Web-API が提供されており、こちらは利用に申請が必要です。

差分データには公開期限があります

ここが自前で取り込む場合に最も注意すべき点です。

差分ファイルは直近 40 営業日分だけが公開されています。 常に 40 ファイルが並んでおり、古いものから順に消えていきます。一度公開期間を過ぎたファイルは、国税庁からも他のどこからも取得できません。

つまり、取り込みが 2 か月止まっていたことに後から気づいても、その期間の差分ファイルはもう取得できません。全件データを取り直せば現在の状態は復旧し、個別の法人の履歴は国税庁に照会できますが、その期間に登録簿全体で何が変わったのかは、保持していなければ再構成できません。

日次のバッチが静かに落ちていて誰も気づかない、というのは珍しいことではありません。この設計では、それが取り返しのつかない結果になります。

自前で取り込む場合に詰まるところ

実際に運用してみると分かる点をいくつか挙げます。

ファイル ID は毎回変わります。 ダウンロードリンクに含まれる ID は公開のたびに再生成されるため、ハードコードできません。一覧ページから都度取得する必要があります。ファイル数もレジストリの成長に応じて変わります。

処理区分に未知のコードが現れます。 公表されている仕様に載っていないコードが実データに存在します。未知のコードで処理を中断する実装は、ある日突然止まります。かといって行を破棄すると、後から取得し直せないデータを失います。

削除を表す区分があります。 差分にのみ現れ、全件には現れません。これを「更新」として扱うと、取り消された登録をいつまでも有効として保持し続けることになります。そして全件から作り直したデータベースとは食い違うため、検算しないと気づきません。

メモリに乗りません。 全件ファイルは展開すると 1 GB を超えます。素直にメモリへ読み込む実装は落ちます。

API を使うべきかどうかの判断

自前で取り込むほうが合理的なのは、次のような場合です。

• 全件データを一度取り込めば足りる（変更履歴が不要）
• 日次バッチを確実に運用し、失敗を検知する体制がある
• データを外部に出せない事情がある

API を使うほうが合理的なのは、次のような場合です。

• 「いつ変わったか」が必要
• 特定の法人の変更を検知したい
• 日次バッチの運用そのものを持ちたくない

Daichodo の場合

curl https://api.daichodo.com/v1/corporations/8000000000001 \
  -H "Authorization: Bearer dc_test_..."

差分は毎営業日取り込んでおり、公開されたものは保持しています。特定の番号を登録しておけば、変更があった時点で Webhook をお送りします（変更検知は Standard プラン以上）。

よくある質問