服务端接入
更新时间：2026-07-07 15:59:25
| 日期 | 版本 | 修订内容摘要 |
|---|---|---|
| 2023-09-07 | v1.0.0 | 新增接口文档 |
一、Web 及 App接入
1、接口描述
- 请求协议：https
- 请求方式：post
- Content-Type：multipart/form-data
- 接口地址：https://api.253.com/open/txyzm/yzm-v2
2、输入参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| appId | string | 应用 id |
| appKey | string | 应用 key |
| AppSecretKey | string | 验证码密钥 |
| CaptchaAppId | string | 验证码 appId |
| RendStr | string | 验证票据需要的随机字符串 |
| Ticket | string | 验证码返回给用户的票据 |
| IP | string | 用户操作来源的外网 IP |
输出参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| chargeStatus | string | 是否收费 1 收费，0 不收费 |
| message | string | 响应code码解释 |
| tradeNo | string | 交易流水号 |
| CaptchaMsg | string | 状态描述及验证错误信息 注意：此字段可能返回 null，表示取不到有效值。 |
| EvilLevel | string | [0,100]，恶意等级 注意：此字段可能返回 null，表示取不到有效值。 |
| RequestId | string | 验证码系统返回的唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。 |
| CaptchaCode | string | 1 OK 验证通过 6 user code len error 验证码长度不匹配 7 captcha no match 验证码答案不匹配/Randstr 参数不匹配（建议重新生成 Randstr、Ticket 进行校验。） 8 verify timeout 验证码签名超时（Ticket票据过期，前端生成Ticket后，有效时长为5分钟） 9 Sequnce repeat 验证码签名重放（Ticket票据被重复校验，建议重新生成 Randstr、Ticket 进行校验） 10 Sequnce invalid 验证码签名序列 11 Cookie invalid 验证码 cooking 信息不合法 12 sig len error 签名长度错误 13 verify ip no match ip 不匹配 15 decrypt fail 验证码签名解密失败（以下情况均可导致该错误发生：1.CaptchaType 不等于9。2.Randstr 或 Ticket 所填写的值和前端生成的不一致。3.userIP 不合法。4.CaptchaAppId、AppSecretKey 填写有误。） 16 appid no match 验证码强校验 appid 错误（CaptchaAppId错误，前端代码 data-appid 和后端 CaptchaAppId 所填写的值，都必须和验证码应用中 CaptchaAppId （验证id）一致） 17 cmd no much 验证码系统命令不匹配 18 uin no match 号码不匹配 19 seq redirect 重定向验证 20 opt no vcode 操作使用 pt 免验证码校验错误 21 diff 差别，验证错误 22 captcha type not match 验证码类型与拉取时不一致 23 verify type error 验证类型错误 24 invalid pkg 非法请求包 25 bad visitor 策略拦截 26 system busy 系统内部错误 100 param err appsecretkey 参数校验错误 |
| EvilBitmap | string | 风控拦截策略 注意：此字段可能返回 null，表示取不到有效值， 0：空秒拨代理IP异常 1：IP短时聚集异常（短时间内多次发起验证） 2：AppId+IP短时聚集异常（短时间内多次发起验证） 3：AppId+IP+设备短时聚集异常（短时间内多次发起验证） 4：流量特征异常（比如TCP协议栈信息异常） 5：数据参数异常（比如浏览器参数异常） 6：蜜罐异常（执行了不该执行的逻辑） 7：行为聚类异常 |
| code | string | 响应 code 码 200000 请求成功 400001 参数校验异常 400101 商户信息不存在 400102 商户 IP 地址不合法 400200 黑名单列表 400201 手机号码不能为空 400901 账户信息不存在 400902 应用类型信息不存在 403000 用户校验失败 403101 账户被系统禁用 403102 账户未激活 415000 请求数据转换异常 500000 系统异常 500002 数据处理异常 500003 业务操作失败 500004 远程调用失败 500005 账户余额异常 500006 请求外部系统失败 500901 邮箱未设置 500902 账户信息已存在 500903 账户相关能力已激活 504000 系统超时 510101 用户产品可用数量不足 |
返回示例:
正常:
{
tradeNo: "656221037519835137",
chargeStatus: 1,
message: "成功",
data: {
CaptchaMsg: "OK",
EvilLevel: "0",
EvilBitmap: "0",
RequestId: "984d6957-902c-4be8-af3a-012309b63d80",
CaptchaCode: "1"
},
code: "200000"
}验证码 CaptchaAppId、AppSecretKey 错误:
{
tradeNo: "656198616582455296",
chargeStatus: 1,
message: "成功",
data: {
CaptchaMsg: "SecretKeyCheck Error",
EvilLevel: "0",
EvilBitmap: "null",
RequestId: "e82f459a-cbf5-4167-9a9e-1d2c1bbdf9bd",
CaptchaCode: "100"
},
code: "200000"
}验证码 ticket 超时，需要重新获取:
{
tradeNo: "656221420577095680",
chargeStatus: 1,
message: "成功",
data: {
CaptchaMsg: "verify timeout",
EvilLevel: "0",
EvilBitmap: "null",
RequestId: "060352db-3767-4a3c-bd31-3beb624b17ce",
CaptchaCode: "8"
},
code: "200000"
}Ticket 和 rendStr 不一致，返回示例:
{
tradeNo: "656222083289710592",
chargeStatus: 1,
message: "成功",
data: {
CaptchaMsg: "decrypt fail",
EvilLevel: "0",
EvilBitmap: "null",
RequestId: "593dd626-8563-4f4d-9f17-6fe3a216937a",
CaptchaCode: "15"
},
code: "200000"
}二、微信小程序接入
1、接口描述
- 请求协议：https
- 请求方式：post
- Content-Type：multipart/form-data
- 接口地址：https://api.253.com/open/txyzm/yzmMini-v2
2、输入参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| appId | string | 应用 id |
| appKey | string | 应用 key |
| AppSecretKey | string | 验证码密钥 |
| CaptchaAppId | string | 验证码 appId |
| Ticket | string | 验证码返回给用户的票据 |
| IP | string | 用户操作来源的外网 IP |
输出参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| chargeStatus | string | 是否收费 1 收费，0 不收费 |
| message | string | 响应code码解释 |
| data | string | 返回结果 |
| CaptchaCode | string | 1 ticket verification succeeded 票据验证成功 7 CaptchaAppId does not match 票据与验证码应用APPID不匹配 8 ticket expired 票据超时 10 ticket format error 票据格式不正确 15 ticket decryption failed 票据解密失败 16 CaptchaAppId wrong format 检查验证码应用APPID错误 21 (1)ticket error 票据验证错误 (2)diff 一般是由于用户网络较差，导致前端自动容灾，而生成了容灾票据，业务侧可根据需要进行跳过或二次处理 25 invalid ticket 无效票据 26 system internal error 系统内部错误 31 UnauthorizedOperation.Unauthorized 无有效套餐包/账户已欠费 100 param err 参数校验错误 示例值：8 |
| CaptchaMsg | string | 状态描述及验证错误信息 注意：此字段可能返回 null，表示取不到有效值。 示例值：ticket expired |
| RequestId | string | 唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。 |
| code | string | 响应 code 码 200000 请求成功 400001 参数校验异常 400101 商户信息不存在 400102 商户 IP 地址不合法 400200 黑名单列表 400201 手机号码不能为空 400901 账户信息不存在 400902 应用类型信息不存在 403000 用户校验失败 403101 账户被系统禁用 403102 账户未激活 415000 请求数据转换异常 500000 系统异常 500002 数据处理异常 500003 业务操作失败 500004 远程调用失败 500005 账户余额异常 500006 请求外部系统失败 500901 邮箱未设置 500902 账户信息已存在 500903 账户相关能力已激活 504000 系统超时 510101 用户产品可用数量不足 |
返回示例:
正常:
{
"chargeStatus": 1,
"message": "成功",
"data": {
"CaptchaCode": "1",
"CaptchaMsg": "ticket verification succeeded",
"RequestId": "d9faaf84-02c3-484c-a24c-3fa6a2556be4"
},
"code": "200000"
}验证码 CaptchaAppId、AppSecretKey 错误:
{
"chargeStatus": 1,
"message": "成功",
"data": {
"CaptchaCode": "31",
"CaptchaMsg": "Uin-CaptchaAppId不匹配，请检查使用的CaptchaAppId是否属于对应的账户/子账户",
"RequestId": "f2d03160-86b2-4a23-876a-908d3b8f551e"
},
"code": "200000"
}验证码 ticket 超时，需要重新获取:
{
"chargeStatus": 1,
"message": "成功",
"data": {
"CaptchaCode": "8",
"CaptchaMsg": "ticket expired 详情请参考输出参数中CaptchaCode字段的具体描述",
"RequestId": "3dafd257-c036-4d3f-8f80-75ed7fa2f9cc"
},
"code": "200000"
}Ticket错误，返回示例:
{
"chargeStatus": 1,
"message": "成功",
"data": {
"CaptchaCode": "15",
"CaptchaMsg": "ticket decryption failed 详情请参考输出参数中CaptchaCode字段的具体描述",
"RequestId": "98e87d2a-746f-40de-8460-87cead75549b"
},
"code": "200000"
}code码解释
code码解释见：code码解释
这篇文档对您有帮助吗？
