服务端API接入_验证码(Captcha)-阿里云帮助中心

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

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

基本信息

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

请求参数

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

公共请求参数：

名称	类型	是否必须	描述
Format	String	否	返回消息的格式。取值： JSON（默认值） XML
Version	String	是	API版本号，使用 YYYY-MM-DD日期格式。取值：2023-03-05。
Action	string	是	要执行的操作。取值：VerifyIntelligentCaptcha。
AccessKeyId	String	是	访问服务使用的密钥 ID。
Signature	String	是	签名结果串，具体签名方式见下方。
SignatureMethod	String	是	签名方式。取值：HMAC-SHA1。
Timestamp	String	是	请求的时间戳，为日期格式。使用 UTC 时间按照 ISO8601标准，格式为 YYYY-MM-DDThh:mm:ssZ。例如，北京时间2013年1月10日20点0分0秒，表示为2013-01-10T12:00:00Z。
SignatureVersion	String	是	签名算法版本，取值：1.0。
SignatureNonce	String	是	唯一随机数，用于防止网络重放攻击。在不同请求间要使用不同的随机数值。

API请求参数：

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

签名机制

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

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

返回参数

名称			类型	描述
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	原因码。 F001：验证不通过。 F002：您传入的CaptchaVerifyParam参数为空。 F003：您传入的CaptchaVerifyParam格式不合法，请参考集成文档检查您的集成代码。 F004：控制台开启测试模式下的验证不通过。 F005：场景ID不存在。 F006：场景ID不归属该账户。 F007：验证超出时间限制。 F008：验证数据重复提交。 F009：检测到虚拟设备环境，请使用真实设备。 F010：同IP访问频率超出限制。 F011：同设备访问频率超出限制。 F012：您传入的SceneID与CaptchaVerifyParam内的场景ID不一致。 F013：您传入的CaptchaVerifyParam缺少参数。

返回参数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"
  }
}

异常处理：

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