sumsub-check-databases

データベースを確認する

Sumsub が国ごとに提供するデータベース確認ソース、それぞれのソースが現在のテナントで有効かどうか、および認証レベルへの組み込み方法を一覧表示します。呼び出し側は、レベルを構築する前にデータベース／非書類認証の可否を判断するために使用します。

対象範囲：KYC（個人）のみ — 現時点では。 エンドポイントが返すのは、個人／人物向けの確認ソースのみです。企業（KYB）のデータベース認証はまだここでは公開されていません。このスキルを使用して、企業／事業者向けのソースを配置しないでください。

エンドポイント

GET https://api.sumsub.com/resources/api/agent/settings/checkSources?country=<country>

country はISO alpha-3 コードです（例：DEU）。ユーザーが国名を指定した場合は、呼び出す前に alpha-3 に変換してください。カタログ全体を返す場合は country を省略します。認識されないコードやサポートされていないコードはエラーになりません。HTTP 200 と空の checkSources リストが返されます。

可能な限り country を指定してください。 フィルターなしのレスポンスはカタログ全体で、全ての国にわたる数百件のエントリーが含まれているため、コンテキストが肥大化したり切り詰められたりする可能性があります。ユーザーが国を指定した場合は、それでフィルターしてください。指定していない場合は、フィルターなしで呼び出す前に、必要な国を尋ねることを優先してください。大量のレスポンスを処理でき、意図的にカタログ全体が必要な場合に限り、country を省略してください。

認証 — アプリトークン + シークレット（サンドボックスのみ）

このスキルは公開 Sumsub API に接続し、 認証リファレンス に従って各リクエストに署名します。仕組みの詳細は sumsub-api-auth スキルに記載されています。401 Invalid signature が発生した場合は、こちらをお読みください。

⚠️ サンドボックストークンのみ。 ここでは、本番環境のアプリトークンを受け取ったり、使用したりしないでください。ユーザーが提示した場合は拒否し、https://cockpit.sumsub.com/checkus/devSpace/appTokens でサンドボックス用のトークンペアを作成するよう依頼してください（最初にワークスペースをSandboxに切り替え、その後Createを選択します）。トークンとシークレットは一度しか表示されません。ダイアログを閉じる前に両方をコピーしてください。ヘルパースクリプトでこの制限を適用しており、sbx: で始まらないトークンは拒否されます。

変数	例
SUMSUB_APP_TOKEN	sbx:... — ダッシュボードで取得したサンドボックス用アプリトークン。
SUMSUB_SECRET_KEY	トークンの作成時に一度だけ表示される、対応するシークレット。
SUMSUB_BASE	任意。デフォルトは https://api.sumsub.com です。

使用方法

bash ${CLAUDE_SKILL_DIR}/scripts/check_databases.sh <country>

出力：Sumsub の生のレスポンス本文に続いて HTTP <code> が表示されます。

成功（HTTP 200）：

{"checkSources": [
  {
    "sourceId": "arg_gov_dni",
    "name": "Argentina DNI Verification",
    "description": "Verifying user's personal, biometric, and residency data against official government sources.",
    "dataSources": [
      "National Registry of Persons (Registro Nacional de las Personas - RENAPER)",
      "Agency of Public Revenues and Control (Agencia de Recaudación y Control Aduanero – ARCA)"
    ],
    "country": "ARG",
    "checkType": "E_KYC_CHECK",
    "confirmationType": "otp",
    "status": "ENABLED",
    "validationReady": false,
    "stepsReady": ["E_KYC", "IDENTITY"],
    "supportedDocuments": ["ID_CARD"],
    "requiredInputFields": ["gender", "number"],
    "optionalInputFields": ["address.postCode"],
    "selfieRequirement": "ADDITIONAL",
    "outputFields": ["firstName", "lastName", "addresses", "gender", "nationality", "dob", "tin"],
    "violations": ["GENDER_MISMATCH", "DEAD", "PERSON_IS_MINOR", "SELFIE_MISMATCH"]
  }
]}
HTTP 200

入力フィールドの値は、バックグラウンドチェックの入力データにおける機械可読なフィールド名です。number、dob、address.postCode、bankAccount.bankName などが該当し、表示用ラベルではありません。ドット区切りの名前はネストされたオブジェクト（address.*、bankAccount.*）を表します。ユーザーに表示する際は、読みやすい表現に変換してください。

セルフィーは入力フィールドに記載されることはありません。 専用の selfieRequirement フィールドに記載されます。フローにセルフィーの手順が必要かどうかを判断する際は、optionalInputFields ではなくこちらを確認してください。

