本文介绍如何通过调用Initialize接口发起eKYC-PRO请求。
接口信息
接口名:Initialize
请求方法:HTTPS POST
接口说明:每次开始eKYC_PRO认证流程前,通过本接口获取transactionId,用来串联认证请求中的各个接口。
QPS限量:API独享QPS限量,详情请参见ID Verification服务端API QPS限量说明。
服务地址:
说明内网访问优势:内网指阿里云同一地域内各产品间的私有通信网络。若您的业务服务器部署于阿里云对应地域,请使用内网域名访问 ID Verification 服务,以获得更安全、稳定的通信质量。
海外访问优化建议:海外网络环境复杂,建议参考服务端网络耗时分析与优化,优化集成方案,降低网络延迟及请求失败概率。
新加坡
公网:
cloudauth-intl.ap-southeast-1.aliyuncs.com内网:
cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com
印度尼西亚
公网:
cloudauth-intl.ap-southeast-5.aliyuncs.com内网:
cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com
中国香港
公网:
cloudauth-intl.cn-hongkong.aliyuncs.com内网:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
马来西亚(吉隆坡)
公网:
cloudauth-intl.ap-southeast-3.aliyuncs.com内网:
cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com
在线调试和集成
在调试和集成前,请确保您已完整阅读使用OpenAPI调试和集成服务端API文档,充分了解API接口在OpenAPI平台的调用方式和SDK及其代码的获取方式。
您可以在OpenAPI Explorer中直接运行本接口进行调试,并生成本接口的SDK代码示例。
请求参数
名称 | 类型 | 是否必选 | 描述 | Example |
ProductCode | String | 是 | 要接入的产品方案。取值: eKYC_PRO:使用eKYC_PRO产品方案,您的用户需要完成证件识别和活体认证整个流程。 | eKYC_PRO |
SceneCode | String | 否 | 您自定义的认证场景ID,用于后续控制台输入此场景ID查询相关记录。支持长度为10位的字母、数字或下划线的组合。 | 1234567890 |
MerchantBizId | String | 是 | 您自定义的业务唯一标识,用于后续定位排查问题。支持长度为32位的字母和数字的组合,请确保唯一。 说明 阿里云服务器不会对该字段的值进行唯一性检查。为了更好地跟踪,强烈建议保证字段唯一性。 | e0c34a77f5ac40a5aa5e6ed20c35**** |
MetaInfo | String | 是 | MetaInfo环境参数,需要通过客户端SDK获取。 请参考对应平台的客户端SDK接入文档,获取MetaInfo。 说明 无须修改返回值,直接透传即可。 | |
MerchantUserId | String | 是 | 您自定义的用户ID,或者其他可以识别特定用户的标识,例如手机号码、邮箱地址等。强烈建议对该字段的值进行预先脱敏,例如对值进行哈希处理。 | 123456789 |
IdSpoof | String | 否 | 是否开启证件防伪检测功能:
| Y |
DocType | String | 是 | 证件类型。 您可以在证件类型表中查询支持的证件编码;在证件OCR字段表中查询每种证件的ORC返回字段详情。 重要 受地域模型限制,不同地域支持识别的证件类型不一致。
| GLB03001 |
SecurityLevel | String | 否 | 代表认证流程不同安全水位的模式,可选值:
| 02 |
IdThreshold | String | 否 | 自定义OCR质量检测阈值模式:
| 0 |
Model | String | 否 | 要进行活体检测的类型:
说明 支持集成的SDK版本,请参见SDK发布记录。 | PHOTINUS_LIVENESS |
DocVideo | String | 否 | 是否需要存证视频。
说明 因为视频文件较大,当网络不稳定时系统会丢弃视频文件,优先保障认证必要图片传输。 | N |
CallbackUrl | String | 否 | 认证结果的回调通知地址,回调请求方式默认为GET,回调地址必须以
警告
| https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200 |
CallbackToken | String | 否 | 安全Token,由您自行生成,用于防重复、防篡改校验。 如果设置了此值,将会在CallbackUrl回调时携带CallbackToken字段。 | NMjvQanQgplBSaEI0sL******** |
AppQualityCheck | String | 否 | 是否开启人脸严格质量检测。
重要
| N |
Pages | String | 否 | 采集页配置,多页使用
| 01 |
ShowGuidePage | String | 否 | 是否展示引导页面开关:
| 1 |
DocScanMode | String | 否 | OCR证件扫描模式:
| shoot |
Authorize | String | 否 | 是否启用权威数据源核验以增强证件防伪能力。仅当IdSpoof参数设置开启时,该参数适用。
说明
| T |
Mobile | String | 否 | 传入印度尼西亚电话号码,需校验格式(以+62开头,后接9-11位数字),此字段仅在 说明 该字段仅在开启印尼数据源时必传。 | +6281293671234 |
String | 否 | 用户电子邮件地址。此字段仅在 说明 该字段仅在开启印尼数据源时必传。 | a*@gmail.com |
返回数据
名称 | 类型 | 描述 | 示例值 | |
HTTP Status Code | Integer | HTTP状态码。 | 200 | |
HTTP Body | RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF03**** |
Code | String | Success | ||
Message | String | 返回Code的详细描述。 | success | |
Result.TransactionId | String | 整个认证流程的唯一标识。该字段为计费统计字段,并用于发起CheckResult接口请求。 重要
| hksb7ba1b28130d24e015d6******** | |
Result.Protocol | String | 认证标准加密协议。 建议获取该参数并传递给客户端 SDK。客户端 SDK 将基于此参数减少网络交互,并支持动态网络切换,以提升用户体验。 | hksb7ba1b28130d24e015d********* | |
返回Code
HTTP状态码 | Code | Message描述 |
200 | Success | 请求成功。 |
400 | MissingParameter | 参数不能为空。 |
InvalidParameter | 非法参数。 | |
401 | Forbidden.ExceptionRepeatedInvoke | 异常重复调用次数超限。 |
403 | Forbidden.RAMUserAccessDenied | 需要给RAM用户授予AliyunAntCloudAuthFullAccess操作权限。更多信息,请参见授权RAM用户访问服务。 |
Forbidden.AccountAccessDenied | 确保您开通了ID verifycation,并且保证账户未欠费。 | |
Throttling.Api | API限流拦截。 | |
500 | InternalError | 系统内部错误,请反馈工程师排查。 |
503 | ServiceUnavailable | 服务不可用,请反馈工程师排查。 |