This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
云码平台 - 商家接入文档
商家 API 接口 根地址
测试环境：https://test-api.code92.top
阅读 API 功能文档
商家身份鉴权
几乎所有的 API 都要求验证权限，请在 HTTP 请求头中添加您账号的 JWT Token ：
- Header Key：Authorization
- Header Value：XXXXXXXXXXX （查看商家授权令牌）
短信接码流程
获取手机号
方式一：主动取号（文档）
成功响应示例：
{
"code": "succeed", // 使用if ( code == "succeed" ) 判定获取成功。
"data": {
"callingCode": 66, // 国际电联ITU-T E.164 callingcodes https://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.164D-11-2011-PDF-E.pdf
"id": 552149995081733, // 业务流水号，存下来，在后续的接口调用中要传入。
"phoneNumber": "858683974" // 去除callingCode前缀的电话号码
}
}
失败响应示例：
{
"code": "unexpected", // 错误码
"msg": "外部接口异常 0|-1" // 错误原因
}
方式二：自动取号推送
i. 添加取号需求
ii. 添加推送地址
iii. 控制取号开启/停止（文档）
获取验证码
方式一：主动获取（文档），此步骤需要多次尝试，建议设定请求间隔为5s，持续5min
取到码响应示例：
{
"code": "succeed",
"data": {
"receiveStatus": "received", // 如果取到短信验证码 此字段值为 “received”
"smsCode": "1234" // 短信验证码
}
}
未取到码示例：
{
"code": "succeed",
"data": {
"receiveStatus": "waiting" // 如果是waiting，或者executing ，说明还在取码中，可等待几秒再调用此接口
}
}
{
"code": "succeed",
"data": {
"receiveStatus": "timeout" // 如果是timeout，说明长时间未收到验证码，系统已经自动释放了该手机号，不会再去收码了。
}
}
方式二：接码自动推送（添加推送地址）
报告验证码错误
如您收到验证码输入目标程序后提示验证码不正确，可调用此接口（文档）上报，将该次任务状态重置为waiting， 之后继续执行步骤3，直到状态为received，即收到了新的正确的验证码。
释放手机号
如果调用步骤2多次未获取到验证码，需要放弃此号继续做下一个任务时，请调用此接口（文档），释放手机号之后即停止计费，避免损耗。
拉黑手机号
如果不希望获取到某个手机号，可以调用此接口（文档）拉黑，拉黑之后可确保24小时内不会再次取到此手机号。
邮箱接码流程
获取邮箱号
成功响应示例：
{
"code": "succeed", // 使用if ( code == "succeed" ) 判定获取成功。
"data": {
"email": "kerwinnskinnerroman@gmail.com", // email 地址
"id": 552154460643333 // 业务流水号，存下来，在后续的接口调用中要传入。
}
}
失败响应示例：
{
"code": "unexpected", // 错误码
"msg": "无可用邮箱号"// 错误原因
}
获取邮件码
方式一：主动获取（文档），此步骤需要多次尝试，建议设定请求间隔为5s，持续5min
取到码响应示例：
{
"code": "succeed",
"data": {
"receiveStatus": "received", // 如果取到邮件验证码 此字段值为 “received”
"mailCode": "1234" // 邮件验证码
}
}
未取到码示例：
{
"code": "succeed",
"data": {
"receiveStatus": "waiting" // 如果是waiting，或者executing ，说明还在取码中，可等待几秒再调用此接口
}
}
{
"code": "succeed",
"data": {
"receiveStatus": "timeout" // 如果是timeout，说明长时间未收到验证码，系统已经自动释放了该邮箱号，不会再去收码了。
}
}
方式二：接码自动推送（添加推送地址）
报告验证码错误
如您收到验证码输入目标程序后提示验证码不正确，可调用此接口（文档）上报，将该次任务状态重置为waiting， 之后继续执行步骤3，直到状态为received，即收到了新的正确的验证码。
拉黑邮箱号
如果不希望获取到某个邮箱号，可以调用此接口（文档）拉黑，拉黑之后可确保24小时内不会再次取到此邮箱号。
数据订阅推送
如果您拥有支持公网访问的 Web 服务器，还可以 订阅数据推送 ，支持各类订阅各类事件推送。
通知方式也是通过 HTTP 请求传递到您的 Web 服务器。
推送协议
| Request Method | Request Url | Request Header | Request Body |
|---|---|---|---|
| POST | 设置用于接收数据推送的 URL 地址 | CLOUD-CODE-TIMESTAMP: 时间戳 CLOUD-CODE-SIGN: 签名 Content-Type: application/json |
{ "pushType": DataPushTypes , "pushData": 推送数据 } |
签名校验
为了确保数据由本平台发出且未经篡改送达您的服务器， 请按照以下方式校验签名，抛弃签名不符以及时间戳误差过大的非法请求：
( 您的用户标识 + Header["CLOUD-CODE-TIMESTAMP"] + ReuqestBody ).MD5(UTF8) = Header["CLOUD-CODE-SIGN"]
例如您的用户标识为：26849160-3e36-46fb-b51c-2def0655f195
收到的请求时间戳为：1723276087
收到的请求内容为：{"name":"cloud-code"}
则签名串为
26849160-3e36-46fb-b51c-2def0655f1951723276087{"name":"cloud-code"}
经过md5哈希运算的签名值为：
aadb0544aa76e57ed86481870a21f8d2
推送事件
点击链接进入文档页面 CTRL+F 搜索
| 事件类型 | 类型描述 | 推送数据 |
|---|---|---|
| smsCodeReceived | 接收到短信验证码 | QuerySmsCodeRsp |
| mailCodeReceived | 接收到邮件验证码 | QueryMailCodeRsp |
| gotPhone | 取到手机号 | GetPhoneRsp |