国际短信业务接口

1 概述

1.1 Base URL

国际短信API引用的地址都有如下Base URL:
中国大陆接入:https://app.cloopen.com:8883
港澳台及境外接入:https://hksms.cloopen.com:8883
注意:为了确保数据隐私,云通讯平台的REST API是通过HTTPS方式请求。

1.2 业务URL

业务URL格式:/{SoftVersion}/account/{accountSid}/{action}/{funcdes}?sig={SigParameter}
在URL格式中 {}内的内容表示为参数,非{}的内容固定不变。
Base URL与业务URL相拼接为完整请求URL,完整URL示例:
属性说明:
属性类型约束说明
accountSidString必选
开发者主账户ACCOUNT SID(登陆官网在管理控制台获取)
SigParameter
String必选

REST API 验证参数,生成规则如下

1.使用MD5加密(账户Id + 账户授权令牌 + 时间戳)。其中账户Id和账户授权令牌根据url的验证级别对应主账户。

时间戳是当前系统时间,格式"yyyyMMddHHmmss"。时间戳有效时间为24小时,如:20140416142030

2.SigParameter参数需要大写,如不能写成sig=abcdefg而应该写成sig=ABCDEFG

1.3 HTTP标准包头字段

Accept:application/xml;
Content-Type:application/xml;charset=utf-8;
Content-Length:256; 
Authorization:
属性说明:
属性类型约束说明
Accept
String必选客户端响应接收数据格式:application/xml、application/json
Content-Type
String必选类型:application/xml;charset=utf-8、application/json;charset=utf-8
Content-Length
String必选Content-Length

Authorization

String

必选

验证信息,生成规则详见下方说明

1.使用Base64编码(账户Id + 冒号 + 时间戳)其中账户Id根据url的验证级别对应主账户

2.冒号为英文冒号

3.时间戳是当前系统时间,格式"yyyyMMddHHmmss",需与SigParameter中时间戳相同。

2 发送国际短信接口

2.1 请求地址

POST  /v2/account/{accountId}/international/send?sig={SigParameter}

2.2 请求包体

属性类型约束长度说明

mobile

String必选20

下发手机号(号码规则:00+国家码+手机号,如当地手机号是以0开头的,需要去掉手机号前边的0)
多个手机号以英文“,”分割;最多支持200个手机号

appId

varchar

必选32应用Id,官网控制台应用列表获取

content

String必选1000短信内容
reqIdString可选32第三方自定义消息id,最大支持32位,同账号下同一自然天内不允许重复。
JSON请求示例
  •  POST /v2/account/abcdefghijklmnopqrstuvwxyz012345/international/send?sig=C1F20E7A9733CE94F680C70A1DBABCD HTTP/1.1

  •  Host:192.168.0.1:8883
  •  content-length: 139
  •  Accept:application/json; 
  •  Content-Type:application/json;charset=utf-8; 
  •  Authorization:ZmY4MDgwODEzYzM3ZGE1MzAxM2M4MDRmODA3MjAwN2M6MjAxMzAyMDExNTABCDE=
  •  
  • {"appId":"8c71b15cbc0444ac92fcecfcfb1e21c2","content":"Your verification code is 1234","mobile":"008613800138000,15832a","reqId":"abc"}         

2.3 响应包体

  • 此步响应只表明接口请求成功,不代表短信已送达手机。具体送达状态请参考“状态报告”接口
  • 对响应解析后,statusCode为"000000"表示请求发送成功。statusCode非"000000"表示请求发送失败,客户服务端可以根据自己的逻辑进行重发或者其他处理。
属性类型约束长度说明

statusCode

String

必选

6

请求状态码,取值000000(成功),其余值为失败

statusMsg

String

必选

状态码statusCode中文描述

smsMessageSid
String必选32短信唯一标识符;32位字母+数字
dateCreated
String必选短信的创建时间,格式:yyyyMMddHHmmss

failList

list必选提交失败号码详单,如均成功则内容为空
mobileString可选失败号码
errorCodeString可选错误码
errorMsgString可选错误码中文描述
JSON响应示例
  •  HTTP/1.1 200 OK 
  •  Content-Length: 641
  •  
  • {
  •    "statusCode": "000000",
  •    "statusMsg": "成功",
  •    "msgId": "b29e2a4043b042bcb4a001eda3d952d4",
  •    "failList": [{
  •           "mobile": "15832a",
  •           "errorCode": "160088",
  •           "errorMsg": "号码格式无效"
  •         }]
  • }   
       

3 国际短信状态报告回调接口

  • 目前支持 HTTP/HTTPS 方式的回调,采用 POST 方式,正文部分为 XML或者 JSON 格式,字符集为 UTF-8;
  • 状态报告回调功能开启与回调地址的配置,请联系商务经理或售后客服配置

3.1 回调地址

POST  /{path}

3.2 回调请求参数

