すべてのプロダクト
Search
ドキュメントセンター

ID Verification:Initialize

最終更新日:Mar 25, 2026

このトピックでは、Initialize オペレーションを呼び出して eKYC (電子的な本人確認) リクエストを開始する方法について説明します。

検証の開始

  • API: Initialize

  • メソッド: HTTPS POST

  • 説明: 各 eKYC 検証プロセスを開始する前に、この API を呼び出して transactionIdtransactionUrl を取得します。これらのパラメーターは、単一の検証リクエストに対する API 呼び出しをリンクします。

  • この API オペレーションには専用の QPS 制限があります。詳細については、「ID Verification サーバー側 API オペレーションの QPS 制限」をご参照ください。

  • エンドポイント:

    説明
    • 内部ネットワークアクセスのメリット: 内部ネットワークは、同一リージョン内の Alibaba Cloud プロダクト間の非公開通信ネットワークです。ご利用のビジネスサーバーが対応する Alibaba Cloud リージョンにデプロイされている場合、内部の同一リージョンエンドポイントを使用して ID Verification サービスにアクセスできます。これにより、より安全で安定した通信が提供されます。

    • 中国以外からのアクセスに関する最適化の提案: 中国以外のネットワーク環境は複雑になる可能性があります。統合ソリューションを最適化し、ネットワーク遅延を削減し、リクエスト失敗を最小限に抑えるには、「サーバー側ネットワーク遅延分析と最適化」をご参照ください。

    中国 (香港)

    • パブリックネットワーク: cloudauth-intl.cn-hongkong.aliyuncs.com

    • 内部ネットワーク: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

オンラインデバッグと統合

説明

API オペレーションをデバッグおよび統合する前に、OpenAPI Explorer を使用して API オペレーションを呼び出し、SDK とサンプルコードを取得する方法については、「OpenAPI Explorer を使用したサーバー側 API オペレーションのデバッグと統合」をご参照ください。

この API は、OpenAPI Explorer で直接実行してデバッグし、SDK コード例 を生成できます。

リクエストパラメーター

パラメーター

必須

説明

ProductCode

String

はい

使用するソリューション。有効な値:

eKYC: eKYC ソリューション。ユーザーはドキュメント認識と顔のライブネス検証の両方を完了します。

eKYC

MerchantBizId

String

はい

トラブルシューティング目的で定義する一意のビジネス識別子。値は最大 32 文字と数字の組み合わせにできます。

説明

Alibaba Cloud はこの値の一意性をチェックしません。トラブルシューティングを簡素化するために、この値が一意であることを確認してください。

e0c34a77f5ac40a5aa5e6ed20c35****

MetaInfo

String

はい

MetaInfo 環境パラメーター。JS ファイルを介して getMetaInfo() 関数を呼び出して取得する必要があります。MetaInfo の取得方法の詳細については、対応するプラットフォームのクライアント統合ドキュメントをご参照ください。

重要
  • 戻り値を変更しないでください。直接渡してください。

  • サーバー側はこのパラメーターを使用してモバイルまたは PC 実行環境を識別し、異なる検証 URL を送信します。関数説明に記載されているように、実際の実行環境からこのパラメーターを取得してください。

{
  "zimVer": "3.0.0",
  "appVersion": "1",
  "bioMetaInfo": "4.1.0:1150****,0",
  "appName": "com.aliyun.antcloudauth",
  "deviceType": "ios",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}

MerchantUserId

String

はい

カスタマイズするユーザー ID、または携帯電話番号やメールアドレスなど、特定のユーザーを識別できる別の識別子。この値はハッシュ化するなどして非識別化することを強く推奨します。

123456789

ReturnUrl

String

いいえ

ご利用のビジネスページのリダイレクト URL。

重要

このパラメーターは、iframe ベースの統合でのみオプションです。

https://www.alibabacloud.com

DocType

String

はい

ドキュメントタイプを一意に識別する 8 桁の値。詳細については、以下の表をご参照ください。

01000000

SceneCode

String

いいえ

コンソールで関連レコードをクエリするために使用できるカスタム検証シナリオ ID。値は最大 10 文字、数字、またはアンダースコア (_) の組み合わせにできます。

1234567890

IdSpoof

String

いいえ

ドキュメントのなりすまし防止検出を有効にするかどうかを指定します。

  • Y: 機能を有効にします。

  • N: 機能を無効にします。これがデフォルト値です。

Y

Authorize

String

いいえ

公式データベースに対する本人確認を有効にするかどうかを指定します。

  • T: 機能を有効にします。

  • F: 機能を無効にします。これがデフォルト値です。

説明

