接入文档

• 概述
• 集成指南
• 常用说明
• 鉴权接口
• 短信群推接口
• 完整demo示例

概述

该文档旨在介绍短信服务群推接口，通过调用文中的所述接口，可以帮助用户实现短信的群推业务。

全文包括两个部分：

第一部分常用说明：调用接口的字段解释、接口返回值编码说明

第二部分接口说明：鉴权、群推等接口的使用方式


集成指南

开通服务

请联系文档中心右侧“技术咨询”，开通服务

新建应用

请至短信开发者中心新建应用，获取APPId，APPKey和MasterSecret参数

新建短信签名与模板

请至短信开发者中心创建签名与模板

设置IP白名单

出于安全考虑，请至短信开发者中心设置IP白名单

常用说明

返回码说明

鉴权和短信群推接口返回result字段的返回码说明：

短信群推接口返回每个pn对应发送结果的code说明：

鉴权接口

接口描述

该接口为鉴权接口，在调用短信群发接口之前，需先调用该接口进行鉴权，鉴权成功获得authToken，后续接口使用authToken进行调用。

使用场景

用户调用短信群推接口，需上传鉴权成功后返回的authToken，短信群推接口会对authToken进行校验。

接口说明

请求地址： https://openapi-smsp.getui.com/v1/sps/auth_sign

请求方法：POST

具体参数

返回值说明

请求示例

Json示例, 具体请求需转Json格式

{
    "appId": "xxxxxx",
    "timestamp": "1234567890000",
    "sign": "xxxxxx"
}

响应示例

鉴权结果响应Json格式示例

{
    "result": "20000",
    "msg": "success",
    "data": {
        "authToken": "xxxxxxxxxxx"
    }
}

注意事项

鉴权生成的authToken有效期为2个小时，若authToken过期，需重新进行鉴权。


短信群推接口

接口描述

根据用户上传MD5加密后的手机号码，匹配模板进行短信推送。

注意：MD5采用32位小写加密

使用场景

用户调用短信发送接口，将需要发送的MD5加密后手机号码列表和模板中的参数配置上传，处理后由短信服务向手机推送短信。

接口说明

请求地址： https://openapi-smsp.getui.com/v1/sps/push_sms_list

请求方法：POST

具体参数

返回值说明

请求示例

Json示例, 具体请求需转Json字符串

{
    "appId": "XXXXXXXXXXXXXX",
    "authToken": "XXXXXXXXXXXXXX",
    "smsTemplateId": "000001",
    "smsParam": {
        "key1": "value1",
        "key2": "value2"
    },
    "recNum": [
        "3c41dc04cbc783dc66091ad49c7b755b",
        "9a54ab45622e64bd76b5d50d4e6487ac"
    ]
}

响应示例

Json示例

{
    "result": "20000",
    "msg": "success",
    "data": {
        "taskId": "xxxxxxxxxxx",
        "results": {
            "3c41dc04cbc783dc66091ad49c7b755b": 20000,
            "9a54ab45622e64bd76b5d50d4e6487ac": 40000
        }
    }
}

注意事项

接口中返回的每个手机号对应的结果仅代表服务的请求状况，不代表短信是否发送成功。短信是否发送成功以手机接收的实际情况为准。


完整demo实例

java示例

/**
 * 鉴权接口
 */
public class AuthSignTest {
    //鉴权url
    static String url = "https://openapi-smsp.getui.com/v1/sps/auth_sign"; 
    public static void main(String[] args) throws Exception {
        URL urlObj = new URL(url);
        URLConnection con = urlObj.openConnection();
        HttpURLConnection httpURLConnection = (HttpURLConnection) con;

           //http头部
        httpURLConnection.setRequestMethod("POST");
        httpURLConnection.setDoOutput(true);
        httpURLConnection.setRequestProperty("Content-Type","application/json;charset=UTF-8"); 
        long timestamp = System.currentTimeMillis();

        //将个推短信服务提供的app对应的appkey和masterSecret，可自行替换
        String appkey="";
        String masterSecret=""; 
        String appId="";

        //sha256加密，使用org.apache.commons包中自带的加密方法，需将加密后数据一起上传
        String sign = DigestUtils.sha256Hex(String.format("%s%d%s", appkey, timestamp, masterSecret)); 
        JSONObject requestDataObject = new JSONObject();
        requestDataObject.put("sign", sign);
        requestDataObject.put("timestamp", timestamp);
        requestDataObject.put("appId", appId);

        //建立连接，将数据写入内存
        OutputStreamWriter out = new 
        OutputStreamWriter (httpURLConnection.getOutputStream());
        out.write(requestDataObject.toString());
        out.flush();
        out.close();

        BufferedReader in = null;
        String result = "";

        //将数据发送给服务端，并获取返回结果
        in = new BufferedReader(new InputStreamReader(httpURLConnection.getInputStream()));
        String line;
        while ((line = in.readLine()) != null) {
            result += line;
        }
        System.out.println(result);
    }
}



/**
 * 群推接口
 */