属性类型约束说明
actionString必选功能操作标识 ,SMSArrived
smsTypeString必选短信类型,1:手机接收状态报告
recvTimeString必选短信送达手机时间,格式:yyyyMMddHHmmss
apiVersionString必选REST API版本号,格式:YYYY-MM-DD
fromNumString必选接收短信的手机号码
contentString必选短信唯一标识符,即下行短信请求响应的smsMessageSid。
statusString必选短信到达状态, 0为接收成功,其它值为接收失败
dateSentString必选短信发送时间,格式:yyyyMMddHHmmss
deliverCodeString必选到达状态描述,即运营商网关状态码
reqIdString必选第三方自定义消息id,与发送短信中reqId一致
smsCountString必选下行短信计费条数
spCodeString必选国际短信此参数无用,请忽略
XML请求示例
  • POST http://{ip|域名}:{port}/{path}
  •  
  • <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  • <Request>
  •  <action>SMSArrived</action>
  •  <smsType>1</smsType>
  •  <recvTime>20130923010101</recvTime>
  •  <apiVersion>2013-12-26</apiVersion>
  •  <fromNum>008613800138000</fromNum>
  •  <deliverCode>DELIVRD</deliverCode>
  •  <content>4121908f3d1b4edb9210f0eb4742f62c</content>
  •  <reqId>123</reqId>
  •  <status>0</status>
  •  <smsCount>1</smsCount>
  •  <dateSent>20130923010000</dateSent>
  •  <spCode></spCode>
  • </Request>          
JSON请求示例
  • POST http://{ip|域名}:{port}/{path}
  •  
  • {
  •  "Request": {
  •    "action": "SMSArrived",
  •    "smsType": "1",
  •    "apiVersion": "2013-12-26",
  •    "content": "4121908f3d1b4edb9210f0eb4742f62c",
  •    "fromNum": "008613800138000",
  •    "dateSent": "20130923010000",
  •    "deliverCode": "DELIVRD",
  •    "recvTime": "20130923010010",
  •    "status": "0",
  •    "reqId": "123",
  •    "smsCount": "2",
  •    "spCode": ""
  •        }
  • }   

3.3 响应要求

  • 客户端需要对回调请求响应 HTTP 200的正确状态,否则服务端会进行重试直到失败次数达到阈值
  • 如出现接收问题请联系请联系商务经理或技术支持

4 批量获取国际短信状态报告接口

  • 批量获取接口功能开启,请联系商务经理或售后客服配置
  • 批量获取接口与回调功能两种获取方式只能选一

4.1 请求地址

POST  /2013-12-26/Accounts/{accountSid}/SMS/GetArrived?sig={SigParameter}

4.2 请求包体

属性类型约束说明
appIdString必选应用Id
smsTypeString必选1:短信状态报告
countString可选查询状态的数量。最大500,缺省100
JSON请求示例
  •  POST /2013-12-26/Accounts/abcdefghijklmnopqrstuvwxyz012345/SMS/GetArrived?sig=
  •  C1F20E7A9733CE94F680C70A1DBABCDE HTTP/1.1

  •  Host:192.168.0.1:8883
  •  content-length: 139
  •  Accept:application/json; 
  •  Content-Type:application/json;charset=utf-8; 
  •  Authorization:ZmY4MDgwODEzYzM3ZGE1MzAxM2M4MDRmODA3MjAwN2M6MjAxMzAyMDExNTABCDE=
  •  
  • {"appId": "ff8080813fc70a7b013fc72312324213","smsType": "1","count": "200"}     

4.3 响应包体

属性类型约束说明
statusCodeString必选请求状态码,取值000000(成功)
actionString必选功能操作标识 ,SMSArrived
apiVersionString必选REST API版本号,格式:YYYY-MM-DD
smsTypeString必选1:短信状态报告
fromNumString必选接收短信的手机号码
contentString必选短信唯一标识符,即下行短信请求响应的smsMessageSid。
recvTimeString必选短信送达手机时间,格式:yyyyMMddHHmmss
statusString必选短信到达状态, 0为接收成功,其它值为接收失败
dateSentString必选短信发送时间,格式:yyyyMMddHHmmss
deliverCode String必选到达状态描述,即运营商网关状态码。
reqIdString必选第三方自定义消息id
smsCountString必选下行短信计费条数
spCodeString必选国际短信此参数无用,请忽略
JSON响应示例
  • HTTP/1.1 200 OK 
  • Content-Length: 487

  • {
  •   "statusCode": "000000",
  •   "reports": [{
  •       "content": "dd134b50e636433a96288f4ce5bb1630",
  •       "apiVersion": "2013-12-26",
  •       "fromNum": "00861380001380000",
  •       "status": "0",
  •       "smsType": "1",
  •       "recvTime": "20161202100328",
  •       "action": "SMSArrived",
  •       "dateSent": "20161202100325"
  •         }, {
  •       "content": "14477928a672437691c295e7dc6d63fb",
  •       "apiVersion": "2013-12-26",
  •       "fromNum": "005112345678",
  •       "status": "0",
  •       "smsType": "1",
  •       "recvTime": "20161202100332",
  •       "action": "SMSArrived",
  •       "dateSent": "20161202100330"
  •         }]
  • }