このトピックでは、サーバーサイド API のみを使用して ID Verification と統合する方法について説明します。
API の説明
API 操作: EkycVerify
リクエストメソッド: HTTPS POST
説明: 画像データなどのパラメーターを使用して eKYC 認証を実行します。
この 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 で実行してテストを行い、この操作のサンプル SDK コードを生成できます。
入力画像のフォーマット要件
画像フォーマット: JPG、JPEG、または PNG。
画像サイズ: 50 KB~100 KB を推奨します。最大サイズは 1 MB です。
画像解像度: 解像度は 640 × 480 ピクセル (高さ × 幅) から 1920 × 1080 ピクセルの範囲内である必要があります。短い方の辺を 720 ピクセルにスケーリングし、圧縮率を 0.9 以上にすることを推奨します。画像の高さは幅よりも大きくする必要があります。幅が高さより大きい場合、検出精度が低下する可能性があります。
説明画像を Base64 フォーマットに変換すると、データサイズが増加します。Base64 フォーマットでパラメーターを渡すには、1 MB のデータ転送制限を超えないように、元の画像サイズが 0.6 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 | いいえ | ユーザーの実名。 説明
これらの条件を満たし、証明書画像なしで | 田中太郎 |
DocNo | String | いいえ | ユーザーの証明書番号。 説明
これらの条件を満たし、証明書画像なしで | 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 | いいえ | 公式データベースに対する本人確認を有効にするかどうかを指定します:
説明 この機能は現在、中国本土の第 2 世代住民 ID カードでのみ利用可能です。 | F |
IdThreshold | String | いいえ | カスタムの OCR 品質検出のしきい値モード:
| 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.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 | はい | 氏名と ID カード番号が公式データベースの情報と一致しません。ユーザーの情報が間違っているか、偽物である可能性があります。ユーザーに情報を確認してから再試行するよう依頼してください。 説明 このエラーコードは、プロダクトで検証される証明書タイプが中国の ID カードで、権威検証機能が有効になっている場合にのみ返されます。 |
202 | はい | 公式データベースで ID 情報が見つかりません。手動レビューのオプションを提供してください。 説明 このエラーコードは、プロダクトで検証される証明書タイプが中国の ID カードで、権威検証機能が有効になっている場合にのみ返されます。 |
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 | 証明書 OCR からのフィールド情報。 説明 証明書 OCR プロセスが失敗した場合、このフィールドは空になります。 | |
spoofInfo | String | 証明書のなりすまし防止検出の結果。リスク評価結果とリスクタイプが含まれます:
| |