PHPで公開法人データを扱うときの確認順序｜文字列・時点・集計定義を分ける

公開法人データを月次レポートに変換するとき、ファイルが読めることと、その内容を比較に使えることは別の確認です。日本語が正常に表示されていても、法人番号を数値へ変換していたり、対象月と取得日を混同していたりすると、後の照合で誤りが生じます。この記事では、PHPで小さな検証処理を作る際に、何をどの順序で確認するかを整理します。

以下のコードは読み取り専用の最小例です。特定サービスの実装ではなく、文字列とJSONの形式を確かめるための独立した例です。データベースへの更新、外部APIの呼び出し、認証情報の読み込みは含みません。

最初に確認する値を小さく固定する

形式検査を始めるときは、まず一つの値について何を確かめるかを固定します。たとえば法人番号なら、ここで扱うのは「13桁の数字を文字列として受け取れたか」だけです。名称の重複、所在地の変更、資料の集計結果までを一度に判定しようとすると、失敗の理由が分かりにくくなります。

小さな検証では、形式、対象期間、表示上の説明を別々の問いとしてメモします。「文字列の形は正しい」と「この数字を比較に使える」は、同じ結論ではありません。確認範囲を狭く書き出すだけでも、テストの結果を必要以上に解釈しない助けになります。

法人番号は表示名と分けて文字列として検証する

名称の全角・半角や空白を整える処理は検索に役立ちますが、名称を法人の識別子にしてはいけません。同名の法人があり、名称変更もあるためです。法人番号は文字列として扱い、入力の形式検査と同一性の照合を別の責務にします。

<?php
// PHP 5.6 compatible, read-only example.
function requireCorporateNumber($value)
{
    if (!is_string($value) || !preg_match('/^[0-9]{13}$/D', $value)) {
        throw new InvalidArgumentException('Invalid corporate-number format');
    }
    return $value;
}

function decodeUtf8Array($raw)
{
    $decoded = json_decode($raw, true);
    if (json_last_error() !== JSON_ERROR_NONE || !is_array($decoded)) {
        throw new RuntimeException('Invalid UTF-8 JSON container');
    }
    return $decoded;
}

この形式検査は、番号が実際に公表されているかを確認する処理ではありません。また、検査数字の検証も行っていません。長さと文字種が正しいことだけを示します。関数名と説明を狭く保つことで、「形式が正しい」と「実在する法人を確認した」を混同しない設計にできます。CSVを読む場合も、読み取った値を安易に整数へ変換せず、元の文字列を検証へ渡します。

JSONについては、PHP公式のjson_decode説明にも、UTF-8文字列を対象とすることが記載されています。この例はJSONの配列またはオブジェクトをPHPの配列として受け取り、スカラー値は拒否します。項目名や必要な列の検証は、この関数の後に別の処理として加える必要があります。

日本語の見た目と検索用の比較を混同しない

文字化けや表記ゆれを確認するときは、表示された文字列と検索時に比べる文字列を混同しないことが大切です。文字コードを確認せずに複数回変換すると、正常だった文字列を壊す場合があります。テストでは、変換前後の短い合成文字列を並べ、期待した文字列かを直接確かめます。

検索用に空白や法人種別を調整するときも、その値を公式商号として表示してはいけません。画面には確認済みの原表記を使い、検索用の値は候補の発見に使います。照合の最終段階では番号、所在地、確認時点へ戻ります。表示と検索の責務を分けると、検索改善のための処理が、引用する名称を意図せず変える事故を防げます。

対象月と参照日を別に読む

九月分の資料を十月に読むことは自然です。対象月とページを参照した日を同じ「更新日」として扱うと、数字が表す期間が分からなくなります。比較メモでは、この二つを別に書きます。

たとえばHoujinbaseの月次レポートを比較するときは、URLの月だけでなく、ページに書かれた集計定義と集計時点も確認します。指定日を基準にした集計と、公開された変更イベントの集計では、同じ期間でも対象が一致するとは限りません。

検証は形式・比較条件・表示の三段階に分ける

段階	確認すること	その確認だけでは分からないこと
形式	文字列の型、文字コード、必要な項目	数字の比較条件
比較条件	対象期間、数える対象、地域の基準	公開ページの表示状態
表示	対象月、値、定義、参照先	公開資料に後日訂正がないこと

表示確認はページが開くことだけで終えません。対象月と定義を読み、地域のページでは対象地域の値と説明を確認します。全国のページが読めたことから、地域別の意味まで推測しないことが大切です。

合成テストで失敗の意味を確かめる

実在の法人情報を使わなくても、形式検査の境界は確かめられます。たとえば次のような合成ケースを用意すると、関数が何を受け入れ、何を拒否するかを説明しやすくなります。

合成ケース	期待する結果	分かること
"1234567890123"	形式検査を通る	13桁の文字列を受け取る
"123456789012"	例外になる	桁数が不足している
1234567890123	例外になる	数字ではなく文字列を求めている
[]	JSONの配列として読める	JSONコンテナの形式だけを確かめる

失敗した場合は、文字列の型、桁数、JSONの形、比較条件のどこで止まったかを短く記録します。実在の法人一覧や認証情報を丸ごと残す必要はありません。形式検査に通ったことを、資料内容の正しさや実在確認の結果として扱わないことも重要です。

出典とこの例の限界

公開データの項目や提供方法は、国税庁法人番号公表サイトで確認してください。上のコードは入力の一部を確認する例であり、公式仕様への完全な適合、法人の実在、取り込み完了を保証しません。法人データレポート一覧は表示確認の参照例として使えますが、個別の契約や登記内容の判断には目的に合う一次情報が必要です。

まず粒度と時点をそろえ、原文を残し、識別子で照合する。そのうえで入力、集計、表示の結果を別々に確認することが、小さな検証コードを実務で役立てるための基本になります。