反社チェックAPIの連携実装｜登録時の同期呼び出しとバッチ、同姓同名を減らす照合キーと判定ログ【2026年】

反社チェックAPIの連携は、ベンダーの照会結果を取引先マスタやCRMの登録処理に組み込む開発です。この記事では、取引先登録時の同期呼び出しと夜間バッチの分け方、タイムアウト時に「保留」へ倒す状態設計、法人番号の検査用数字とNFKC正規化で作る照合キー、同姓同名の誤ヒットを生年月日と所在地で絞る手順、そして後から監査に耐える追記専用の判定ログまでを、動作確認したコード付きで解説します。ツールの選び方や連携すべきかの判断は反社チェックツール比較：4タイプの選び分けと料金の計算、取引先マスタ連携の判断で扱っており、本稿はその先の実装に絞ります。

まとめ：反社チェックAPI連携は判定をAPIに任せず、照合キーと記録を自社で設計する

ベンダーの反社APIが返すのは、ヒット件数と情報区分、記事や情報の中身です。取引してよいかの結論は返ってきません。連携開発の中心は、APIを呼ぶ部分ではなく、その前後にあります。

前は照合キーです。法人は法人番号13桁を主キーにし、社名は表記ゆれを正規化してから送ります。個人の照会に必ず添えるのは、生年月日と都道府県です。ここが雑だと同姓同名のヒットが増え、確認作業が手作業に戻ります。

後ろは状態と記録です。登録時の照会は数秒で打ち切り、失敗したら承認ではなく保留にします。照会1回ごとの検索語・日時・応答原文・判定者は追記専用のテーブルに残し、更新も削除もさせません。月に数十社しか登録しない会社なら、連携せずにツール画面とCSVで回す方が安く済みます。

反社チェックAPIが返す情報の範囲と、連携で自社システム側が作る部分の切り分け

実装に入る前に、ベンダーのAPIに任せられる部分と、自社で作るしかない部分を分けておきます。この線引きを誤ると、APIを入れたのに確認の手間が減らない結果になります。

ベンダーの反社APIが返すのはヒット件数と情報区分で、取引可否の判定ではない

リスクモンスターの2026年6月22日の公式リリースでは、法人向けの反社APIが「反社警戒、事件事故、訴訟問題、行政処分」の4つの情報区分を持ち、新設の反社個人APIは個人の反社警戒・事件事故情報のヒット件数と内容、記事検索情報のヒット件数を返すと説明されています。記事検索型のRISK EYESも、公式サイトで業務システムと連携して結果を表示できる旨を案内しています。

どちらも返すのは「何件、どんな情報に当たったか」です。ヒットした記事の人物が取引先の代表者本人かどうかは、API側では決まりません。

したがって自社側で作るのは、照会に送るキーの組み立て、応答を受けた後の状態の振り分け、人が確認した結果の記録の3つです。法務省の企業が反社会的勢力による被害を防止するための指針が求めるのは関係遮断の体制であり、照会したという事実だけでは足りません。判定の根拠を後から示せる記録まで含めて1つの仕組みとして設計します。

契約前にベンダーへ確認する仕様、認証・同時実行数・課金単位・応答の保存可否

反社APIの詳細仕様は、多くのベンダーが契約者向けにだけ開示しています。公開ページで分かるのは連携できるという事実までなので、設計に入る前に次の項目を仕様書で確かめます。

実務で最初に効くのは課金単位と応答の保存条件の2つです。媒体ごとに課金される契約で同じ取引先を何度も照会すると、費用がそのまま膨らみます。記事本文の保存が規約で禁じられていれば、判定ログには記事IDとヒット件数だけを残し、原文はベンダー画面で見る設計に変わります。

法人番号Web-APIで取れる公開情報と、反社データベースに任せる情報の役割分担

取引先の実在確認と、商号や所在地の変更の検知は、反社APIではなく国税庁の法人番号システムWeb-APIで賄えます。利用には無料のアプリケーションIDの発行が必要で、2026年11月時点で掲載されている最新の仕様はVer.4.0系です。機能は法人番号指定、取得期間指定(差分)、法人名指定の3種類があります。

役割はこう分けます。法人番号Web-APIは「その会社が実在し、いまの商号と所在地は何か」を答える台帳です。反社APIは「その会社や代表者が反社会的勢力や事件報道と結び付くか」を答えます。社名だけで反社APIを照会した場合に生じるのは、旧商号で報じられた記事の取りこぼしです。法人番号で最新の商号を引いてから照会に回す順序にすると、この漏れを防げます。

