服务端API接入 - 阿里云验证码

本文向您介绍如何通过HTTPS原生调用的方式完成验证码服务端接入。

HTTPS原生调用方式需要用户自行封装加解签、拼装请求（URL、Body、header、parameters）。如非特殊业务需求，建议使用SDK方式调用，请参见服务端接入。

基本信息

调用服务请求地址：https://captcha.ap-southeast-1.aliyuncs.com
请求方式（HttpMethod）: POST
传输协议：HTTPS

请求参数

请求参数由公共请求参数和API自定义参数组成。公共参数中包含API版本号、身份验证等信息。

公共请求参数：

名称	类型	是否必选	描述	示例值
x-acs-action	String	是	API的名称。	要执行的操作。取值：VerifyIntelligentCaptcha。
x-acs-version	String	是	API 版本。	API版本号，使用 YYYY-MM-DD日期格式。取值：2023-03-05。
Authorization	String	非匿名请求必须	用于验证请求合法性的认证信息，格式为Authorization: SignatureAlgorithm Credential=AccessKeyId,SignedHeaders=SignedHeaders,Signature=Signature。其中SignatureAlgorithm为签名加密方式，为ACS3-HMAC-SHA256。 Credential 为用户的访问密钥ID。您可以在RAM 控制台查看您的 AccessKeyId。如需创建 AccessKey，请参见创建AccessKey。 SignedHeaders为请求头中包含的参与签名字段键名，【说明】：除了Authorization之外，建议对所有公共请求头添加签名，以提高安全性。 Signature为请求签名，取值参见签名机制。	ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=e521358f7776c97df52e6b2891a8bc73026794a071b50c3323388c4e0df64804
x-acs-signature-nonce	String	是	签名唯一随机数。该随机数用于防止网络重放攻击，每一次请求都必须使用不同的随机数。	d410180a5abf7fe235dd9b74aca91fc0
x-acs-date	String	是	按照ISO 8601标准表示的UTC时间，格式为yyyy-MM-ddTHH:mm:ssZ，例如2018-01-01T12:00:00Z。值为请求发出前15分钟内的时间。	2023-10-26T09:01:01Z
host	String	是	即服务地址，参见HTTP 请求结构。	captcha.cn-shanghai.aliyuncs.com
x-acs-content-sha256	String	是	请求正文Hash摘要后再base-16编码的结果，与HashedRequestPayload一致。	e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-security-token	String	STS认证必传	为调用AssumeRole接口返回值中SecurityToken的值。

API请求参数以application/x-www-form-urlencoded表单形式，放到body里面上传：

名称	类型	是否必选	描述	示例值
CaptchaVerifyParam	String	是	由验证码脚本回调的验证参数，直接将全部参数信息由客户端传给服务端即可。警告禁止对验证参数做任何修改，否则业务会报错。	V2架构示例值：{"sceneId":"xxxxxx","certifyId":"xxxxxx","deviceToken":"xxxxxxx==","data":"xxxxxx==","..."} V3架构示例值：eyJjZXxxxxxxxxxxxxxxnVlfQ==
SceneId	String	否	由您服务端写入本次验证对应的场景ID，建议传入，尤其在多场景下，防止前端被篡改为其他场景。	Udw***d72

签名机制

阿里云验证码会对每个API请求进行身份验证，提交请求时需要在请求中包含签名（Signature）信息。

阿里云验证码通过使用AccessKey ID和AccessKey Secret进行对称加密的方法来验证请求的发送者身份。AccessKey是为阿里云账号和RAM用户发布的一种身份凭证（类似于用户的登录密码），其中AccessKey ID 用于标识访问者的身份，AccessKey Secret是用于加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密。具体操作，请参见V3签名机制。

返回参数

