適格請求書発行事業者のWeb-APIをClaude Codeで呼ぶ — 登録番号を一括照合

取引先から届いた請求書の登録番号(T+13桁)が本物かどうかは、国税庁の適格請求書発行事業者公表システムで確かめられます。1件ずつブラウザで検索するなら数分で済みますが、取引先が数十社を超えると手が止まります。商号や所在地のずれを法人番号で洗い出すなら、法人番号Web-APIで取引先名簿を名寄せする手順が別の仕組みを扱っています。請求書PDFの記載事項が揃っているかは、適格請求書の記載事項をClaudeで点検する手順にあります。

公表システムにはWeb-API機能があり、登録番号を最大10件ずつ渡して判定に必要な情報を取得できます。呼び出すスクリプトはClaude Codeに書かせるのが早いです。ただし、アプリケーションIDの管理と利用規約には気をつける点があります。ここでは、IDの取得から、スクリプトの検証、結果の読み方までを順に扱います。政府統計のAPIで同じ流れを試すならe-Stat APIをClaude Codeで呼ぶ手順があります。

アプリケーションIDの発行手順と、取得後に守る規約

Web-APIの利用には「アプリケーションID」が要ります。発行は無料です。インボイスの登録番号を引くには「インボイス用」のIDが必要で、法人番号システムWeb-API用のIDだけでは足りません。法人番号用IDにインボイスWeb-APIの利用権限を加える手続きも用意されています。

手続きは2026年9月21日施行の規約改正で簡素になりました。改正前の第3条は、届出のあとに「発行申請書」を国税庁へメールで提出するよう定めていましたが、新旧対照表のとおり、改正後はこの条項が削除されています。規約では発行申請書の提出が削除された一方、Web-APIのトップページは本登録の段階で「公表情報の取得方法及び利用方法」が分かる資料の提出を案内しています。フォームで資料を求められたら、用意して添えます。

IDを取ったあとは、利用規約が運用の前提になります。スクリプトの作りに直結する条項を、改正後の条番号で並べます。

規約には1分あたりの上限回数のような数値がありません。数値がないぶん、スクリプト側で間隔を空ける作りにします。

IDの登録情報(法人名・氏名・メールアドレス・電話番号など)が変わったときは、公表サイトの変更届出から変更を届け出ます。使うのをやめるときは「アプリケーションID停止届出」です。停止届出は、IDと登録済みのメールアドレスを送ると届くメールのURLから、停止届出フォームに進む流れです。

3つのエンドポイントと、リクエストの形

公表システムのWeb-APIは、REST方式です。機能は3つあり、請求書の番号照合で主に使うのは1と3です。

先頭の 1 はバージョンで、半角の「1」を指定します。本番のホストは web-api.invoice-kohyo.nta.go.jp です。

登録番号は T に13桁の数字を続けた形で、カンマ区切りで最大10件まで渡せます。type は応答形式で、01 がCSV、11 がXML、21 がJSONです。文字コードはUnicodeです。

/num では、履歴情報を含めるかを history で選べます。省略すると 0(履歴なし)として扱われ、リクエスト時点の最新情報だけが返ります。1 にすると過去の履歴も返り、各レコードの latest が 1(最新情報)か 0(過去情報)かで見分けます。

/valid は、指定した基準日を境にした、直近の登録年月日・取消年月日・失効年月日に紐づく情報を返します。基準日に有効だったかを、取引日ごとに引ける機能です。

呼び出しの例は次のとおりです。番号は仕様書の応答例に出てくるもので、事業者名は架空です。

curl -s "https://web-api.invoice-kohyo.nta.go.jp/1/num\
?id=$INVOICE_APP_ID&number=T8040001999011&type=21&history=0"

応答のJSONは、ヘッダ情報(lastUpdateDate / count / divideNumber / divideSize)と、announcement 配列に入る公表情報でできています。仕様書のサンプルでは、公表情報に registratedNumber(登録番号)、process(事業者処理区分)、kind(人格区分)、registrationDate(登録年月日)、disposalDate(取消年月日)、expireDate(失効年月日)、name(氏名又は名称)などが並びます。項目名の綴りは仕様書のとおり registratedNumber で、registered ではありません。

