このトピックでは、サーバー側の API のみを使用して ID Verification と統合する方法について説明します。
API の説明
API 操作: EkycVerify
リクエストメソッド: HTTPS POST
説明: 画像データなどのパラメーターを使用して eKYC 認証を実行します。
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 Explorer で API を呼び出し、SDK とそのコードを取得する方法を理解してください。
この API 操作は、OpenAPI Explorer で実行してテストを行い、この操作用のサンプル SDK コード を生成できます。
画像形式の要件
画像形式: JPG、JPEG、または PNG。
画像サイズ: 50 KB ~ 100 KB の画像サイズをお勧めします。 最大サイズは 1 MB を超えることはできません。
画像解像度: 解像度は 1920 × 1080 ピクセル (H × W) を超えることはできず、少なくとも 640 × 480 ピクセル (H × W) である必要があります。 短い方の辺を 720 ピクセルに、圧縮率を 0.9 以上にスケーリングすることをお勧めします。 画像の高さは幅よりも大きくする必要があります。 幅が高さよりも大きい場合、検出精度に影響する可能性があります。
説明画像は base64 形式に変換されると、通常、データサイズが増加します。 base64 形式でパラメーターを渡すには、元の画像サイズが 0.6 MB を超えないようにして、最大データ転送制限の 1 MB を満たすようにしてください。
画像品質に関する推奨事項:
顔は完全で、鮮明で、遮るものがなく、カメラに直接向いている必要があります。前面カメラで撮影した顔画像を使用することをお勧めします。
顔は画像領域の 60% 以上を占める必要があります。顔が小さいと、検出精度に影響する可能性があります。
画像に複数の顔がある場合、アルゴリズムはデフォルトで最大の顔をトリミングします。 複数の顔がある画像は渡さないようにしてください。
リクエストパラメーター
名前 | タイプ | 必須 | 説明 | 例 |
ProductCode | String | はい | 統合するプロダクトソリューション。 値を eKYC_MIN に設定します。 | eKYC_MIN |
SceneCode | String | いいえ | カスタム認証シナリオ ID。 この ID を使用して、コンソールで関連レコードをクエリできます。 ID は最大 10 文字で、文字、数字、およびアンダースコア (_) を含めることができます。 | 1234567890 |
MerchantBizId | String | はい | カスタマイズする一意のビジネス識別子。 問題の特定とトラブルシューティングに使用されます。 識別子は最大 32 文字で、文字と数字を含めることができます。 識別子が一意であることを確認してください。 | e0c34a77f5ac40a5aa5e6ed20c35**** |
MerchantUserId | String | はい | カスタム ユーザー ID または特定のユーザーを識別できる他の識別子 (携帯電話番号やメールアドレスなど)。 このフィールドの値は、事前にハッシュ化などして機密化してください。 | Y |
DocType | String | はい | 証明書のタイプ。8 桁の数字で一意に識別されます。 詳細については、「証明書のタイプ」をご参照ください。 | 01000000 |
DocName | String | いいえ | ユーザーの実名。 説明 Authorize が T に設定されていて、証明書のタイプが中国本土の居住者 ID カードの場合、次の情報のグループの少なくとも 1 つを入力する必要があります。
| Zhang San |
DocNo | String | いいえ | ユーザーの証明書番号。 説明 Authorize が T に設定されていて、証明書のタイプが中国本土の居住者 ID カードの場合、次の情報のグループの少なくとも 1 つを入力する必要があります。
| 411xxxxxxxxxxx0001 |
IdOcrPictureBase64 | String | いいえ 説明 IdOcrPictureBase64 または IdOcrPictureUrl のいずれかを指定する必要があります。 | 証明書画像の Base64 エンコーディング。 説明 このメソッドを使用して証明書画像を渡す場合は、画像サイズを確認してください。 サイズが大きすぎる画像は渡さないでください。 | Base64 エンコーディング |
IdOcrPictureUrl | String | いいえ | 証明書画像の URL。 URL は、インターネット経由でアクセスできる HTTP または HTTPS リンクである必要があります。 | https://*** |
FacePictureBase64 | String | いいえ 説明 FacePictureBase64 または FacePictureUrl のいずれかを指定する必要があります。 | ポートレート画像の Base64 エンコーディング。 説明 このメソッドを使用して証明書画像を渡す場合は、画像サイズを確認してください。 サイズが大きすぎる画像は渡さないでください。 | Base64 エンコーディング |
FacePictureUrl | String | いいえ | ポートレート画像の URL。 URL は、インターネット経由でアクセスできる HTTP または HTTPS リンクである必要があります。 | https://*** |
Crop | String | いいえ | 顔画像をトリミングするかどうかを指定します。
| F |
Authorize | String | いいえ | 公式データベースに対する ID 検証を有効にするかどうかを指定します。
説明 この機能は現在、中国本土の第 2 世代居住者 ID カードに対してのみ使用できます。 | F |
IdThreshold | String | いいえ | カスタム OCR 品質検出しきい値モード:
| 0 |
証明書のタイプ
DocType | 対応する証明書 |
01000000 | 国際パスポート |
00000006 | 香港身分証明書 (2003 年版) |
00000008 | 香港身分証明書 (2018 年版) |
00000007 | 香港・マカオへの出入国許可証 |
00000009 | 香港・マカオ居住者向け中国本土旅行許可証 |
000000011 | マカオ身分証明書 |
000000012 | 台湾居住者向け中国本土旅行許可証 |
00000001 | 中国本土の第 2 世代居住者 ID カード |
レスポンスパラメーター
名前 | タイプ | 説明 | 例 | |
HTTP ステータスコード | Integer | HTTP ステータスコード。 | 200 | |
HTTP 本文 | RequestId | String | リクエスト ID。 | 130A2C10-B9EE-4D84-88E3-5384FF0**** |
Code | String | Success | ||
Message | String | 応答コードの詳細な説明。 | 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 検証を有効化し、アカウントに支払い遅延がないことを確認してください。 | |
Throttling.Api | 速度制限により API リクエストがブロックされています。 | |
500 | InternalError | 内部システムエラーです。 トラブルシューティングのためにエンジニアにフィードバックを提供してください。 |
ResultObject.SubCode のエラーコード
エラーコード | 請求対象 | 説明、原因、および提案 |
200 | はい | 認証に合格しました。 |
201 | はい | 名前と ID カード番号が公式データベースの情報と一致しません。 ユーザーの情報が間違っているか、偽造されている可能性があります。 ユーザーに情報を確認して再試行するように依頼してください。 |
202 | はい | 公式データベースで ID 情報が見つかりません。 手動レビューのオプションを提供してください。 |
203 | はい | 写真が見つからないか、使用できません。 考えられる原因: 権限のある比較ソースに基本写真が登録されていません。 手動レビューのオプションを提供してください。 |
204 | はい | 顔照合に失敗しました。 画像の人物が同一人物でないか、ライブネス写真の品質が低い可能性があります。 |
205 | はい | 生体検知中にリスクが検出されました。 |
207 | はい | アップロードされた顔が公式データベースの顔と一致しません。 画像の人物が同一人物でないか、顔写真の品質が低い可能性があります。 |
209 | はい | 権限のある比較ソースが異常です。 |
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 | 証明書 OCR からのフィールド情報。 説明 証明書 OCR プロセスが失敗した場合、このフィールドは空になります。 | |
spoofInfo | String | 証明書のなりすまし防止検出の結果。リスク評価結果とリスクタイプが含まれます。
| |