接入文档

接入文档

概述

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

全文包括两个部分:

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

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

集成指南

开通服务

请联系技术支持,开通服务。QQ:2880983158

新建应用

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

新建短信签名与模板

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

设置IP白名单

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

常用说明

返回码说明

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

错误码 说明
20000 success
40004 app is unvalid
40026 sign error
40027 get auth_token error
40028 auth_token expired
40031 ip blocked
40032 params error
40033 phone num over limit
40034 template is not exist
50000 other error
50001 other error
50002 other error

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

错误码 说明
20000 success
40000 send error
40006 phone is invalid
40007 template parse error
40008 phone daily msg overlimit
40009 appid daily msg overlimit
50000 server error

鉴权接口

接口描述

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

使用场景

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

接口说明

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

请求方法:POST

具体参数

字段 类型 是否必传 备注
appId String 由个推短信服务提供,每个应用都对应一个唯一的appId
sign String sha256(appKey+timeStamp+masterSecret)
timestamp String 生成sign的时间戳

返回值说明

字段 类型 备注
result String 20000
msg String success
data Json json格式
authToken String 权限令牌,调用其他接口时需提供;data字段的属性

请求示例

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

具体参数

字段 类型 是否必传 备注
appId String 由个推短信服务提供,每个应用都对应一个唯一的appId
authToken String 由鉴权接口返回
smsTemplateId String 模板id
smsParam Json 短信模板变量,传参规则{"key":"value"},key的名字需和模板中定义的变量一致;若模板无变量,此参数不需要传
recNum JsonArray 接收短信的号码,目前单次最大发送量为50个MD5加密后的手机号码。例如:["md5(pn1)","md5(pn2)"]
notifyUrl String 客户用于接收短信发送回执的接口地址,请求以Json格式POST方式提交

返回值说明

字段 类型 备注
result String 20000
msg String success
data String Json格式
taskId String 个推短信服务生成的推送任务id
results JsonArray 短信推送结果返回,例如:[{ "md5(pn1)": code}, { "md5(pn2)": code}]

请求示例

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();
        }

    }

}

文档中心搜索