process は、01が新規、02が公表内容の変更、03が登録の失効、04が登録の取消です。99(登録簿からの削除)は差分データのダウンロードファイルにだけあり、Web-APIの応答には作られません。

Claude Codeに渡す前提を先に決める

スクリプトを頼む前に、Claude Code側で3つを決めておきます。

アプリケーションIDはコードにも会話にも書かない

IDは .env に INVOICE_APP_ID=... の1行で置き、スクリプトに読ませます。そのうえで、Claude Codeの読み取りを拒否する権限ルールを設定します。公式ドキュメントに、Read(./.env) のようなパスを指定する形の例があります。

{
  "permissions": {
    "deny": ["Read(./.env)"],
    "allow": ["Bash(python3 check_invoice.py *)"]
  }
}

この組み合わせが成り立つのは、拒否ルールの効く範囲が決まっているからです。Read の拒否は、Claude Codeの組み込みのファイルツールと、Bashのうち cat や head のような認識済みのファイルコマンドに効きます。一方、PythonやNodeのスクリプトが自分でファイルを開く場合は対象外です。cat のようにファイル名を指定した読み取りは塞げますが、スクリプト経由の読み取りは防げません。厳密に防ぐなら、サンドボックスを有効にします。

環境変数に export したIDは、同じシェルから起動したClaude Codeにも引き継がれます。echo は確認なしで通る読み取り専用コマンドの1つなので、値を会話に出させる経路が残ります。.env に置いてスクリプトが直接読む形にすると、この経路を避けられます。

allow の書き方は、公式の Bash(npm run *) と同じ形です。ただし公式は、Bashの権限パターンで引数を絞る書き方は壊れやすいと注意しています。許可はスクリプト名のレベルにとどめ、権限の全体像は/permissionsコマンドで権限ルールを管理する手順で確認してください。

仕様の要点をCLAUDE.mdに固定する

CLAUDE.mdは、毎セッションの開始時にコンテキストへ読み込まれます。公式は「検証できるほど具体的に書く」ことを勧めています。Web-APIの制約は次のように書けます。

## 適格請求書 Web-API
- ホストは web-api.invoice-kohyo.nta.go.jp(検証時は kensyo.invoice-kohyo.nta.go.jp)
- 1リクエストの登録番号は最大10件。カンマ区切り
- アプリケーションIDは .env の INVOICE_APP_ID から読む。コード・ログ・会話に出さない
- リクエスト間は1秒以上空ける(規約: 短時間の大量アクセス禁止)
- 確認の順序はローカルのスタブ、検証環境、本番。本番は tests が通ってから

書き方の型は、Excel VBAをCLAUDE.mdで規約化する記事と同じです。長くなるなら、CLAUDE.mdの構成はCLAUDE.mdの書き方パターンを参考にしてください。公式は1ファイル200行未満を目安にしています。

入力と出力の形を決める

入力は、取引先,登録番号 の2列のCSVにします。出力は、判定と公表上の名称を足した別のCSVです。元のCSVは上書きさせません。

一括照合スクリプトをClaude Codeに書かせる

指示は、仕様の中身ではなく成果物の形で伝えます。

invoices.csv(取引先,登録番号)の登録番号を、国税庁のWeb-API(/1/num、JSON)で
照合する check_invoice.py を書いて。CLAUDE.md の制約を守ること。
出力は結果CSV。形式エラー・公表情報なし・取消・失効を区別して。

書き上がったコードの主要部は、次のような形になります(公式仕様の項目名に沿って組んだ例で、Claudeの出力そのものではありません)。

NUMBER_RE = re.compile(r"^T\d{13}$")
CHUNK = 10  # 1リクエストの登録番号は最大10件
 
def fetch(app_id, numbers, day=None):
    params = {"id": app_id, "number": ",".join(numbers), "type": "21"}
    if day:
        endpoint, params["day"] = "valid", day
    else:
        endpoint, params["history"] = "num", "0"
    url = f"{BASE}/1/{endpoint}?{urllib.parse.urlencode(params, safe=',')}"
    with urllib.request.urlopen(url, timeout=30) as res:
        return json.load(res).get("announcement", [])
 
