このトピックでは、サーバー側 API 呼び出しを使用した ID Verification の統合方法について説明します。
API 情報
API オペレーション: EkycVerify
リクエストメソッド: HTTPS POST
オペレーションの説明: このオペレーションを呼び出し、イメージなどの情報を指定して、電子本人確認 (eKYC) を実行できます。
QPS 制限: 各 API には専用の QPS 制限があります。詳細については、「ID Verification サーバー側 API の QPS 制限」をご参照ください。
サービスエンドポイント:
説明内部ネットワークアクセスのメリット: 内部ネットワークは、同じリージョン内の Alibaba Cloud サービス間の非公開通信を可能にします。ご利用のアプリケーションサーバも同じリージョンにある場合は、内部ネットワークエンドポイントを使用して ID Verification サービスにアクセスすることで、より安全で安定した接続を実現できます。
海外アクセス向け最適化: 中国本土以外のネットワーク状況は複雑になる可能性があります。レイテンシーを削減し、リクエスト失敗を最小限に抑えるには、「サーバー側ネットワークレイテンシー分析と最適化」のベストプラクティスに従って統合を最適化してください。
中国 (香港)
パブリックエンドポイント:
cloudauth-intl.cn-hongkong.aliyuncs.com内部エンドポイント:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
オンラインデバッグと統合
デバッグまたは統合を行う前に、「OpenAPI を使用したサーバー側 API のデバッグと統合」ガイドを読んで、OpenAPI プラットフォームで API を呼び出す方法と SDK を取得する方法を理解してください。
OpenAPI Explorerでは、この API を直接実行してデバッグし、SDK コード例を生成できます。
イメージ要件
サポートされているイメージ形式: JPG、JPEG、PNG。
イメージサイズ: 推奨 50~100 KB。最大 1 MB。
イメージ解像度: 少なくとも 640 x 480 ピクセル (高さ x 幅) で、1920 x 1080 ピクセル以下である必要があります。最適な結果を得るには、短い辺を 720 ピクセルにスケーリングし、圧縮率を 0.9 より大きくすることをお勧めします。横向きのイメージは検出精度を低下させる可能性があるため、イメージは縦向き (高さが幅より大きい) である必要があります。
説明イメージを base64 形式に変換すると、通常、データサイズが増加します。イメージを base64 エンコードされた文字列として渡す場合は、元のイメージが 0.6 MB を超えないようにして、1 MB のデータ転送制限内に収まるようにしてください。
イメージ品質の推奨事項:
顔は完全で、クリアで、遮るものがなく、被写体はカメラに直接向いている必要があります。フロントカメラで撮影したイメージを使用することをお勧めします。
顔はイメージの総面積の 60% 以上を占める必要があります。顔が小さいと、検出精度が低下する可能性があります。
イメージに複数の顔が含まれている場合、アルゴリズムはデフォルトで最大の顔を処理します。最良の結果を得るには、複数の顔が含まれるイメージを避けてください。
リクエストパラメーター
パラメーター | タイプ | 必須 | 説明 | 例 |
ProductCode | String | はい | 使用するソリューション。値を eKYC_MIN に設定します。 | eKYC_MIN |
SceneCode | String | いいえ | 検証シナリオのカスタム ID。ID Verification コンソールで関連レコードをクエリするために使用されます。ID は最大 10 文字で、文字、数字、アンダースコア (_) を含めることができます。 | 1234567890 |
MerchantBizId | String | はい | トラブルシューティングに使用されるビジネスの一意の識別子。長さ 32 文字で、文字と数字を含むカスタム値を指定できます。値が一意であることを確認してください。 | e0c34a77f5ac40a5aa5e6ed20c35**** |
MerchantUserId | String | はい | 顧客の ID。携帯電話番号やメールアドレスなどのカスタム値を指定できます。カスタム値を指定する前に、データマスキングを実行することをお勧めします。たとえば、ハッシュ化を実行できます。 | Y |
DocType | String | はい | ドキュメントタイプ。ドキュメントタイプを一意に識別するために 8 桁の値を指定できます。詳細については、「ドキュメントタイプ」をご参照ください。 | 01000000 |
DocName | String | いいえ | 顧客の実名。 説明
上記の条件が満たされている場合、次のロジックが適用されます。 | Alice |
DocNo | String | いいえ | 顧客の身分証明書番号。 説明
上記の条件が満たされている場合、次のロジックが適用されます。 | 411xxxxxxxxxxx0001 |
IdOcrPictureBase64 | String | いいえ 説明 IdOcrPictureBase64 と IdOcrPictureUrl のいずれかのパラメーターを指定する必要があります。 | Base64 エンコードされたドキュメントイメージ。 説明 IdOcrPictureBase64 パラメーターを使用してイメージをアップロードする場合は、イメージのサイズを確認してください。過度に大きいサイズのイメージを指定しないでください。 | Base64-encoded content |
IdOcrPictureUrl | String | いいえ | ドキュメントイメージの URL。URL は、インターネット経由でアクセスできる HTTP または HTTPS URL です。 | https://*** |
FacePictureBase64 | String | いいえ 説明 FacePictureBase64 と FacePictureUrl のいずれかのパラメーターを指定する必要があります。 | Base64 エンコードされた顔イメージ。 説明 FacePictureBase64 パラメーターを使用してイメージをアップロードする場合は、イメージのサイズを確認してください。過度に大きいサイズのイメージを指定しないでください。 | Base64-encoded content |
FacePictureUrl | String | いいえ | 顔イメージの URL。URL は、インターネット経由でアクセスできる HTTP または HTTPS URL です。 | https://*** |
Crop | String | いいえ | イメージから顔をトリミングするかどうかを指定します。
| F |
Authorize | String | いいえ | 公式データベースに対する検証を有効にするかどうかを指定します。
説明 このパラメーターは、中国本土居住者向け第二世代身分証明書のみをサポートしています。 | F |
IdThreshold | String | いいえ | OCR 品質チェックのモードを設定します。有効な値は次のとおりです。
| 0 |
ドキュメントタイプ
DocType | ドキュメント |
01000000 | パスポート (グローバル) |
00000006 | 身分証明書 (香港 (中国)) (2003年版) |
00000008 | 身分証明書 (香港 (中国)) (2018年版) |
00000007 | 香港・マカオ往来通行証 |
00000009 | 香港・マカオ住民向け中国本土往来通行証 |
000000011 | 身分証明書 (マカオ (中国)) |
000000012 | 台湾住民向け中国本土往来通行証 |
00000001 | 中国本土居住者向け第二世代身分証明書 |
レスポンスパラメーター
パラメーター | タイプ | 説明 | 例 | |
HTTP Status Code | Integer | HTTP ステータスコード。 | 200 | |
HTTP Body | RequestId | String | リクエスト ID。 | 130A2C10-B9EE-4D84-88E3-5384FF0**** |
Code | String | 返された エラーコード。 | Success | |
メッセージ | 文字列 | 返されたエラーコードの詳細な説明です。 | success | |
Result.Passed | String | 最終検証結果。有効な値は次のとおりです。
| Y | |
Result.SubCode | String | 検証結果の説明。詳細については、「ResultObject.SubCode エラーコード」をご参照ください。 | 200 | |
Result.ExtFaceInfo | String | 顔のライブネス検証の結果。値は JSON 形式です。詳細については、「ExtFaceInfo」をご参照ください。 | | |
Result.ExtIdInfo | String | ドキュメント検証の結果。 値は JSON 形式です。詳細については、「ExtIdInfo」をご参照ください。 | | |
エラーコード
HTTP ステータスコード | コード | メッセージの説明 |
200 | Success | リクエスト成功。 |
400 | MissingParameter | パラメーターは空にできません。 |
InvalidParameter | 無効なパラメーター。 | |
401 | UnqualifiedPhoto | アップロードされたイメージが読み取り不能であるか、イメージ解像度が要件を満たしていません。イメージを変更することをお勧めします。 写真がクリアで、通常の露出で、遮蔽物なしで完全であり、大きな角度のずれがないことを確認してください。 |
DataDuplication | Base64 エンコードされたイメージと URL イメージアドレスの両方が提供されています。これらのパラメーターのいずれか 1 つのみを選択してください。 | |
ToolargeImage | イメージサイズが大きすぎます。イメージを圧縮するか、アップロード方法を変更することをお勧めします。 | |
DownloadTimeout | URL イメージダウンロードタイムアウト。 | |
NoFaceDetected | アップロードされたイメージで顔が検出されませんでした。 | |
403 | Forbidden.RAMUserAccessDenied | RAM ユーザーに AliyunAntCloudAuthFullAccess 権限を付与する必要があります。詳細については、「RAM ユーザーにサービスへのアクセスを許可する」をご参照ください。 |
Forbidden.AccountAccessDenied | ID Verification をアクティブ化しており、アカウントに支払い遅延がないことを確認してください。 | |
Throttling.Api | API リクエストは速度制限によりブロックされました。 | |
500 | InternalError | 内部システムエラー。トラブルシューティングのためにエンジニアにフィードバックを提供してください。 |
503 | ServiceUnavailable | サービスが利用できません。トラブルシューティングのためにエンジニアに連絡してください。 |
ResultObject.SubCode のコード
コード | 請求済み | 説明と原因 |
200 | はい | 顧客は検証に合格しました。 |
201 | はい | 氏名が公式データベースの身分証明書と一致しません。顧客に関する情報が不正確または偽造されています。顧客は情報を確認し、再度本人確認を実行できます。 説明 このエラーコードは、プロダクトによって検証される証明書の種類が中国の身分証明書であり、かつ権威ある検証機能が有効になっている場合にのみ返されます。 |
202 | はい | お客様の情報は、公式データベースで照会できません。手動レビューへのエントリーポイントを設けることを推奨します。 説明 このエラーコードは、プロダクトが検証する証明書の種類が中国身分証明書であり、かつ権威ある検証機能が有効化されている場合にのみ返されます。 |
203 | はい | イメージがクエリされないか、イメージが利用できません。考えられる原因: 権威ある比較ソースにライブラリイメージが保存されていません。手動レビューへのエントリポイントを確保することをお勧めします。 |
204 | はい | ドキュメントの顔がライブの顔と一致しません。考えられる理由として、顔が異なるライブ人物に属しているか、ライブの顔の品質が低いことが挙げられます。 |
205 | はい | 生体検知の結果にリスクが示されています。 |
207 | はい | アップロードされた顔が公式データベース内の顔と一致しません。これは、顔が異なる人物のものであるか、提出された顔画像の品質が低いことを意味する可能性があります。 説明 このエラーコードは、プロダクトが検証する証明書の種類が中国のIDカードであり、かつ公的認証機能が有効化されている場合にのみ返されます。 |
209 | はい | 信頼できる比較元で例外が発生します。 説明 このエラーコードは、プロダクトによって検証される証明書タイプが中国のIDカードであり、公的認証機能が有効になっている場合にのみ返されます。 |
212 | はい | ドキュメントの偽造防止検出の結果に、ドキュメントの写真やコピー、改ざんされたドキュメントなどのリスクが示されています。 |
ExtFaceInfo
パラメーター | タイプ | 説明 | 例 |
facePassed | String | 顧客が顔のライブネス検証に合格したかどうかを示します。有効な値は次のとおりです。
| Y |
faceComparisonScore | Double | 収集された顔とドキュメントの顔の比較スコア。有効な値: 0~100。 | 99.99 |
faceAttack | String | 提出された顔でライブネス攻撃が検出されたかどうかを示します。
| N |
authorityComparisonScore | Double | 収集された顔と権威ある比較ソースの比較スコア。有効な値: 0~100。 | 99.99 |
ExtIdInfo
パラメーター | タイプ | 説明 | 例 |
idPassed | String | 顧客がドキュメント検証に合格したかどうかを示します。ドキュメント検証は、ドキュメント光学文字認識 (OCR) も指します。有効な値は次のとおりです。
| N |
ocrIdInfo | String | ドキュメント検証によって返されるフィールド。 説明 ドキュメント検証が失敗した場合、このパラメーターは空です。 | |
spoofInfo | String | なりすまし検出の結果。リスク判定とリスクタイプが含まれます。 説明 カードなりすまし検出は、Initialize リクエストで IdSpoof = Y の場合にのみ有効になります。 それ以外の場合、spoofResult はデフォルトで N になり、spoofType は空です。
| |