インボイスの登録番号と法人番号の関係で迷う場合は、インボイス登録番号と法人番号の違いで整理しています。

取引先登録時の同期呼び出しと夜間バッチ、2つの連携方式を組み合わせる実装

反社チェックの自動化は、新規登録の瞬間に1社ずつ照会する同期呼び出しと、既存取引先をまとめて再照会するバッチの組み合わせで組みます。どちらか片方だけでは、新規の取りこぼしか再チェック漏れのどちらかが残ります。

登録時の同期呼び出しは数秒で打ち切り、失敗時は承認でなく保留へ倒す設計

取引先登録画面から反社APIを呼ぶとき、応答を無制限に待つと登録画面が固まります。タイムアウトはベンダーが示す応答時間の目安に余裕を足した値、たとえば3秒から5秒程度に置き、超えたら処理を止めずに結果を「保留」として登録を先に進めます。

ここで絶対に避けたいのが、タイムアウトや通信エラーを「該当なし」と同じ扱いにする実装です。API障害の時間帯に登録された取引先が、照会されないまま承認済みになります。判定の振り分けは次のように、取れなかった結果を必ず保留へ寄せます。

def decide_on_register(hit_count, timed_out):
    # 照会結果から取引先の状態を決める。取れなかった結果は必ず保留へ寄せる
    if timed_out or hit_count is None:
        return "保留"      # 夜間バッチで再照会する
    if hit_count == 0:
        return "該当なし"  # 承認フローへ進めてよい
    return "要確認"        # 担当者が中身を見て判定する


print(decide_on_register(None, True))   # 保留
print(decide_on_register(0, False))     # 該当なし
print(decide_on_register(2, False))     # 要確認

保留になった取引先は、次の夜間バッチで自動的に再照会の対象に入れます。保留のまま受注や支払に進めない制御は、後述の状態遷移で受け持ちます。

夜間バッチは再チェック期限の到来分と法人番号の変更検知分だけに対象を絞る

既存取引先の再チェックを全件で毎晩回すと、照会課金と回数制限の両方に当たります。対象は3つに絞ります。登録時に保留になった取引先、取引先マスタの再チェック期限が到来した取引先、そして法人番号Web-APIの取得期間指定で前回以降に商号・所在地・代表情報の変更や閉鎖が見つかった取引先です。

変更検知を挟む理由は、商号変更や本店移転の直後に照会し直すと、旧商号と新商号の両方で報道を拾えるためです。期間指定の条件の付け方や応答項目は、国税庁が公開しているVer.4.0のリクエスト設定方法の仕様書で確かめてから実装してください。

ベンダーの回数制限が1日あたりで決まっている場合は、対象件数を上限で割ってバッチを複数夜に分け、期限の古い順に処理します。1晩で終わらなかった分を翌晩へ繰り越すだけの単純な待ち行列で十分に回ります。

未照会・保留・要確認・承認・却下の5状態と、受注や支払を止める位置の決め方

取引先マスタには、照会の状態を次の5つで持たせます。状態ごとに、どの業務を止めるかを先に決めておくと、例外の扱いで現場が迷いません。

止める位置は契約と支払の2か所が基本です。見積の段階で止めると営業が登録自体を後回しにし、照会のタイミングがかえって遅れます。登録は早く、契約と支払の手前で確実に止める配置が運用に乗りやすい形です。承認から一定期間が過ぎた取引先は、自動で再チェック対象に戻します。

同姓同名の誤ヒットを減らす照合キー設計、法人番号・生年月日・所在地の組み合わせ

反社チェックで確認の手間が膨らむ最大の原因は、同姓同名や同名の別会社のヒットです。照会に送るキーを整えるほど、人が見るべきヒットは減ります。

法人は法人番号13桁を主キーにし、検査用数字の計算で入力誤りを登録前に弾く

法人番号は12桁の基礎番号と、その前に付いた1桁の検査用数字でできています。構成は番号法施行令35条、検査用数字の算式は法人番号の指定等に関する省令2条が定めており、基礎番号の最下位の桁を1桁目として、奇数桁は1倍、偶数桁は2倍した合計を9で割った余りを9から引いた数が検査用数字になります。

import re


def is_valid_corporate_number(number):
    # 13桁の数字であり、先頭1桁が検査用数字として正しいかを確かめる
    if not re.fullmatch(r"[0-9]{13}", number):
        return False
    check_digit, base = int(number[0]), number[1:]
    # 基礎番号12桁を最下位の桁から数え、奇数桁は1倍・偶数桁は2倍して合計する
    total = sum(
        int(d) * (1 if n % 2 == 1 else 2)
        for n, d in enumerate(reversed(base), start=1)
    )
    return check_digit == 9 - total % 9