フィールドの説明

フィールド	意味
sourceId	チェックソースの固定ID（{country}_{provider}_{subject}）。
name	人が読めるソース名（英語）。例：「Argentina DNI Verification」。
description	ソースが何を検証するかを説明する、1行の英文。ない場合もあります。
dataSources	ソースがデータを取得する基盤レジストリ／プロバイダー（英語名）。ない場合もあります。
country	ソースの対象となる正規のISOアルファ3文字コード。
checkType	内部カテゴリ（E_KYC_CHECK、PERSON、TIN）。情報提供のみを目的としており、フィルターではありません。企業（KYB）タイプは返されません。
confirmationType	書類を使わないチェックで申請者が確認を行う方法：otp、oAuth（銀行／国民eIDサービスにログイン）、またはeID（eIDカードをNFCでスキャン）。ソースで確認手順が不要な場合はありません。
status	テナントごとの有効化状態で、利用可否を決定します：ENABLED（本番環境でライセンス済みのため、サンドボックスでも利用可能）／SANDBOX_ONLY（サンドボックスのみライセンス済み。テストには使えますが、本番環境では実行されません）／DISABLED（どの環境でもライセンスされていません）。詳細は以下を参照してください。
validationReady	収集中の書類をソースで相互検証できる（データベース検証）場合はtrueです。
stepsReady	ソースを書類を使わないチェックとして利用できるレベルのステップタイプ（IdDocSetType、例：E_KYC、IDENTITY）。利用できるものがない場合は空です。
supportedDocuments	ソースで検証できるIdDocType。
requiredInputFields / optionalInputFields	申請者が入力する必要がある／入力できる機械処理用フィールド名（例：number、dob、address.postCode）。身元調査の入力データキーであり、表示ラベルではありません。自撮り画像は含まれません。
selfieRequirement	REQUIRED（自撮り画像なしではソースを実行できません）／ADDITIONAL（任意ですが、一致精度が向上します）／なし（自撮り画像は不要）。
outputFields	一致が確認された場合にソースが返すフィールド。
violations	ソースが報告する可能性のある違反理由（例：GENDER_MISMATCH、DEAD）。

型、列挙値、および意味の詳細については、references/checksources-schema.mdを参照してください。

呼び出し元の使用方法

1. HTTP ステータスが 200 でない場合は、直ちに停止してください。エラーボディをユーザーに表示し、先に進まないでください。
2. checkSources リストが空でもエラーではありません。 その国に対して Sumsub が KYC データベースのソースを提供していないことを意味します。または、country の値が認識可能な ISO alpha-3 コードではなかった可能性があります。その国で利用可能なデータベースのチェックソースはないことをユーザーに伝えてください。ユーザーが国の 名称 を入力していた場合は、正しい alpha-3 コードに変換されているか確認し（例：Germany → DEU）、再試行を提案してください。ソースを捏造してはいけません。データベースレイヤーは任意なので、ドキュメントベースの検証に切り替えてください（下記の配置パターンを参照）。
3. status を確認してください。テナントごとに設定され、環境には依存しません（sandbox と prod のどちらからクエリしても同じ値が返されます）。ENABLED：本番環境でライセンスされているため、sandbox でも利用できます。使用可能なので続行します。SANDBOX_ONLY：sandbox でのみライセンスされています。sandbox でのテストには使用できますが、本番環境ではこのソースを実行できないため、その旨を明確に伝えてください。また、本番稼働前に有効化するよう案内してください。DISABLED：いずれの環境でもライセンスされていないため、使用できません。ENABLED 以外の場合は、下記のソースの有効化を参照してください。
4. ユーザーが必要としているソースが利用できない場合、黙って省略せず、すべてを一律に停止しないでください。 チェックソースがなくても（エンタイトルメントがない場合とは異なり）、有効なドキュメントベースのレベルは成立します。そのため、問題点を明らかにし、用途に応じて次のように対応してください。

ユーザーが希望すること	ソースが利用できない場合の対応
データベース検証（ドキュメント と データベースの照合）	ソフトに対応します。ドキュメントの検証は引き続き有効です。確認を取り、データベースレイヤーなしで続行します。
本人確認ステップ内の非ドキュメントソース（IDENTITY 内にネストされたソース）	代替案を提示します。本人確認ステップをドキュメントのアップロードに戻すよう提案し、ユーザーが選択した後に続行します。
単独の非ドキュメントソース（データベースのみのステップが主な目的）	停止に最も近いケースです。ソースなしではそのステップを実行できません。ドキュメントベースの代替案を提示し、明示的な確認が得られた場合にのみ続行します。

