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

ID Verification:Initialize

最終更新日:Feb 01, 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 操作のデバッグと統合」で、API 操作の呼び出し方法、および OpenAPI Explorer で SDK とサンプルコードを取得する方法をご確認ください。

OpenAPI Explorer を使用して、この API 操作を直接デバッグし、 SDK コードサンプルを生成できます。

リクエストパラメーター

名前

タイプ

必須

説明

ProductCode

String

はい

使用するプロダクトソリューション。有効な値:

eKYC: eKYC ソリューションでは、ユーザーはドキュメント検出と生体検知フローを完了する必要があります。

eKYC

MerchantBizId

String

はい

カスタマイズする一意のビジネス ID。問題の追跡とトラブルシューティングに使用されます。ID は最大 32 文字で、英数字を含めることができます。ID が一意であることを確認してください。

説明

Alibaba Cloud はこの ID が一意であるかどうかをチェックしません。追跡を容易にするために、ID が一意であることを確認してください。

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。この ID を使用して、コンソールで関連レコードをクエリできます。ID は最大 10 文字で、英字、数字、アンダースコア (_) を含めることができます。

1234567890

IdSpoof

String

いいえ

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

  • Y: 有効

  • N: 無効 (デフォルト)

Y

Authorize

String

いいえ

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

  • T: 有効

  • F: 無効 (デフォルト)

説明

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

F

LanguageConfig

String

いいえ

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

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

SecurityLevel

String

いいえ

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

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

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

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

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

02

StyleConfig

String

いいえ

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

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

IdThreshold

String

いいえ

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

  • 0: 標準モード

  • 1: 厳格モード

  • 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) ステップで、OCR 結果ページを表示するかどうかを指定します:

  • 1: 表示 (デフォルト)

  • 0: 表示しない

1

ShowGuidePage

String

いいえ

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

説明

このスイッチは PC ではサポートされていません。

  • 1: 表示 (デフォルト)

  • 0: 表示しない

1

ProcedurePriority

String

いいえ

モバイル H5 認証中に互換性の問題が発生した場合に、フォールバックソリューションを許可するかどうかを指定します。

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

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

説明
  • このスイッチは PC ではサポートされていません。

  • アプリケーションシナリオがアプリに埋め込まれた Web ページでの認証完了を伴う場合、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

香港 ID カード (2003 年版)

00000008

香港 ID カード (2018 年版)

00000007

香港・マカオ往来通行証

00000009

香港・マカオ住民の中国本土への旅行許可証

000000011

マカオ ID カード

000000012

台湾住民の中国本土への旅行許可証

00000001

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

戻りデータ

名前

タイプ

説明

HTTP ステータスコード

Integer

HTTP ステータスコード。

200

HTTP 本文

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 は自動的に無効になり、認証に使用できなくなります。

hksb7ba1b28130d24e015d6********

Result.TransactionUrl

String

Web 認証 URL。認証後、ユーザーは ReturnUrl リクエストパラメーターに基づいてリダイレクトされます。

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

  • 安全で効果的な認証プロセスを確保するため、TransactionUrl は 1 回しか使用できません。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

サービスは利用できません。トラブルシューティングのためにエンジニアにお問い合わせください。