文档

HTTPS接入服务端

更新时间:
一键部署
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

本文向您介绍如何通过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 CodeCodeMessage的详细说明,如下表所示。

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"
  }
}

异常处理:

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