この機能は現在、中国本土の第二世代住民 ID カードでのみ利用可能です。

F

LanguageConfig

String

いいえ

カスタム言語構成。追加する言語構成を構成テンプレートに基づいて JSON 文字列に変換します。次に、このパラメーターを指定してカスタム言語構成を追加します。詳細については、「国際化言語とカスタムテキストサポート」をご参照ください。

{
  "languageContent": {****},
  "ocrResultContent": {****},
  "supportedLanguage": [****],
  "titleTranslate": {****},
}

SecurityLevel

String

いいえ

検証フローの異なるセキュリティレベルを表すモード。有効な値:

  • 01: 標準モード。このモードは、デバイス情報収集に制限がある低脅威シナリオにのみ適用されます。

  • 02: 安全モード。比較的厳格なモード (デフォルト)

    説明
    • 安全モードは、SDK の新しい Device Guard モジュールを使用して、デバイス情報に基づいて顔スキャン環境のセキュリティを識別します。これにより、インジェクション攻撃を阻止する能力が効果的に強化されます。このモードを有効にしてください。

    • 開発およびテスト中に、テストデバイスの環境特性により Device Guard がそれを脅威と評価し、検証失敗 (Subcode 206) をトリガーする可能性があります。テスト効率を向上させるには、テストフェーズ中にモードを「01 標準モード」に設定してください。本番稼働時には、「02 安全モード」に切り替えて検証セキュリティを強化してください。

02

StyleConfig

String

いいえ

カスタム UI 構成。追加する UI 構成を構成テンプレートに基づいて JSON 文字列に変換します。次に、このパラメーターを指定してカスタム UI 構成を追加します。詳細については、「IDV UI スタイルカスタマイズ」をご参照ください。

{
  "guidepage:": {****}, 
  "ocrPage": {****},
  "ocrResultPage": [****],
  "facePage": {****},
}

IdThreshold

String

いいえ

カスタム OCR 品質検出のしきい値モード:

  • 0: 標準モード

  • 1: Strict モード

  • 2: 緩いモード

  • 3: 品質検出を無効にする (デフォルト)

0

Model

String

いいえ

実行する生体検知のタイプ:

  • LIVENESS: まばたき生体検知 (デフォルト)。

  • PHOTINUS_LIVENESS: まばたき生体検知と色ベースの生体検知 (PC ではサポートされていません)。

  • SILENT: パッシブ生体検知。この機能は現在、Web SDK (モバイル / PC) 統合でのみサポートされています。

説明

サポートされている SDK バージョンの詳細については、「SDK リリースノート」をご参照ください。

PHOTINUS_LIVENESS

DocVideo

String

いいえ

検証ビデオを保存するかどうかを指定します。

  • N: いいえ (デフォルト)。

  • Y: ユーザーの顔スキャンプロセス (1 ~ 2 秒のビデオファイル) のビデオは、検証中に収集され、クエリ API オペレーションを介して返されます。

説明

ビデオファイルは大きいため、ネットワークが不安定な場合、システムは必須の検証画像の送信を優先するためにそれを破棄する可能性があります。

N

ShowBlbumIcon

String

いいえ

ドキュメント OCR 中にアルバムから写真をアップロードするオプションを表示するかどうかを指定します。

  • 1: エントリを表示します。これがデフォルト値です。

  • 0: エントリを表示しません。

1

ShowOcrResult

String

いいえ

ドキュメント OCR 中に認識結果ページを表示するかどうかを指定します。

  • 1: ページを表示します。これがデフォルト値です。

  • 0: ページを表示しません。

1

ShowGuidePage

String

いいえ

ガイドページを表示するかどうかを指定します。

説明

この設定は PC ではサポートされていません。

  • 1: ページを表示します。これがデフォルト値です。

  • 0: ページを表示しません。

1

ProcedurePriority

String

いいえ

モバイル H5 ページでの検証中に互換性の問題が発生した場合に、フォールバックオプションを提供するかどうかを指定します。

  • url (デフォルト): フォールバックがサポートされています。ページには検証 URL が表示され、ユーザーはそれを別のブラウザにコピーしてプロセスを続行できます。

  • keep: フォールバックはサポートされていません。システムは直接エラーの原因を返し、検証プロセスを終了します。

説明
  • この設定は PC ではサポートされていません。

  • ご利用のユースケースがアプリケーション内に埋め込まれたウェブページで検証を完了することを含む場合、URL フォールバックを許可しないためにこのパラメーターを keep に設定することを推奨します。

url

CallbackUrl

String

いいえ

