云码平台 - 商家接入文档
商家 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 |