print(is_valid_corporate_number("7000012050002"))  # True
print(is_valid_corporate_number("7000012050003"))  # False(末尾の打ち間違い)
print(is_valid_corporate_number("700001205000"))   # False(12桁しかない)

登録画面でこの検証を通してから法人番号Web-APIで商号を引き、一致した法人番号を取引先マスタの照合キーにします。手入力の打ち間違いで別会社を照会し、「該当なし」で承認してしまう事故を入口で防げます。

社名の表記ゆれはNFKC正規化と法人格の除去で照合用キーにそろえてから送る

法人番号を持たない取引先や、代表者名・旧商号での照会では、文字列の揺れをそろえる処理が必要です。Pythonのunicodedata.normalizeでNFKCを指定すると、全角英数は半角に、半角カナは全角に、「㈱」のような合字は「(株)」に変わります。そのうえで空白と法人格を取り除けば、表記の違う同じ社名が1つのキーにまとまります。

import re
import unicodedata

CORP_FORMS = ["株式会社", "有限会社", "合同会社", "合資会社", "合名会社",
              "一般社団法人", "一般財団法人", "(株)", "(有)", "(同)"]


def corp_match_key(name):
    # 全角英数・半角カナ・合字をNFKCでそろえ、空白と法人格を除いて照合用キーにする
    s = unicodedata.normalize("NFKC", name)
    s = re.sub(r"\s+", "", s)
    for form in CORP_FORMS:
        s = s.replace(form, "")
    return s.upper()


print(corp_match_key("㈱ＡＢＣ ﾎｰﾙﾃﾞｨﾝｸﾞｽ"))      # ABCホールディングス
print(corp_match_key("ABCホールディングス株式会社"))  # ABCホールディングス

このキーは自社側の重複登録の検出と、照会履歴の突き合わせに使います。ベンダーへ送る検索語そのものは、正規化前の正式名称と旧商号の両方にしてください。記事は正式名称で書かれるため、法人格を外した短い語で検索すると無関係な記事のヒットが増えます。振込名義のような半角カナの名寄せまで扱う場合は、入金消込の自動化を実装するで示した正規化と同じ部品を共有できます。

個人の同姓同名は生年月日と都道府県で絞り、残ったヒットを人が見る順番を決める

代表者や個人事業主の照会は、氏名だけでは同姓同名を避けられません。ベンダーの検索条件に生年や生年月日、所在地の指定があれば必ず送ります。指定できない場合でも、生年月日と都道府県は照会リクエストと一緒に自社の判定ログへ保存しておき、ヒットした記事の年齢や地域と担当者が突き合わせられるようにします。

確認の順番は固定します。まず記事中の年齢から算出した生年と、登録された生年月日を比べます。次に見るのは記事の地域と所在地の都道府県で、最後に確認するのは肩書きや社名の一致です。年齢が5歳以上離れていれば別人と判定してよい、といった社内基準を決めておくと、判定のばらつきが減ります。

別人と判定したヒットは、判定理由とともに記録し、次回の照会で同じ記事が出たときに再確認を省けるようにします。判定の基準そのものは、反社チェックとは？やり方4段階と判定基準で解説しています。

判定結果の保存と監査ログ、照会の記録を後から説明できる形で残すテーブル設計

監査や上場審査で問われるのは「いつ、誰を、何で調べ、どう判断したか」です。この4点が取引先マスタの最新値しか残っていないと、過去の判断を説明できません。

照会1回ごとに検索語・送信日時・API応答の原文・判定者を追記専用で残す

照会の記録と人の判定は、それぞれ別のテーブルへ追記する設計です。取引先マスタには最新の状態と次回の再チェック期限だけを持たせ、履歴はこの2つのテーブルから引きます。次の定義はSQLiteで動作確認したもので、トリガーで更新と削除を拒否します。

CREATE TABLE screening_request (
  id               INTEGER PRIMARY KEY,
  partner_id       INTEGER NOT NULL,
  corporate_number TEXT CHECK (corporate_number IS NULL OR length(corporate_number) = 13),
  query_name       TEXT NOT NULL,
  birth_date       TEXT,
  prefecture       TEXT,
  vendor           TEXT NOT NULL,
  trigger_type     TEXT NOT NULL CHECK (trigger_type IN ('register', 'batch', 'manual')),
  requested_at     TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
  hit_count        INTEGER,
  response_body    TEXT,
  result           TEXT NOT NULL CHECK (result IN ('no_hit', 'needs_review', 'pending'))
);

