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

ID Verification:初期化

最終更新日:Nov 09, 2025

このトピックでは、Initialize API 操作を呼び出して Electronic Know Your Customer (eKYC) リクエストを開始する方法について説明します。

検証リクエストの開始

  • API 操作: Initialize

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

  • 説明: eKYC 検証フローを開始する前に、この API 操作を呼び出して transactionId を取得します。この ID を使用して、検証リクエスト内のすべての API 操作をリンクします。

  • QPS 制限: この 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

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

説明

デバッグと統合を行う前に、「OpenAPI Explorer を使用してサーバーサイド API 操作をデバッグおよび統合する」ドキュメントをお読みください。OpenAPI プラットフォームで API 操作を呼び出す方法と、SDK およびそのサンプルコードを取得する方法について説明しています。

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

リクエストパラメーター

名前

タイプ

必須

説明

ProductCode

String

はい

統合するプロダクトソリューション。指定できる値:

使用するプロダクトプラン。値を eKYC に設定します。このプランでは、ユーザーは証明書検知と生体検知のフロー全体を完了する必要があります。

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

いいえ

公式データベースに対する ID 検証を有効にするかどうかを指定します:

  • T: 有効

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

説明

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

F

SecurityLevel

String

いいえ

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

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

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

    説明

    安全モードは、SDK の新しい Device Guard モジュールを使用して、顔スキャン環境とデバイスのセキュリティを識別します。これにより、インジェクション攻撃の傍受が効果的に強化されます。このモードを選択することを強くお勧めします。

02

IdThreshold

String

いいえ

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

  • 0: 標準モード

  • 1: 厳格モード

  • 2: 緩いモード

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

0

Model

String

いいえ

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

  • LIVENESS (デフォルト): 瞬きアクションの生体検知。

  • PHOTINUS_LIVENESS: 瞬きアクションの生体検知とカラフルな生体検知による二重検知。

  • PHOTINUS_FAR_NEAR_LIVENESS: 瞬きアクション + 遠近 + カラフルな生体検知。

    (App SDK または App SDK に基づく Flutter 統合でのみサポート)

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

  • PC はカラフルな生体検知による二重検知をサポートしていません。

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

リターンコード

HTTP ステータスコード

コード

メッセージ

200

Success

リクエストは成功しました。

400

MissingParameter

パラメーターを空にすることはできません。

InvalidParameter

無効なパラメーターです。

403

Forbidden.RAMUserAccessDenied

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

Forbidden.AccountAccessDenied

ID Verification を有効にし、アカウントに支払い遅延がないことを確認してください

Throttling.Api

API リクエストはスロットリングによりブロックされました。

500

InternalError

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