名称			类型	描述
HTTP Status Code			Integer	HTTP状态码。更多信息，请参见返回参数说明。
HTTP Body	RequestId		String	请求ID。
	Success		Boolean	请求是否成功。 true：表示请求成功。 false：表示请求失败。
	Code		String	返回码。更多信息，请参见返回参数说明。
	Message		String	返回详细信息。更多信息，请参见返回参数说明。
	Result	VerifyResult	Boolean	验证结果。 true：表示验证通过。 false：表示验证不通过。
		VerifyCode	String	T001	服务端校验通过。
				T005	控制台开启测试模式，且配置了验证通过。如有疑问，请登录验证码2.0控制台查看对应场景的策略状态的配置。具体操作请参见接入指引。
				F001	疑似攻击请求，风险策略不通过。
				F002	您传入的`CaptchaVerifyParam`参数为空，`CaptchaVerifyParam`是由前端自动获取并传给您的服务端，服务端不能做任何更改，直接传给阿里云。请参考服务端接入检查您的集成代码。
				F003	您传入的`CaptchaVerifyParam`格式不合法，`CaptchaVerifyParam`是由前端自动获取并传给您的服务端，服务端不能做任何更改，直接传给阿里云。请参考服务端接入检查您的集成代码。
				F004	控制台开启测试模式，且配置了验证不通过。如有疑问，请登录验证码2.0控制台查看对应场景的策略状态配置。具体操作请参见场景管理。
				F005	CaptchaVerifyParam中的场景ID（sceneId）不合法，CaptchaVerifyParam是由前端自动获取并传给您的服务端，服务端不能做任何更改，直接传给阿里云。请参考服务端接入检查您的集成代码。
				F006	`CaptchaVerifyParam`中的场景ID（sceneId）不合法，前端集成需要传入您账户创建的场景ID，请登录验证码2.0控制台查看场景配置。
				F008	验证数据重复提交。同一笔验证码请求只允许提交一次。
				F009	检测到虚拟设备环境，请检查是否使用vmware、virtualbox、hyper-v、parallels等虚拟机，avd、blue stacks、vbox/hyper-v等模拟器，桌面浏览器模拟移动设备等。如不需要拦截，请登录验证码2.0控制台自定义策略中关闭，具体操作请参见设置自定义策略。
				F010	同IP访问频率超出限制。如果需要自定义频率阈值，请登录验证码2.0控制台自定义策略进行配置，具体操作请参见设置自定义策略。
				F011	同设备访问频率超出限制。如果需要自定义频率阈值，请登录验证码2.0控制台自定义策略进行配置，具体操作请参见设置自定义策略。
				F012	您服务端参数里传入的SceneID需要与前端配置的场景ID（SceneId）保持一致。
				F013	您传入的`CaptchaVerifyParam`缺少参数，`CaptchaVerifyParam`是由前端自动获取并传给您的服务端，服务端不能做任何更改，直接传给阿里云。请参考发起认证请求检查您的集成代码。
				F014	无初始化记录，可能存在两种原因：验证请求和初始化请求间隔超出20分钟时间，后端会删除初始化记录，请重新发起初始化请求进行尝试。不存在初始化记录，疑似攻击请求，或者接入异常，发起验证请求前需先发起客户端初始化请求。
				F015	验证交互不通过。例如拼图没有滑动到正确位置，可以刷新验证码重新完成交互。
				F016	控制台自定义策略配置URL验证导致不通过，请登录验证码2.0控制台自定义策略中URL验证策略进行调整，具体操作请参见设置自定义策略。
				F017	疑似攻击请求，协议或参数异常不通过。
				F018	V3架构下，业务验签请求入参CaptchaVerifyParam重复使用。
				F019	V3架构下，行为验证请求和业务验签请求间隔超出90秒或未发起行为验证就直接进行业务验签请求。
				F020	V3架构下，业务验签请求的CaptchaVerifyParam与场景ID或用户不匹配。
				F023	在V2架构中，若初始化失败，将自动触发验证请求。当该请求校验未通过时，将返回此状态码。此过程属于容灾机制，不产生计费。
				F024	检测到自动化脚本模拟点击、滑动等操作行为。若当前为引入 touch-emulator 以在桌面端模拟触摸事件的 Vue 应用，或其他存在合法模拟点击场景的业务，请勿启用拦截。如无需拦截此类行为，请在自定义策略中关闭拦截模拟点击行为，具体操作请参见设置自定义策略。
				F025	基于Qwen大模型智能分析检出的异常请求，若不希望启用AI大模型安全能力，可通过如下方式关闭：登录验证码控制台。进入概览页，单击右上角产品卡片中的展开详情。单击AI智能安全防护开关。
		CertifyID	String	若初始化传入自定义CertifyID参数（UserCertifyId），该值将透传自定义CertifyID，支持客户关联校验。若初始化未传入自定义CertifyID参数，该值将展示服务端生成的默认CertifyID，用于标识验证码单次验证周期。

返回参数HTTP Status Code、Code、Message的详细说明，如下表所示。

HTTP Status Code	Code	Message
200	Success	成功。
400	MissingParameter	缺少必须参数。
401	InvalidParameter	参数不合法。
403	Forbidden.AccountAccessDenied	无权限，可能是未开通服务，或已欠费。
403	Forbidden.RAMUserAccessDenied	RAM用户无权限，请授权 AliyunYundunAFSFullAccess。具体操作，请参见管理RAM角色的权限。
500	InternalError	系统内部错误，建议重试。若重试仍失败，建议默认放行以保障业务可用性，具体请参见业务容灾处理建议。

返回示例：

{
  "RequestId": "3F290236-C***B-54F31BD999FF",
  "Message": "success",
  "Code": "Success",
  "Success": true,
  "Result": {
    "VerifyResult": true,
    "VerifyCode": "T001"
  }
}

异常处理：

为了保障业务可用性，建议您在调用本接口时，如果出现请求失败或网络异常，打印日志，并默认认为验证通过，优先保证业务可用，然后尽快联系我们排查异常原因。