検証結果通知用の Webhook アドレス。コールバックリクエストメソッドはデフォルトで GET です。Webhook アドレスは https で始まる必要があります。検証が完了すると、プラットフォームはこのアドレスにコールバックを送信し、以下のパラメーターを自動的に追加します。

  • transactionId

  • passed

  • subcode

警告
  • システムは、API オペレーションが呼び出される前にこのアドレスがアクセス可能かどうかをチェックします。アドレスがパブリックネットワーク経由でアクセスできない場合、400 エラーが返されます。

  • コールバックは検証完了後すぐに実行されますが、ネットワークの問題により遅延する場合があります。最初にクライアントで検証完了通知を受け取り、その後クエリ API オペレーションを呼び出して検証詳細を取得することを推奨します。

https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

CallbackToken

String

いいえ

リプレイ防止と改ざん防止検証のために生成するセキュリティトークン。

このパラメーターを設定すると、CallbackToken フィールドが CallbackUrl へのコールバックに含まれます。

NMjvQanQgplBSaEI0sL86WnQplB

AppQualityCheck

String

いいえ

厳格な顔品質検出を有効にするかどうかを指定します。

重要

この機能は Web SDK ではサポートされていません。

  • Y: 機能を有効にします。これがデフォルト値です。

  • N: 機能を無効にします。

Y

EditOcrResult

String

いいえ

ユーザーが OCR 結果ページで情報を編集できるかどうかを指定します。

  • 1: サポートされています。これがデフォルト値です。

  • 0: サポートされていません。

0

ドキュメントタイプ

DocType

ドキュメント

01000000

パスポート

00000006

中国 (香港) 身分証明書 (2003 年版)

00000008

中国 (香港) 身分証明書 (2018 年版)

00000007

香港・マカオ往来通行証

00000009

香港・マカオ居住者向け本土往来通行証

000000011

マカオ (中国) 身分証明書

000000012

台湾居住者向け本土往来通行証

00000001

中国本土の第二世代住民 ID カード

応答データ

パラメーター

説明

HTTP ステータスコード

Integer

HTTP ステータスコード。

200

HTTP Body

RequestId

String

リクエスト ID。

130A2C10-B9EE-4D84-88E3-5384FF0****

Code

String

詳細については、「応答コード」をご参照ください。

Success

Message

String

応答コードの詳細な説明。

success

Result.TransactionId

String

検証フロー全体の一意の識別子。このパラメーターは、課金統計および CheckResult API オペレーションリクエストを開始するために使用されます。

重要
  • 無効なパラメーターなどのエラーがリクエスト中に発生した場合、TransactionId は返されません。

  • TransactionId を現在のビジネスフローのビジネス ID にアタッチし、サーバー側に保存してください。CheckResult を呼び出す際、この検証 ID をサーバー側ストレージから取得して結果クエリを開始してください。

  • TransactionId または TransactionUrl を取得した後、30 分以内に検証を完了する必要があります。この期間を過ぎると、ID または URL は自動的に無効になり、検証に使用できなくなります。

hksb7ba1b28130d24e015d********

Result.TransactionUrl

String

ウェブ検証 URL。検証が完了すると、ユーザーはリクエストパラメーターで指定された ReturnUrl にリダイレクトされます。

重要
  • 統合中に TransactionUrl を変更しないでください。変更すると検証が失敗する可能性があります。

  • 安全で効果的な検証プロセスを確保するため、TransactionUrl は一度だけ使用できます。URL を再利用すると検証が失敗します。

  • TransactionId または TransactionUrl を取得した後、30 分以内に検証を完了する必要があります。この期間を過ぎると、ID または URL は期限切れになります。

https://www.alibabacloud.com/index.html?clientcfg=****

Result.Protocol

String

hksb7ba1b28130d24e015d*********

応答コード

HTTP ステータスコード

コード

説明

200

Success

リクエスト成功。

400

MissingParameter

パラメーターは空にできません。

InvalidParameter

無効なパラメーター。

401

Forbidden.ExceptionRepeatedInvoke

繰り返された異常な呼び出しの数が制限を超えています。

403

Forbidden.RAMUserAccessDenied

RAM ユーザーに AliyunAntCloudAuthFullAccess 権限を付与する必要があります。詳細については、「RAM ユーザーにサービスへのアクセスを許可する」をご参照ください。

Forbidden.AccountAccessDenied

ID Verification をアクティブ化し、アカウントに支払い遅延がないことを確認してください

Throttling.Api

速度制限により API リクエストがブロックされました。

500

InternalError

内部システムエラー。トラブルシューティングのためにエンジニアにフィードバックを提供してください。

503

ServiceUnavailable

サービスが利用できません。トラブルシューティングのためにエンジニアに連絡してください。