CREATE TABLE screening_decision (
  id               INTEGER PRIMARY KEY,
  request_id       INTEGER NOT NULL REFERENCES screening_request(id),
  decision         TEXT NOT NULL CHECK (decision IN ('approved', 'rejected', 'same_name_cleared')),
  reason           TEXT NOT NULL,
  decided_by       TEXT NOT NULL,
  decided_at       TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
  next_check_due   TEXT NOT NULL
);

CREATE TRIGGER screening_request_no_update BEFORE UPDATE ON screening_request
BEGIN SELECT RAISE(ABORT, 'screening_request is append-only'); END;
CREATE TRIGGER screening_request_no_delete BEFORE DELETE ON screening_request
BEGIN SELECT RAISE(ABORT, 'screening_request is append-only'); END;
CREATE TRIGGER screening_decision_no_update BEFORE UPDATE ON screening_decision
BEGIN SELECT RAISE(ABORT, 'screening_decision is append-only'); END;
CREATE TRIGGER screening_decision_no_delete BEFORE DELETE ON screening_decision
BEGIN SELECT RAISE(ABORT, 'screening_decision is append-only'); END;

判定を訂正したいときは、元の行を直さず、訂正理由を書いた新しい判定行を足します。PostgreSQLなどで運用するなら、アプリケーション用のロールからUPDATEとDELETEの権限を外す方法でも同じ効果を得ることが可能です。trigger_typeを持たせておくと、登録時の照会とバッチの照会を分けて件数や費用を集計できます。

逮捕や起訴の報道を含む応答は要配慮個人情報にあたりうる、閲覧権限の分け方

反社APIの応答には、個人が逮捕・起訴されたといった報道が含まれることがあります。個人情報保護法は2条3項で犯罪の経歴などを要配慮個人情報と定め、20条2項で本人の同意なく取得できる場合を限定しています。報道機関などにより公開されている要配慮個人情報は同項7号の例外にあたりますが、どの応答がどの例外に当たるかの整理は、自社の法務担当や顧問弁護士と事前に詰めておいてください。

システム側でできるのは、見られる人を絞ることです。response_bodyを持つscreening_requestテーブルは管理部門の判定担当だけが読めるようにし、営業が見るCRMの画面には状態と次回期限だけを表示します。CRMへ記事本文を同期する設計は採りません。CRMは閲覧者が多く、権限を細かく分けにくいためです。

犯罪収益移転防止法の特定事業者に当たる会社では、取引時確認の記録と照会記録の保存期間をそろえる必要が出てきます。義務の範囲は犯罪収益移転防止法とは？特定事業者の義務とKYCシステムの要件で確認できます。

ベンダー変更やAPI障害に備え、照合キーと判定履歴をベンダー非依存の形で持つ

反社チェックツールは、料金や収録媒体の見直しで乗り換えが起きやすい製品です。判定ログをベンダーの応答形式のまま持つと、乗り換えた瞬間に過去の履歴と新しい照会を突き合わせられなくなります。

そこで、ベンダー固有の部分はvendor列とresponse_body列に閉じ込め、hit_countとresultは自社の定義した値に変換して保存します。照合キー(法人番号・正規化した社名・生年月日・都道府県)も自社のテーブルに持ち、どのベンダーへも同じキーから検索語を組み立てます。呼び出し部分はベンダーごとのアダプタとして分けておけば、乗り換え時に書き換えるのはその1か所だけです。

API障害が長引いたときの手順も、この構造なら組めます。保留が一定件数を超えたら担当者へ通知し、ベンダーの画面での手動照会に切り替えて、結果をtrigger_typeがmanualの行として同じテーブルへ記録します。

反社チェックAPI連携を受託開発で組むべき条件と、ツール画面の運用で足りる場面

ここまでの仕組みを全部作るのは、すべての会社に必要なわけではありません。連携開発に費用をかけてよい条件と、見送るべき条件を言い切っておきます。

個別開発で組む条件、取引先の登録口が複数あり月300件を超える会社の連携

連携開発を勧めるのは、次のいずれかに当たる会社です。取引先の登録口が販売管理・購買・CRMなど複数のシステムに分かれている場合、新規と再チェックを合わせた照会が月300件を超える場合、そして上場準備や監査対応で、照会から判定までの記録を求められている場合です。

