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

ID Verification:初期化

最終更新日:Feb 01, 2026

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

本人確認リクエストの開始

  • API 操作: Initialize

  • リクエストメソッド: HTTPS POST

  • 説明: eKYC 本人確認フローを開始する前に、この API 操作を呼び出して transactionId を取得します。この ID は、本人確認リクエスト内のすべての 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 とサンプルコードの取得方法について説明しています。

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

リクエストパラメーター

名前

タイプ

必須

説明

ProductCode

String

はい

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

eKYCeKYC ソリューションでは、ユーザーは証明書検知と生体検知フローを完了する必要があります。

eKYC

SceneCode

String

いいえ

カスタムの本人確認シナリオ ID。この ID を使用して、コンソールで関連レコードをクエリできます。ID は最大 10 文字で、文字、数字、アンダースコア (_) を含めることができます。

1234567890

MerchantBizId

String

はい

カスタムの一意なビジネス識別子。後で問題を特定してトラブルシューティングするために使用します。識別子は最大 32 文字で、文字と数字を含めることができます。識別子がユニークであることを確認してください。

説明

Alibaba Cloud サーバーはこの値の一意性をチェックしません。追跡を容易にするために、値がユニークであることを確認してください。

e0c34a77f5ac40a5aa5e6ed20c35****

MetaInfo

String

はい

MetaInfo 環境パラメーター。クライアントサイド SDK から取得します。詳細については、対応するクライアント統合ガイドをご参照ください。

説明

戻り値を変更せずに直接渡してください。

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

MerchantUserId

String

はい

カスタムのユーザー ID または特定のユーザーの別の識別子 (携帯電話番号やメールアドレスなど)。事前に値を非識別化すること (ハッシュ化など) を強く推奨します。

123456789

IdSpoof

String

いいえ

証明書のなりすまし防止検知機能を有効にするかどうかを指定します:

  • Y: 有効

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

Y

DocType

String

はい

証明書タイプ。8 桁の組み合わせで一意に識別されます。詳細については、以下の表をご参照ください。

01000000

Authorize

String

いいえ

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

  • T: 有効

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

説明

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

F

SecurityLevel

String

いいえ

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

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

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

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

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

02

IdThreshold

String

いいえ

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

  • 0: 標準モード

  • 1: 厳格モード

  • 2: 緩和モード

  • 3: 品質検知を無効化 (デフォルト)

0

Model

String

いいえ

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

  • LIVENESS: 瞬きによる生体検知 (デフォルト)。

  • PHOTINUS_LIVENESS: 瞬きによる生体検知と色情報に基づく生体検知 (PC ではサポートされていません)。

説明

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

PHOTINUS_LIVENESS

DocVideo

String

いいえ

本人確認ビデオを保存するかどうかを指定します。

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

  • Y: 本人確認中にユーザーの顔スキャンプロセスのビデオ (1〜2 秒のビデオファイル) が収集され、クエリ API 操作を通じて返されます。

説明

ビデオファイルはサイズが大きいため、ネットワークが不安定な場合、システムは不可欠な本人確認画像の送信を優先するためにビデオファイルを破棄することがあります。

N

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

いいえ

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

  • Y: 有効 (デフォルト)

  • N: 無効

重要
  • この構成にはクライアントサイド SDK のサポートが必要です。この機能を有効にしても、クライアントサイド SDK に顔品質検知モジュールが統合されていない場合、この構成は無効として扱われます。

  • クライアントサイド SDK はバージョン 1.2.5 以降である必要があります。

N

DocPageConfig

String

いいえ

JSON 文字列配列。

OCR_ID_BACK: 裏面を収集します。

説明

現在、これは中国本土の ID カードでのみサポートされています。

OCR_ID_BACK

ShowGuidePage

String

いいえ

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

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

  • 0: 非表示

1

DocScanMode

String

いいえ

OCR 証明書スキャンモード:

  • shoot (デフォルト): 写真を撮る

  • scan: スキャンする

  • auto: 写真とスキャンの自動切り替え

shoot

証明書タイプ一覧

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-5384FF03****

Code

String

コードに戻る

Success

Message

String

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

success

Result.TransactionId

String

本人確認フロー全体の一意な識別子。このフィールドは課金統計や CheckResult API 操作リクエストの開始に使用されます。

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

  • TransactionId を現在のビジネスフローのビジネス ID に添付し、サーバーサイドに保存してください。CheckResult を呼び出す際、サーバーサイドのストレージからこの本人確認 ID を取得して結果クエリを開始します。

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

hksb7ba1b28130d24e015d6********

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

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