def judge(rec):
    if rec.get("disposalDate"):
        return f"取消({rec['disposalDate']})"
    if rec.get("expireDate"):
        return f"失効({rec['expireDate']})"
    return "登録中"

import argparse, csv, json, os, re, sys, time
import unicodedata, urllib.error, urllib.parse, urllib.request
 
BASE = os.environ.get("INVOICE_API_BASE", "https://web-api.invoice-kohyo.nta.go.jp")
NUMBER_RE = re.compile(r"^T\d{13}$")
CHUNK = 10  # 1リクエストの登録番号は最大10件
 
def fetch(app_id, numbers, day=None):
    params = {"id": app_id, "number": ",".join(numbers), "type": "21"}
    if day:
        endpoint, params["day"] = "valid", day
    else:
        endpoint, params["history"] = "num", "0"
    url = f"{BASE}/1/{endpoint}?{urllib.parse.urlencode(params, safe=',')}"
    with urllib.request.urlopen(url, timeout=30) as res:
        return json.load(res).get("announcement", [])
 
def judge(rec):
    if rec.get("disposalDate"):
        return f"取消({rec['disposalDate']})"
    if rec.get("expireDate"):
        return f"失効({rec['expireDate']})"
    return "登録中"
 
def norm(name):
    s = unicodedata.normalize("NFKC", name)  # 全角半角を統一
    s = re.sub(r"株式会社|有限会社|合同会社|\(株\)|\(有\)", "", s)  # 前株・後株を吸収
    return re.sub(r"\s+", "", s)
 
def load_app_id():
    """環境変数を優先し、無ければ .env の INVOICE_APP_ID を読む"""
    if os.environ.get("INVOICE_APP_ID"):
        return os.environ["INVOICE_APP_ID"]
    if os.path.exists(".env"):
        for line in open(".env", encoding="utf-8"):
            key, _, value = line.strip().partition("=")
            if key == "INVOICE_APP_ID":
                return value.strip("\"'")
    sys.exit("INVOICE_APP_ID が環境変数にも .env にもありません")
 
def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("src")
    ap.add_argument("dst")
    ap.add_argument("--day", help="基準日 YYYY-MM-DD(/valid を使う)")
    args = ap.parse_args()
    app_id = load_app_id()  # コードにも会話にも書かない
 
    with open(args.src, newline="", encoding="utf-8") as f:
        rows = list(csv.DictReader(f))  # 列: 取引先,登録番号
 
    valid = sorted({r["登録番号"] for r in rows if NUMBER_RE.match(r["登録番号"])})
    found = {}
    for i in range(0, len(valid), CHUNK):
        try:
            for rec in fetch(app_id, valid[i:i + CHUNK], args.day):
                found[rec["registratedNumber"]] = rec
        except urllib.error.HTTPError as e:
            print(e.read().decode())  # エラー本文はCSV形式で返る
            sys.exit(1)
        except urllib.error.URLError as e:
            print(f"接続できません: {e.reason}")
            sys.exit(1)
        time.sleep(1)  # リクエスト間隔を空ける
 
    with open(args.dst, "w", newline="", encoding="utf-8") as f:
        w = csv.writer(f)
        w.writerow(["取引先", "登録番号", "判定", "公表上の名称"])
        for r in rows:
            num = r["登録番号"]
            if not NUMBER_RE.match(num):
                w.writerow([r["取引先"], num, "形式エラー", ""])
            elif num not in found:
                w.writerow([r["取引先"], num, "公表情報なし", ""])
            else:
                rec = found[num]
                result = judge(rec)
                if norm(rec.get("name", "")) != norm(r["取引先"]):
                    result += " / 要確認(名称不一致)"
                w.writerow([r["取引先"], num, result, rec.get("name", "")])
 
if __name__ == "__main__":
    main()

呼び出し側では、番号を10件ずつに区切り、区切りごとに1秒待ちます。safe=',' を付けるのは、番号の区切りのカンマがURLエンコードされないようにするためです。IDは環境変数があればそれを、なければ .env から読みます。金融庁のEDINET APIで有価証券報告書を取得する組み方は、EDINET APIの比較手順で扱っています。

--day を付けると、/valid で基準日時点の状態を引きます。請求書の取引日を渡せば、「その日に登録があったか」を確かめられます。

