From c7c77a82c41f60a355e6c11797baaf8216d57fbd Mon Sep 17 00:00:00 2001 From: tk Date: Thu, 14 Nov 2024 17:18:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20=E7=BB=88=E7=AB=AF?= =?UTF-8?q?=E6=9C=BA=E5=95=86=E5=AE=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...%88%E7%AB%AF%E6%9C%BA%E5%95%86%E5%AE%B6.md | 210 ++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 %E7%BB%88%E7%AB%AF%E6%9C%BA%E5%95%86%E5%AE%B6.md diff --git a/%E7%BB%88%E7%AB%AF%E6%9C%BA%E5%95%86%E5%AE%B6.md b/%E7%BB%88%E7%AB%AF%E6%9C%BA%E5%95%86%E5%AE%B6.md new file mode 100644 index 0000000..07f06c3 --- /dev/null +++ b/%E7%BB%88%E7%AB%AF%E6%9C%BA%E5%95%86%E5%AE%B6.md @@ -0,0 +1,210 @@ +
+

云码平台 - 商家接入文档

+
+ + +## 商家 API 接口 根地址 + +正式环境：https://api.code92.top + +测试环境：https://test-api.code92.top + +## 阅读 API 功能文档 + +https://test-api.code92.top + +## 商家身份鉴权 + +几乎所有的 API 都要求验证权限，请在 HTTP 请求头中添加您账号的 JWT Token ： + +- Header Key：Authorization +- Header Value：XXXXXXXXXXX （查看商家授权令牌） + +## 短信接码流程 + +### 获取手机号 + +方式一：主动取号（文档） + +成功响应示例： +``` 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. 添加取号需求 + +ii. 添加推送地址 + +iii. 控制取号开启/停止（文档） + +--------------- + + +### 获取验证码 +方式一：主动获取（文档），此步骤需要多次尝试，建议设定请求间隔为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，说明长时间未收到验证码，系统已经自动释放了该手机号，不会再去收码了。 + } +} +``` +方式二：接码自动推送（添加推送地址） + + + +### 报告验证码错误 +如您收到验证码输入目标程序后提示验证码不正确，可调用此接口（文档）上报，将该次任务状态重置为waiting， 之后继续执行步骤3，直到状态为received，即收到了新的正确的验证码。 + +### 释放手机号 +如果调用步骤2多次未获取到验证码，需要放弃此号继续做下一个任务时，请调用此接口（文档），释放手机号之后即停止计费，避免损耗。 + +### 拉黑手机号 +如果不希望获取到某个手机号，可以调用此接口（文档）拉黑，拉黑之后可确保24小时内不会再次取到此手机号。 + +## 邮箱接码流程 + +### 获取邮箱号 + +查看文档 + +成功响应示例： +``` json +{ + "code": "succeed", // 使用if ( code == "succeed" ) 判定获取成功。 + "data": { + "email": "kerwinnskinnerroman@gmail.com", // email 地址 + "id": 552154460643333 // 业务流水号，存下来，在后续的接口调用中要传入。 + } +} +``` + +失败响应示例： +``` json +{ + "code": "unexpected", // 错误码 + "msg": "无可用邮箱号"// 错误原因 +} +``` + +### 获取邮件码 +方式一：主动获取（文档），此步骤需要多次尝试，建议设定请求间隔为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，说明长时间未收到验证码，系统已经自动释放了该邮箱号，不会再去收码了。 + } +} +``` +方式二：接码自动推送（添加推送地址） + +### 报告验证码错误 +如您收到验证码输入目标程序后提示验证码不正确，可调用此接口（文档）上报，将该次任务状态重置为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 | \ No newline at end of file