更新日志

版本号 更新日期 更新说明
V1.0.1 2018-7-12 更新接口加密
V1.0.2 2018-7-25 新增模板参数
V1.0.3 2018-9-28 新增“#”说明
V2.0.0 2018-11-18 服务升级,文档更新
V2.1.0 2019-1-11 新增验证码校验接口
V2.1.1 2020-11-9 发送短信状态码增加13xx

签名认证

  1. 用户自己生成 timestamp(Unix 时间戳),单位精确到秒,取整数
  2. 生成随机数nonce(注:最好是32位的)
  3. 将timestamp、nonce、GTID 这三个字符串依据字符串首位字符的ASCII码进行升序排列,如果第一个字符相同则比较下一位,依次类推。将三个字符串join成一个字符串;然后用GTKEY对这个字符串做hamc-sha256 签名,以16进制编码
  4. 将上述得到的签名结果作为signature的值,与GTID, nonce, timestamp 一起放在HTTP HEADER的Authorization中

示例

假设GTID(此为示例ID,请使用极验后台的ID【极验后台->身份认证->短信->概览下方->ID&KEY】) = “xp9mzzxttrrjheg8jtojwskqzz64zq3j”; GTKEY(此为示例KEY,请使用极验后台的KEY)=“h9yldjrzxaeiabtad0kb4ty5ivj7ehr1”;

1. 获得timestamp(unix时间戳),返回timestamp :“ 1531476256”
2. 获得随机nonce,返回nonce: “frxwel0nioxt92smrtn509majr5750lj”
3. 将timestamp、nonce、GTID 这三个字符串依据字符串首位字符的ASCII码进行升序排列,如果第一个字符相同则比较下一位,依次类推。将三个字符串join成一个字符串;
   返回joinstr:”1531476256frxwel0nioxt92smrtn509majr5750ljxp9mzzxttrrjheg8jtojwskqzz64zq3j”
4. 用GTKEY对joinstr做hamc-sha256签名,且以16进制编码,返回signature:“ a4a8a3b68d6d3ba804abdbe4b500e7e225c454a388f345908a72164da8618c56”
5. 将上述的值按照 #{k}=#{v} 并以 ‘,’ join在一起,返回签名认证字符串:
   “Authorization:gt_id=xp9mzzxttrrjheg8jtojwskqzz64zq3j,nonce=frxwel0nioxt92smrtn509majr5750lj,signature=a4a8a3b68d6d3ba804abdbe4b500e7e225c454a388f345908a72164da8618c56,timestamp=1531476256”

签名认证DEMO下载

Python,Java,PHP,Node.js

短信发送接口

请求URL

https://tectapi.geetest.com/message

请求方式

POST

数据类型

application/json

参数

参数名 必选 类型 说明
phone string 手机号(多个手机号用英文逗号隔开,长度一次不要超过5000个)
国内手机号传不带区号的11位手机号码;
国外手机号需要带上对应区号(区号不需要传+号),
例如英国的国际电话区号为+44,手机号为1618505872,手机号传441618505872
modeId string 模板编号,国内和国外的短信需要分别创建不同的模板,并告知极验的工作人员配置对应的通道(对应极验后台模板设置中的模板编号)
arguments dict 模板参数(key为模板中的变量名,val为实际想发送的内容,key和val都为字符串),模板中没有变量时可以不传(示例:'arguments':{'code' :'123qwe'})

返回示例

成功返回

{
    "data":
    {
        "message_status": true
    },
    "status": 200,
    "trade_id":"k51m6b51ja0agmivk8nackvq9gieto0n"
}

失败返回实例

{
    "error_msg": "connection error",
    "status": 2800,
    "trade_id":"k51m6b51ja0agmivk8nackvq9gieto0n"
}

状态码说明

状态码 说明 描述
200 正常 服务器成功处理了请求
1100 缺少身份验证参数 缺少请求头签名认证参数
1101 无效的时间戳 加密参数时间超过十分钟有效期
1102 ID不存在 无效的ID
1103 验证失败 签名认证加密参数验证失败
1104 金额不足 充值金额剩余不足
1105 身份验证参数错误 请求头签名认证参数错误
1200 参数错误 手机号、模板编号至少有一项为空、模板变量不合规定
1300 手机号参数错误 手机号码重复
1301 模板参数错误 无效的模板ID
1302 模板参数错误 模板审核未通过
1303 手机号参数错误 非指定运营商的手机号
1304 内部接口异常 极验内部接口异常
1305 模板变量异常 未配置的模板变量
1306 内部接口异常 验证码设置不成功
1307 手机号参数错误 单次传入手机个数超过5000条
2800 内部接口异常 极验内部接口异常
4000 未知错误 未知错误

验证码校验接口

简要描述

校验短信验证码是否正确(只能校验一次)

请求URL

https://tectapi.geetest.com/checkmessage

请求方式

POST

数据类型

application/x-www-form-urlencode

请求头

参数名 必选 类型 说明
Authorization string 身份验证参数,见签名认证部分

参数

参数名 必选 类型 说明
phone string 手机号
trade_id string 发送验证码短信请求返回的流水号(trade_id)
answer string 验证码短信中的验证码

返回示例

{
    "data": true,
    "status": 200,
    "trade_id": "k51m6b51ja0agmivk8nackvq9gieto0n"
}

返回参数说明

参数名 类型 说明
status int 状态码,200表示成功
data bool true或者false
error_msg str 当请求失败时,会附带返回码,具体见下
trade_id str 当次请求的流水号

状态码说明

状态码 说明 描述
200 正常 服务器成功处理了请求
1100 缺少身份验证参数 缺少请求头签名认证参数
1101 无效的时间戳 加密参数时间超过十分钟有效期
1102 id不存在 无效的ID
1103 验证失败 签名认证加密参数验证失败
1105 身份验证参数错误 请求头签名认证参数错误
1200 参数错误 至少有一个参数为空
1204 没有查到记录 没有查到记录
4000 未知错误 未知错误

短信报告接口

简要描述

获取发送短信的到达报告

请求URL

https://tectapi.geetest.com/message_report

请求方式

POST

数据类型

application/x-www-form-urlencode

请求头

参数名 必选 类型 说明
Authorization string 身份验证参数,见签名认证部分

返回示例

{
    "data": ["91sxyglscl4refpqdkvmjp3dnneo1o5s,13237100223,2019-01-04 18:10:27,2019-01-04 18:10:31,DELIVRD, 100041"],
    "status": 200,
    "trade_id": "k51m6b51ja0agmivk8nackvq9gieto0n"
}

返回参数说明

参数名 类型 说明
status int 状态码,200表示成功
data list 返回数据,最多一次请求返回999条,每条为字符串,格式为"流水号,手机号,发送时间,到达时间,到达状态,模板编号"
error_msg str 当请求失败时,会附带返回码,具体见下
trade_id str 当次请求的流水号

状态码说明

状态码 说明 描述
200 正常 服务器成功处理了请求
1100 缺少身份验证参数 缺少请求头签名认证参数
1101 无效的时间戳 加密参数时间超过十分钟有效期
1102 id不存在 无效的ID
1103 验证失败 签名认证加密参数验证失败
1105 身份验证参数错误 请求头签名认证参数错误
1200 参数错误 模板编号为空
4000 未知错误 未知错误