python3 check_invoice.py invoices.csv result.csv --day 2026-08-31

本番に送る前に、確認を3段階に分ける

スクリプトを書く段階では、IDが手元にないことがあります。IDの有無と、国税庁へ実際に送るかどうかで、確かめられることが変わります。

スタブで判定ロジックを固める

スタブは、環境変数 INVOICE_API_BASE で向け先を差し替えるだけで使えます。仕様書の応答の形(count と announcement)で、登録中・取消・失効の3件だけを返す小さなサーバーです。

import json
from http.server import BaseHTTPRequestHandler,HTTPServer
from urllib.parse import urlparse,parse_qs
DATA={
 "T8040001999011":{"registratedNumber":"T8040001999011","process":"01","kind":"2","registrationDate":"2023-10-01","disposalDate":"","expireDate":"","name":"株式会社インボイス公表"},
 "T8040001999012":{"registratedNumber":"T8040001999012","process":"04","kind":"2","registrationDate":"2023-10-01","disposalDate":"2025-03-31","expireDate":"","name":"株式会社インボイス登録"},
 "T1234567890123":{"registratedNumber":"T1234567890123","process":"03","kind":"1","registrationDate":"2023-10-01","disposalDate":"","expireDate":"2026-01-15","name":"山田 太郎"},
}
class H(BaseHTTPRequestHandler):
    def do_GET(self):
        u=urlparse(self.path);q=parse_qs(u.query)
        nums=q.get("number",[""])[0].split(",")
        if len(nums)>10:
            self.send_response(400);self.end_headers();self.wfile.write("0002,登録番号は10件以内で指定してください。".encode());return
        ann=[DATA[n] for n in nums if n in DATA]
        body=json.dumps({"lastUpdateDate":"2026-10-01","count":str(len(ann)),"divideNumber":"1","divideSize":"1","announcement":ann},ensure_ascii=False).encode()
        self.send_response(200);self.send_header("Content-Type","application/json");self.end_headers();self.wfile.write(body)
    def log_message(self,*a):pass
HTTPServer(("127.0.0.1",18765),H).serve_forever()

python3 stub.py &
INVOICE_APP_ID=dummy INVOICE_API_BASE=http://127.0.0.1:18765 \
  python3 check_invoice.py invoices.csv result.csv
cat result.csv

登録中・取消・失効・存在しない番号・形式エラーを1件ずつ入れた invoices.csv で流すと、次の結果になります(Python 3.12で実行した出力です)。

取引先,登録番号,判定,公表上の名称
インボイス公表(株),T8040001999011,登録中,株式会社インボイス公表
株式会社インボイス登録,T8040001999012,取消(2025-03-31),株式会社インボイス登録
山田太郎,T1234567890123,失効(2026-01-15),山田 太郎
存在しない商事,T9999999999999,公表情報なし,
番号ミス商店,T123,形式エラー,

名称の比較には落とし穴があります。取引先名が後株の インボイス公表(株) のとき、(株) を株式会社に置き換えるだけの正規化では、前株の公表名称 株式会社インボイス公表 と一致せず、要確認が付きました。全体コードの norm が法人格の表記ごと取り除くのは、この結果を受けた修正です。

スタブが返す応答は自分で書いたものなので、国税庁側の挙動の証明にはなりません。確かめられるのは、スクリプトが仕様の項目名どおりに読み、分岐を取りこぼさないかどうかです。ClaudeにスタブとテストをCLAUDE.mdの方針で書かせ、pytest などで回せる形にしておけば、判定ロジックを直すたびに同じ確認を繰り返せます。

検証環境で先に動かす

IDが届いたら、検証環境で挙動を確かめます。リクエストのフォーマットは本番とは別に定められており、URLも次のとおり異なります。

バージョンと条件は本番と同じです。スクリプトのホストは、スタブと同じく環境変数 INVOICE_API_BASE で切り替えられます。

INVOICE_API_BASE=https://kensyo.invoice-kohyo.nta.go.jp \
  python3 check_invoice.py sample.csv result.csv

ここでClaude Codeに実行させ、出力を読ませます。「result.csvを見て、判定が仕様書の登録・取消・失効のどれに当たるか確認して」と頼めば、コードの修正まで一続きで回せます。検証環境にも、本番と同じ利用規約と個人情報の保護方針が適用されます。サンプルデータは、登録番号を活用するシステムの開発・改修以外の用途に使わず、第三者に貸与・譲渡しないよう求められています。