登録口が複数あると、どのシステムから入った取引先も同じ照合キーと同じ状態管理を通す必要があり、ツールの画面だけでは記録が分散します。月300件を超える規模では、画面での検索とCSV取り込み、結果の転記という手作業が毎日発生し、転記漏れがそのまま記録の欠落になる規模です。取引先マスタと反社APIをつなぐアダプタ、状態管理、判定ログの3つをまとめて組むなら、API開発・システム連携としてご相談いただけます。

連携開発を見送る条件、月50社未満や登録口が1つでベンダー既製連携で済む場合

新規取引先が月50社未満で、取引先の登録口が1つのシステムに集まっている会社には、個別の連携開発は過剰です。ツールの画面検索かCSV一括検索で照会し、取引先マスタに実施日・方法・結果・次回期限を手で記録する運用で十分に回ります。

使っているCRMや販売管理に、ベンダーが用意した既製の連携機能がある場合も、まずはそれを使う方が早く安く済みます。個別開発に進むのは、既製の連携で状態管理や判定ログの要件を満たせないと分かった時点です。順序を逆にして最初から作り込むと、ツールを乗り換えたときに作った部分が丸ごと無駄になります。

よくある質問：反社チェックAPIの料金・同姓同名・自動化の進め方

反社チェックAPIの連携を検討する担当者から出やすい質問に、実装の観点で答えます。

反社チェックAPIの料金は、画面での検索と比べて高くなりますか？

料金体系はベンダーと契約ごとに異なり、API利用に別途の月額や初期費用がかかる契約もあれば、画面検索と同じ照会単価で使える契約もあります。費用に効くのは単価よりも照会回数です。夜間バッチで全件を毎晩照会する設計にすると、画面運用の何倍にも膨らみます。再チェック期限と変更検知で対象を絞り、同じ取引先への重複送信をアプリケーション側で止めれば、照会回数は画面運用と同程度に収まります。

反社チェックAPIだけで同姓同名を判別できますか？

判別はできません。APIは検索条件に合う記事や情報を返すだけで、記事の人物が取引先の代表者本人かどうかは人が判断します。生年や所在地を検索条件に指定できるベンダーならヒット件数は減らせますが、ゼロにはなりません。誤ヒットを減らす照合キーと、残ったヒットを年齢・地域・肩書きの順で確認する社内基準、別人と判定した理由の記録の3つを組み合わせて、確認にかかる時間を短くするのが現実的な到達点です。

反社チェックの自動化はRPAとAPIのどちらで組むべきですか？

ベンダーがAPIを提供しているならAPIで組みます。RPAで画面を操作する方式は、ツール側の画面変更で止まりやすく、照会結果を構造化したデータとして受け取れないため、判定ログに残せる情報も限られます。RPAが向くのは、APIを提供していないツールを使い続ける前提で、月数十件程度の照会を省力化したい場合に限った話です。その場合も、照会日時と結果の記録先は取引先マスタ側に用意しておきます。

既存取引先をAPIで一括チェックするとき、何件ずつ回せばよいですか？

ベンダーの回数制限と同時実行数の上限から逆算します。1日あたりの上限があるなら、対象件数をその上限で割った日数に分けて、再チェック期限の古い順に処理します。初回の一括チェックは件数が最も多くなるため、通常の夜間バッチとは別の期間を設け、ベンダーに事前に件数を伝えておくと安全です。途中で止まっても再開できるよう、処理済みの取引先はscreening_requestテーブルの記録で判別します。

反社チェックの照会結果をCRMやSalesforceに保存してもよいですか？

状態(承認・要確認・却下など)と次回の再チェック期限はCRMに同期して構いません。記事本文や事件の内容まで同期するのは避けます。CRMは営業部門の多くの担当者が閲覧するため、逮捕や起訴の報道のように要配慮個人情報にあたりうる内容の閲覧者を絞りにくいためです。詳細は管理部門だけが読めるデータベースに置き、CRMからは照会記録のIDで参照する構成にします。

関連記事

• 反社チェックとは？やり方4段階と判定基準、取引先マスタへの記録の残し方【2026年】：照会の手順と、マスタに残す記録項目の考え方
• 反社チェックツール比較：4タイプの選び分けと料金の計算、取引先マスタ連携の判断【2026年】：連携先となるツールのタイプ別の違いと連携要否
• 与信管理システムの比較｜4タイプの選び分けと信用調査データ連携・受注時チェックの判断【2026年】：反社チェックと並べて組み込む与信の照会
• データマッチング技術とは？名寄せ・類似検索の3系統とツールの選び方：照合キーの設計に使う名寄せ手法の全体像
• 顧客データ統合の進め方｜名寄せのキー設計とCDPを入れずに済む条件：取引先マスタの重複統合とキー設計