添加 终端机商家
parent
e570c77972
commit
c7c77a82c4
210
%E7%BB%88%E7%AB%AF%E6%9C%BA%E5%95%86%E5%AE%B6.md
Normal file
210
%E7%BB%88%E7%AB%AF%E6%9C%BA%E5%95%86%E5%AE%B6.md
Normal file
@ -0,0 +1,210 @@
|
||||
<div align="center">
|
||||
<h1>云码平台 - 商家接入文档</h1>
|
||||
</div>
|
||||
|
||||
|
||||
## 商家 API 接口 根地址
|
||||
|
||||
正式环境：<a href="https://api.code92.top" target="_blank">https://api.code92.top</a>
|
||||
|
||||
测试环境：<a href="https://test-api.code92.top" target="_blank">https://test-api.code92.top</a>
|
||||
|
||||
## 阅读 API 功能文档
|
||||
|
||||
<a href="https://test-api.code92.top" target="_blank">https://test-api.code92.top</a>
|
||||
|
||||
## 商家身份鉴权
|
||||
|
||||
几乎所有的 API 都要求验证权限，请在 HTTP 请求头中添加您账号的 JWT Token ：
|
||||
|
||||
- Header Key：Authorization
|
||||
- Header Value：XXXXXXXXXXX （<a href="https://admin.code92.top/profile/merchant" target="_blank">查看商家授权令牌</a>）
|
||||
|
||||
## 短信接码流程
|
||||
|
||||
### 获取手机号
|
||||
|
||||
方式一：主动取号（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/sms.code/api-adm-sms.code-get.phone-Post" target="_blank">文档</a>）
|
||||
|
||||
成功响应示例：
|
||||
``` json
|
||||
{
|
||||
"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前缀的电话号码
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
失败响应示例：
|
||||
``` json
|
||||
{
|
||||
"code": "unexpected", // 错误码
|
||||
"msg": "外部接口异常 0|-1" // 错误原因
|
||||
}
|
||||
```
|
||||
|
||||
方式二：自动取号推送
|
||||
|
||||
i. <a href="https://admin.code92.top/biz/phone-task" target="_blank">添加取号需求</a>
|
||||
|
||||
ii. <a href="https://admin.code92.top/push/subscriber" target="_blank">添加推送地址</a>
|
||||
|
||||
iii. 控制取号开启/停止（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/phone.task/api-adm-phone.task-set.enabled.by.country-Post" target="_blank">文档</a>）
|
||||
|
||||
---------------
|
||||
|
||||
|
||||
### 获取验证码
|
||||
方式一：主动获取（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/sms.code/api-adm-sms.code-get-Post" target="_blank">文档</a>），此步骤需要多次尝试，建议设定请求间隔为5s，持续5min
|
||||
|
||||
取到码响应示例：
|
||||
``` json
|
||||
{
|
||||
"code": "succeed",
|
||||
"data": {
|
||||
"receiveStatus": "received", // 如果取到短信验证码 此字段值为 “received”
|
||||
"smsCode": "1234" // 短信验证码
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
未取到码示例：
|
||||
``` json
|
||||
{
|
||||
"code": "succeed",
|
||||
"data": {
|
||||
"receiveStatus": "waiting" // 如果是waiting，或者executing ，说明还在取码中，可等待几秒再调用此接口
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
``` json
|
||||
{
|
||||
"code": "succeed",
|
||||
"data": {
|
||||
"receiveStatus": "timeout" // 如果是timeout，说明长时间未收到验证码，系统已经自动释放了该手机号，不会再去收码了。
|
||||
}
|
||||
}
|
||||
```
|
||||
方式二：接码自动推送（<a href="https://admin.code92.top/push/subscriber" target="_blank">添加推送地址</a>）
|
||||
|
||||
|
||||
|
||||
### 报告验证码错误
|
||||
如您收到验证码输入目标程序后提示验证码不正确，可调用此接口（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/sms.code/api-adm-sms.code-report.sms.code.error-Post" target="_blank">文档</a>）上报，将该次任务状态重置为waiting， 之后继续执行步骤3，直到状态为received，即收到了新的正确的验证码。
|
||||
|
||||
### 释放手机号
|
||||
如果调用步骤2多次未获取到验证码，需要放弃此号继续做下一个任务时，请调用此接口（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/sms.code/api-adm-sms.code-release.phone-Post" target="_blank">文档</a>），释放手机号之后即停止计费，避免损耗。
|
||||
|
||||
### 拉黑手机号
|
||||
如果不希望获取到某个手机号，可以调用此接口（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/sms.code/api-adm-sms.code-ban.phone-Post" target="_blank">文档</a>）拉黑，拉黑之后可确保24小时内不会再次取到此手机号。
|
||||
|
||||
## 邮箱接码流程
|
||||
|
||||
### 获取邮箱号
|
||||
|
||||
<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/mail.code/api-adm-mail.code-get.email-Post" target="_blank">查看文档</a>
|
||||
|
||||
成功响应示例：
|
||||
``` json
|
||||
{
|
||||
"code": "succeed", // 使用if ( code == "succeed" ) 判定获取成功。
|
||||
"data": {
|
||||
"email": "kerwinnskinnerroman@gmail.com", // email 地址
|
||||
"id": 552154460643333 // 业务流水号，存下来，在后续的接口调用中要传入。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
失败响应示例：
|
||||
``` json
|
||||
{
|
||||
"code": "unexpected", // 错误码
|
||||
"msg": "无可用邮箱号"// 错误原因
|
||||
}
|
||||
```
|
||||
|
||||
### 获取邮件码
|
||||
方式一：主动获取（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/mail.code/api-adm-mail.code-get-Post" target="_blank">文档</a>），此步骤需要多次尝试，建议设定请求间隔为5s，持续5min
|
||||
|
||||
取到码响应示例：
|
||||
``` json
|
||||
{
|
||||
"code": "succeed",
|
||||
"data": {
|
||||
"receiveStatus": "received", // 如果取到邮件验证码 此字段值为 “received”
|
||||
"mailCode": "1234" // 邮件验证码
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
未取到码示例：
|
||||
``` json
|
||||
{
|
||||
"code": "succeed",
|
||||
"data": {
|
||||
"receiveStatus": "waiting" // 如果是waiting，或者executing ，说明还在取码中，可等待几秒再调用此接口
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
``` json
|
||||
{
|
||||
"code": "succeed",
|
||||
"data": {
|
||||
"receiveStatus": "timeout" // 如果是timeout，说明长时间未收到验证码，系统已经自动释放了该邮箱号，不会再去收码了。
|
||||
}
|
||||
}
|
||||
```
|
||||
方式二：接码自动推送（<a href="https://admin.code92.top/push/subscriber" target="_blank">添加推送地址</a>）
|
||||
|
||||
### 报告验证码错误
|
||||
如您收到验证码输入目标程序后提示验证码不正确，可调用此接口（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/mail.code/api-adm-mail.code-report.mail.code.error-Post" target="_blank">文档</a>）上报，将该次任务状态重置为waiting， 之后继续执行步骤3，直到状态为received，即收到了新的正确的验证码。
|
||||
|
||||
### 拉黑邮箱号
|
||||
如果不希望获取到某个邮箱号，可以调用此接口（<a href="https://test-api.code92.top/index.html#/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1/mail.code/api-adm-mail.code-ban.email-Post" target="_blank">文档</a>）拉黑，拉黑之后可确保24小时内不会再次取到此邮箱号。
|
||||
|
||||
|
||||
## 数据订阅推送
|
||||
|
||||
如果您拥有支持公网访问的 Web 服务器，还可以 <a target="_blank" href="https://admin.code92.top/push/subscriber">订阅数据推送</a> ，支持各类订阅各类事件推送。
|
||||
|
||||
通知方式也是通过 HTTP 请求传递到您的 Web 服务器。
|
||||
|
||||
### 推送协议
|
||||
|
||||
| Request Method | Request Url | Request Header | Request Body |
|
||||
| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| POST | <a href="https://admin.code92.top/push/subscriber" target="_blank">设置用于接收数据推送的 URL 地址</a> | CLOUD-CODE-TIMESTAMP: 时间戳 <br />CLOUD-CODE-SIGN: 签名 <br />Content-Type: application/json | { "pushType": <a target="_blank" href="https://test-api.code92.top/index.html#/SwaggerModels/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1"> DataPushTypes </a>, "pushData": 推送数据 } |
|
||||
|
||||
### 签名校验
|
||||
为了确保数据由本平台发出且未经篡改送达您的服务器， 请按照以下方式校验签名，抛弃签名不符以及时间戳误差过大的非法请求：
|
||||
|
||||
( <a href="https://admin.code92.top/profile/merchant" target="_blank">您的用户标识</a> + 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 | 接收到短信验证码 | <a target="_blank" href="https://test-api.code92.top/index.html#/SwaggerModels/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1">QuerySmsCodeRsp</a> |
|
||||
| mailCodeReceived | 接收到邮件验证码 | <a target="_blank" href="https://test-api.code92.top/index.html#/SwaggerModels/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1">QueryMailCodeRsp</a> |
|
||||
| gotPhone | 取到手机号 | <a target="_blank" href="https://test-api.code92.top/index.html#/SwaggerModels/%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1">GetPhoneRsp</a> |
|
||||
Loading…
x
Reference in New Issue
Block a user