検証環境には、もう1つ注意があります。Webブラウザ経由でWeb-APIを使うと、取得したデータが表示できないことがあります。Javaやスクリプトなどのプログラムからのリクエストではこの事象は起きないとされています。動作確認はcurlかスクリプトで行います。

結果の読み方

judge の判定は、disposalDate(取消年月日)と expireDate(失効年月日)が空かどうかで決まります。

「公表情報なし」は、次の理解にもとづく扱いです。仕様書は count を「指定した条件に合致したデータの総件数」と定義しており、公表されていない番号は応答に現れないはずです。仕様書の応答サンプルは、いずれも該当データがあるケースです。検証環境で存在しない番号を1件混ぜ、同じ動きになるかを見ておくと確実です。応答に現れない番号には、入力の誤りのほか、登録簿から削除された番号も含まれることがあるため、この行は「取引先に番号を再確認する」合図として扱います。

形式エラーは、リクエストを送る前に弾きます。10件を超えるとエラーコード0002、14桁でない番号は0004、T+13桁の形でない番号は0005が返るため、送信前の検査で余計なリクエストを減らせます。

もう1つの見どころは名称の照合です。公表システムの name と、請求書の取引先名が違えば、番号の書き間違いや別法人の可能性があります。全体コードの norm で表記を揃えて比較し、一致しなければ「要確認」を付けて、人が見ます。

名称の一致判定をどこまで厳しくするかは、法人か個人事業者かで変わります。

個人は名称の一致判定を緩め、「要確認」の行を人が見る前提にします。

つまずきやすいエラー

エラー時は、HTTPステータスに加えて、エラーコードとメッセージがCSV形式で返ります。JSONで頼んでも、エラー本文はJSONではない点が落とし穴です。全体コードが HTTPError の本文をそのまま表示するのは、これが理由です。

/diff は、取得期間の開始日と終了日の間が50日を超えると0205のエラーになります。開始日は2021年10月1日以降しか指定できません。データが500件を超えるときは、応答が分割され、divideNumber と divideSize が一致するまで分割番号を指定して追加リクエストを送る決まりです。番号照合では1リクエストが最大10件なので、通常は分割が起きません。

結果を社内システムや公開サービスに載せるとき

利用規約の第6条は、本機能を利用したサービスを提供する場合に、次の文言を適宜の場所へ明示するよう求めています。社内の経理チェックのように、利用者へ提供するサービスを伴わない使い方は、この条文の文言上は対象に見えません。

このサービスは、適格請求書発行事業者公表システムWeb-API機能を利用して取得した情報をもとに作成しているが、サービスの内容は国税庁によって保証されたものではない

表示場所の指定はありません。Claude Codeで作るツールを他社に配るときは、この一文をREADMEか画面に入れておきます。配るツールにIDを同梱することはできません(第9条でIDの譲渡・開示を禁じています)。利用する会社ごとに、その会社が国税庁からIDを取る形になります。

取得した情報の扱いにも配慮が要ります。第9条は、取得した公表情報を、公表サイトの運営方針が定める目的以外のために第三者へ提供することを禁じています。第4条の2は、取得した情報を個人情報保護法などに基づいて管理するよう定め、第12条は漏えいや改ざんを防ぐ措置を求めています。個人事業者の氏名を含む結果を名簿として蓄積する前に、これらの条文と個人情報の保護方針を読み直してください。

自分の側の登録手続きは、別の記事にまとめています。Claudeで開業届・青色申告・インボイス登録を整理する方法を参照してください。Claude自体のサービス料金の請求書にある登録番号や消費税の扱いは、請求先住所と税金計算の解説にあります。

まとめ

IDの扱いと規約の2点(IDを会話に出さない、リクエストの間隔を空ける)が運用の分かれ目で、判定ロジックはIDが届く前でも、スタブで固められます。照合の結果は、取引先の状態が変われば変わります。月次の締めごとにスクリプトを回し、結果のCSVを日付つきで残しておけば、後から「その時点でどう見えていたか」を追えます。