public class SmsPushListTest {
    //短信群推url
    static String url = "https://openapi-smsp.getui.com/v1/sps/push_sms_list"; 
    public static void main(String[] args) throws Exception {
        URL urlObj = new URL(url);
        URLConnection con = urlObj.openConnection();
        HttpURLConnection httpURLConnection = (HttpURLConnection) con;

        //http头部
        httpURLConnection.setRequestMethod("POST");
        httpURLConnection.setDoOutput(true);
        httpURLConnection.setRequestProperty("Content-Type","application/json;charset=UTF-8"); 

        String appId=""; 
        JSONObject requestDataObject = new JSONObject();
        requestDataObject.put("appId", appId);
        requestDataObject.put("authToken", "9e46cf0fac0bd94b01c6396db8700f6b5c988cd4e51eaff94f1cefec50ad17c9");
        requestDataObject.put("smsTemplateId", "000001");
        Map<String, String> param = new HashMap<String, String>();
        param.put("name", "***");
        param.put("code", "***");
        requestDataObject.put("smsParam", param);
        List<String> phoneNum = new ArrayList<String>();
        for (int i = 0; i < 1; i++) {
            phoneNum.add("9a54ab64562e64bd76b5d50d4e6487ac");
              phoneNum.add("b6fda656f377a5b8ebdb7db70aa29870");
        }
        requestDataObject.put("recNum", phoneNum);

        //建立连接，将数据写入内存
        OutputStreamWriter out = new     
        OutputStreamWriter (httpURLConnection.getOutputStream());
        out.write(requestDataObject.toString());
        out.flush();
        out.close();
        BufferedReader in = null;
        String result = "";

        //将数据发送给服务端，并获取返回结果
        in = new BufferedReader(new     
        InputStreamReader(httpURLConnection.getInputStream()));
        String line;
        while ((line = in.readLine()) != null) {
            result += line;
        }
        System.out.println(result);
    }
}

PHP示例

/**
 * 鉴权接口
 */
function AuthSignTest(){
    //鉴权url
    $url="https://openapi-smsp.getui.com/v1/sps/auth_sign";
    //将个推短信服务提供的app对应的appkey和masterSecret，可自行替换
    $appkey="";
    $masterSecret="";
    $appId="";
    $timestamp = micro_time();
    $signCombination = $appkey.$timestamp.$masterSecret;
    $sign = hash("sha256", $signCombination);
    $params = array();
    $params["sign"] = $sign;
    $params["timestamp"] = $timestamp;
    $params["appId"] = $appId;
    //http头部
    $headers=array(
        "Content-Type:application/json;charset=utf-8",
        "Accept:application/json;charset=utf-8"
    );
    //json序列化
    $params=json_encode($params);
    $result=do_post($url,$params,$headers);
    echo json_encode($result);
    return;
}

/**
 * 群推接口
 */
function SmsPushListTest(){
    //短信群推url
    $url="https://openapi-smsp.getui.com/v1/sps/push_sms_list";
    $appId="";
    $requestDataObject = array();
    $requestDataObject["appId"] = $appId;
    $requestDataObject["authToken"] = "";
    $requestDataObject["smsTemplateId"] = "";

    $params = array();
    //params中填写你的模版中的占位符参数；
    $params["name"] = "***";
    $params["code"] = "***";
    $requestDataObject["smsParam"] = $params;
    $phoneNum = array();
    for($i = 0; $i < 1; $i++){
        $phoneNum[0] = "";

    }
    $requestDataObject["recNum"] = $phoneNum;

    $headers=array(
        "Content-Type:application/json;charset=utf-8",
        "Accept:application/json;charset=utf-8"
    );
    //json序列化
    $params=json_encode($requestDataObject);
    $result=do_post($url,$params,$headers);
    echo json_encode($result);
    return;
}


function do_post($url, $params, $headers) {
    $ch = curl_init ();
    curl_setopt ( $ch, CURLOPT_URL, $url );
    curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, 1 );
    curl_setopt ( $ch, CURLOPT_CUSTOMREQUEST, 'POST' );
    curl_setopt ( $ch, CURLOPT_POSTFIELDS, $params );
    curl_setopt ( $ch, CURLOPT_HTTPHEADER, $headers );
    curl_setopt ( $ch, CURLOPT_TIMEOUT, 60 );
    $result = curl_exec ( $ch );
    curl_close ( $ch );
    return $result;
}


function micro_time()
{
    list($usec, $sec) = explode(" ", microtime());
    $time = ($sec . substr($usec, 2, 3));
    return $time;
}

python示例

import requests
import hashlib
import json
import time


#鉴权接口
def AuthSignTest():
    url = "https://openapi-smsp.getui.com/v1/sps/auth_sign"
    headers = {
        "Content-Type": "application/json; charset=UTF-8",
        "Accept": "application/json;charset=utf-8"
    }
    #将个推短信服务提供的app对应的appkey和masterSecret，可自行替换
    appkey = ""
    masterSecret = ""
    appId = ""
    timestamp = getCurrentTime()
    sign = getSign(appkey, timestamp, masterSecret)
    params = dict()
    params["sign"] = sign
    params["timestamp"] = timestamp
    params["appId"] = appId
    params = json.dumps(params)
    r = requests.post(url, data=params, headers=headers)
    print(r.text)


