取引先のインボイス番号API照会結果をマスタに残す項目— ステータス・スナップショット・失敗時ルール

1. マスタ本体に残す必須フィールド

1-1. 識別と照会メタデータ

最低限、取引先ID、登録番号（T+13桁）、照会実施日時（UTC+9で統一）、照会実行者（ユーザーIDまたはバッチ名）、照会チャネル（API／手動／一括CSV）を残します。
APIレスポンスのリクエストIDやHTTPステータスも別列に置くと、障害切り分けが速くなります。

1-2. ステータスと有効期間

照会結果ステータスは「有効」「失効」「該当なし」「照会不能」の4値以上に分け、APIが返す登録日・失効日・取消日を原文のまま保存します。
表示用の「現在判定」列は計算列にし、履歴行を上書きしない設計にします。
失効後も番号欄が残っている取引先は、登録取消後の継続取引の扱いとセットでレビューします。

1-3. レスポンスハッシュと原文スナップショット

JSON全文を毎回保存すると肥大化するため、正規化したレスポンスのSHA-256ハッシュと、事業者名・所在地・処理年月日など監査で見る項目だけのスナップショットJSONを分けます。
争いが起きた案件だけ全文をオブジェクトストレージへ退避する二段構えが現実的です。

2. 発注・支払時点のスナップショット

2-1. 発注確定時

発注番号ごとに「発注確定日時」「その時点の照会ステータス」「照会日時」「ハッシュ値」を子テーブルへINSERTします。
マスタの最新値をコピーするのではなく、発注ボタン押下時に再照会した結果を優先する運用が安全です。
再照会を省略する場合は、マスタ最新照会が24時間以内であることをルール化し、超えたらブロックします。

2-2. 支払実行・支払データ出力時

支払バッチ起動時にも同型のスナップショット行を追加し、発注時からステータスが変わっていないか差分フラグを立てます。
差分ありの案件は経理承認キューへ回し、発注と支払の監査リンクで追跡できるようにします。

2-3. 記載要件との接続

適格請求書の記載事項チェックは、スナップショットの事業者名と請求書表記の一致も見ます。
表の項目定義は記載事項テンプレートと同じ列名に揃えると、台帳エクスポートが楽です。

3. 更新トリガーと頻度

3-1. イベント駆動

新規取引先登録、番号変更、休眠からの復活、発注確定、支払データ生成の5イベントで再照会を走らせます。
手動「再照会」ボタンは権限を限定し、理由コード必須にします。

3-2. 定期バッチ

直近90日以内に発注または支払があった取引先は週次、それ以外は月次で全件再照会する二段階がAPI負荷とリスクのバランスが取りやすいです。
失効が多い業種は週次対象の日数を120日に広げます。

3-3. マスタと台帳の役割分担

番号入力の初回確認手順は取引先登録時のインボイス番号確認を参照し、マスタは「最新」、台帳は「時点証跡」と役割を分けます。
トリカク（torikaku） では取引先単位の番号と発注行の紐づけを前提に設計しています。

4. 照会失敗・矛盾時のルール

4-1. リトライとサーキット

タイムアウトは指数バックオフで最大3回、HTTP 5xxは15分サーキットオープン後に再開します。
4xxはリトライせず「照会不能」で記録し、番号フォーマットエラーは入力画面へ戻します。

4-2. 発注・支払ブロック条件

ステータス「該当なし」「失効」は発注ブロック、「照会不能」は経理承認付き警告付き通過、の二段階が一般的です。
支払60日起算の案件では、無効番号のまま支払うと後追い調整が発生するため、支払期日60日の起算レビューと同じ週次会議で一覧化します。

4-3. 手動確認の証跡

API障害時に公表サイトを目視確認した場合は、スクリーンショットではなく確認日時・確認者・見えたステータス文字列を手動照会ログ表へ入力します。
後からAPI結果と突合し、一致すれば手動行を「補完済み」に更新します。

5. 項目一覧（実装チェック用）

マスタ最新行: vendor_id, invoice_reg_no, lookup_at, lookup_by, channel, api_request_id, http_status, status_code, reg_date, expire_date, cancel_date, name_snapshot, address_snapshot, response_hash, raw_archive_key。
発注スナップショット: po_id, snapshot_type=ORDER, snapshot_at, status_code, lookup_at, response_hash, diff_from_master_flag。
支払スナップショット: payment_batch_id, po_id, snapshot_type=PAY, 同上。
失敗行: error_code, retry_count, next_retry_at, blocked_po_ids。

コンプラ台帳側では発注コンプライアンスチェックリストの「適格請求書発行事業者確認」行と、上記 status_code を1対1でマッピングしておくと監査説明が短くなります。

6. 運用例：月次クローズとの整合

6-1. 月末時点のスナップショット

月次クローズ時に、有効ステータスの取引先だけを再照会し、月末23:59時点の status_code を月次スナップショット表へINSERTします。
決算説明で「月末時点で失効していた取引先がいたか」を即答できるようにするためです。

6-2. 経理締めとの突合

支払データ出力日と照会日が逆転している行、つまり照会より先に支払った行を例外レポートで毎月抽出します。
例外は必ず理由コード付きで解消し、解消しない行は次月も繰り越して可視化します。

6-3. バージョン管理

照会ロジックやブロック条件を変えるときは、仕様書合意版の管理と同様に版番号をマスタ設定に持たせ、旧版で確定した発注は旧ルールで説明できるようにします。

6-4. 取引先向け説明

失効検知後に取引先へ番号更新を依頼するとき、マスタに残した照会日時と status_code を根拠として提示できるよう、社外向け説明テンプレを用意します。
口頭だけの失効通知は、こちらの記録と食い違うと支払停止判断が遅れます。

よくある質問

Q. 毎回APIを叩かずマスタ最新で足りませんか

失効は日付境界で起きるため、発注から支払までにステータスが変わるケースがあります。
支払直前の再照会か、差分検知付きスナップショットがないと説明責任を果たせません。

Q. ハッシュだけ残してJSONは捨ててよいですか

日常運用はハッシュと要約JSONで足ります。
ただし争い案件では原文が必要になるため、一定期間のアーカイブ方針を文書化してください。

Q. 番号未登録の個人事業主はどう記録しますか

番号欄は空、status_code=NOT_APPLICABLE、理由=免税事業者等のコードを必須にします。
空欄と未照会を混同しないため、lookup_at も必ず入れます。

Q. 一括取込CSVの照会結果はどこに残しますか

取込バッチID単位のログ表を作り、行番号・vendor_id・結果・ハッシュを保存します。
マスタ本体は最新のみ更新し、取込ログは削除しない運用にします。

Q. 海外子会社経由の請求はAPI対象外ですか

日本の登録番号が付く請求のみAPI照会対象にし、それ以外は status_code=OUT_OF_SCOPE と明示します。
対象外を「照会不能」と混ぜるとブロックルールが誤作動します。

まとめ

• マスタは最新、発注・支払は時点スナップショットで履歴を上書きしない
• status・日付・ハッシュ・要約JSONの4層で証跡を軽量に保つ
• イベント駆動と定期バッチの二段階で失効を取りこぼさない
• 失敗時はリトライ上限とブロック条件を数値で固定する
• チェックリスト行と status_code を1対1マッピングする

注意

本記事は取適法・フリーランス新法に関する一般的な情報の整理であり、トリカク（torikaku） の機能説明を含みますが、法的助言ではありません。
個別の契約内容・取引実態については専門家にご確認ください。