黙って仕様を下げたり、一方的に完全停止したりしてはいけません。問題点と影響を明らかにし、（呼び出し元を介して）ユーザーに判断を委ねてください。引き続き適用される唯一の完全停止条件は、非ドキュメントの本人確認には E_KYC_TARGET エンタイトルメントも必要であり、sumsub-check-permissions がこれを個別に確認することです。

ソースの有効化

エージェントはソースを有効化できません。チェックソースを有効化するための公開 API はありません。 これは DISABLED（何も動作しない）と SANDBOX_ONLY（sandbox では動作するが、本番環境では動作しない）の両方に当てはまります。どのデータベースチェックが、どの環境で利用できないのかをユーザーに伝えてください。ソースの name を具体的に示し、その sourceId も伝えてください。さらに、どの検証が行えなくなるのかも説明してください。その後、次の案内をしてください。

• Sumsub ダッシュボードの データベース → 利用可能な製品 — ほとんどのソースはセルフサービスで有効化できます。
• ソースをセルフサービスで有効化できない場合は、ユーザーからカスタマーサクセスマネージャーまたは Sumsub サポートに連絡し、有効化を依頼してください。

レベル内での各ソースの配置先

選択したソースは、レベルの checkSourceSettings.countrySettings[] に組み込みます。country ごとにエントリーを 1 つ設定し、レベルのトップレベルに配置する場合は checkType も指定して、executionConfigurations の下に sourceId を記述します。validationReady と stepsReady は、どの配置先が適用されるかを示します。sumsub-create-level がペイロード全体を構築し、このスキルでは配置先を決定します。

ソースは、validationReady が true であり、かつ／または stepsReady にエントリーがある場合があります。両方を確認してください。これらは独立したシグナルです。stepsReady に複数のステップタイプが記載されている場合、それは同じソースを配置できる場所の一覧であり、すべてに同時に配置する指示ではありません。ユーザーの意図に合う配置先を選んでください。

配置先（チケット）	シグナル	レベル内での意味
データベース検証	validationReady: true	ドキュメントの docSet（例：IDENTITY）をそのままにします。申請者は引き続きドキュメントを提出します。ソースはレベルのトップレベルにある checkSourceSettings（requiredIdDocs と同階層で、その内部にはネストしません）に追加します。
ドキュメント不要、単独配置	stepsReady にステップタイプが単独で含まれている（例：E_KYC）	専用のドキュメント不要の docSet を使用し、アップロードは不要です。本人確認には E_KYC を使用します（E_KYC_TARGET が必要です。 sumsub-check-permissions で確認してください）。申請者が requiredInputFields を入力し、データベースと照合します。ソースはその docSet 自体の checkSourceSettings 内にネストして追加します。
既存のステップ内にドキュメント不要で配置	stepsReady にステップタイプ（例：IDENTITY）が含まれており、すでに必須となっているドキュメントステップと併用する	ドキュメントの docSet の types はそのままにします（ドキュメントのアップロードは引き続き任意です）。ソースの checkSourceSettings は同じ docSet 内にネストして配置します。申請者は 1 つのステップ内で、アップロードまたはデータベース照合を選べます。E_KYC_TARGET も必要です。

どの配置方法でも、ソースは country、checkType（トップレベルに配置する場合のみ）、および executionConfigurations[].sourceId で参照します。任意の fallbackReasons（NO_DATA、NAME_MISMATCH、DOB_MISMATCH、INVALID_DOC_NUMBER、FAILED、DEAD）を指定すると、照合で確認できなかった場合に別のソースまたはドキュメントへフォールバックできます。具体例は sumsub-create-level/examples/ の identity-selfie-with-database-validation.json（トップレベル、validationReady）、identity-with-non-doc-selfie.json（IDENTITY 内にネスト）、non-doc.json（単独の E_KYC）を参照してください。

概念リファレンス：ドキュメント不要の認証、データベース検証。

関連項目

• sumsub-create-level — これらのソースを組み込むレベルを構築します。
• sumsub-check-permissions — ドキュメント不要の本人確認に必要な E_KYC_TARGET の権限を確認します。
• sumsub-api-auth — リクエスト署名の詳細。
• references/checksources-schema.md — レスポンスの完全なスキーマ、フィールドの型、列挙値。