def getSign(appKey, timeStamp, masterSecret):
    rawValue = appKey + str(timeStamp) + masterSecret
    return hashlib.sha256(rawValue.encode()).hexdigest()


def getCurrentTime():
    return int(time.time() * 1000)


#群推接口
def SmsPushListTest():
    url = "https://openapi-smsp.getui.com/v1/sps/push_sms_list"
    headers = {
        "Content-Type": "application/json; charset=UTF-8",
        "Accept": "application/json;charset=utf-8"
    }
    appId = ""
    requestDataObject = dict()
    requestDataObject["appId"] = appId
    requestDataObject["authToken"] = ""
    requestDataObject["smsTemplateId"] = ""

    params = dict()
    #params中填写你的模版中的占位符参数
    params["name"] = "***";
    params["code"] = "***";
    requestDataObject["smsParam"] = params
    phoneNum = []
    for i in range(1):
        phoneNum.append("")
    requestDataObject["recNum"] = phoneNum
    params = json.dumps(requestDataObject)
    r = requests.post(url, data=params, headers=headers)
    print(r.text)

c#示例

using System;
using System.IO;
using System.Net;
using System.Collections.Generic;
using Newtonsoft.Json.Linq;
using System.Text;
using System.Security.Cryptography;


namespace c_
{
    public class SendMsg
    {        
        static string authurl= "https://openapi-smsp.getui.com/v1/sps/auth_sign";
        static string sendmsgurl= "https://openapi-smsp.getui.com/v1/sps/push_sms_list";

        //鉴权方法，获得token值
        public static void authsign()
        {
            Uri uri = new Uri(authurl);
            HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(uri);
            httpWebRequest.Method = "POST";
            httpWebRequest.ContentType = "application/json;charset=UTF-8";
            long timestamp= (long)(DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalMilliseconds;

            //将个推短信服务提供的app对应的appkey和masterSecret，可自行替换
            string appkey = "";
            string masterSecret = "";
            string appId = "";

            string sign = sha256(String.Format("{0}{1}{2}", appkey, timestamp, masterSecret));

            JObject jObject = new JObject();
            jObject.Add("sign", sign);
            jObject.Add("timestamp", timestamp);
            jObject.Add("appId", appId);

            //建立连接，将数据写入内存
            StreamWriter streamWriter = new StreamWriter(httpWebRequest.GetRequestStream());
            streamWriter.WriteLine(jObject.ToString());
            streamWriter.Flush();
            streamWriter.Close();

            StreamReader streamReader = null;
            string result = "";

            //将数据发送给服务端，并获取返回结果
            HttpWebResponse httpWebResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            streamReader = new StreamReader(httpWebResponse.GetResponseStream());
            string line;
            while((line=streamReader.ReadLine())!=null)
            {
                result += line;
            }
            Console.WriteLine(result);
            Console.ReadLine();
        }


        //sha256值
        public static string sha256(string data)
        {
            byte[] bytes = Encoding.UTF8.GetBytes(data);
            byte[] hash = SHA256Managed.Create().ComputeHash(bytes);

            StringBuilder builder = new StringBuilder();
            for (int i = 0; i < hash.Length; i++)
            {
            builder.Append(hash[i].ToString("X2"));
            }

            return builder.ToString();
        }


        //短信发送方法
        public static void send()
        {
            Uri uri = new Uri(sendmsgurl);
            HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(uri);
            httpWebRequest.Method = "POST";
            httpWebRequest.ContentType = "application/json;charset=UTF-8";
            string appId=""; 

            JObject jObject = new JObject();
            JObject smsParam = new JObject();
            //smsParam中填写你的模版中的占位符参数；
            smsParam.Add("name","***");
            smsParam.Add("code","***");

            jObject.Add("appId", appId);
            jObject.Add("authToken", "");
            jObject.Add("smsTemplateId", "");
            jObject.Add("smsParam",smsParam);

            JArray phoneNum = new JArray();
            for(int i= 0;i<1;i++){
                //md5(手机号码)
                phoneNum.Add("");
            }
            jObject.Add("recNum",phoneNum);
            //建立连接，将数据写入内存
            StreamWriter streamWriter = new StreamWriter(httpWebRequest.GetRequestStream());
            streamWriter.WriteLine(jObject.ToString());
            streamWriter.Flush();
            streamWriter.Close();

            StreamReader streamReader = null;
            string result = "";

            //将数据发送给服务端，并获取返回结果
            HttpWebResponse httpWebResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            streamReader = new StreamReader(httpWebResponse.GetResponseStream());
            string line;
            while((line=streamReader.ReadLine())!=null)
            {
                result += line;
            }
            Console.WriteLine(result);
            Console.ReadLine();
        }

    }

}