开通和使用

云鼎短信服务的开通及操作方式有控制台操作和API接口两种方式。

1、控制台方式开通及操作

登陆云鼎控制台，访问云鼎短信服务申请开通。
访问路径：“京东云鼎控制台”->“云服务”->“业务组件”->“云鼎短信服务”

1.1 账户概览

账户概览页面可以查看云鼎账户状态、短信余量、发送量（7天、30天）及套餐包使用情况；

短信充值：点击短信充值进入套餐包购买页面
设置余量预警：针对短信剩余数量设置预警通知，当短信余量触发预警数量时将以短信方式通知您；为了防止套餐余量用尽、影响到您的业务, 建议在套餐管理页面进行预警设置。

1.2 套餐包管理

套餐包管理页面您可以查看历史已购买的套餐包信息，也可以点击“购买套餐包”进入套餐包购买页面进行套餐购买。

可以通过账户概览页面充值入口或者套餐包管理页面购买套餐包入口进入购买套餐包页面。
您可以根据您实际业务的需要购买不同规格的套餐包；套餐包购买规格的数量越大相对费用单价越低，但需考虑业务实际用量（套餐包有效期一年）。

1.3 应用管理

在使用京东云鼎短信服务发送短信前，需要先创建应用，应用创建完成，您可以获得该应用的唯一标识码AppID（应用ID）和用来校验短信发送请求合法性的密码 AccessKey。

1.3.1 创建应用

登录京东云账号后，进入云鼎控制台-云鼎短信服务，在左侧菜单中选择 "应用管理"，在打开的页面中点击 "创建应用"按钮。

在弹出的创建应用界面中填写应用名称和应用描述，信息填写完成后点击确定，页面会跳转到应用列表，您在应用列表可以看到你刚才添加成功的应用。

在应用列表页面上，您可以查看该应用的短信使用情况，停用、启用、编辑应用。

应用创建后为启用状态，此时您可以进行停用操作，列表中应用的状态将变为 '停用'，停用后京东云鼎将停止该应用的短信服务。如果您想继续使用该应用可点击 '启用'，启用后将可正常使用短信服务。

1.3.2 管理应用

应用列表页面点击单个应用的应用名称进入应用管理页面，可对应用的文本短信内容进行签名、模版、任务管理，同时可查看应用下的短信数据统计及对应用进行通用设置。

1.3.2.1 应用-文本短信

文本短信概览：查看应用基础信息及获取对应用的AccessKey ID和AccessKey Secret；

短信签名：短信签名页面可管理已有签名信息及创建签名；点击“创建签名”根据签名弹窗页面的提示内容进行信息填写；填写完成后点击“提交”后等待运营人员进行签名审核。

短信模版：短信模版页面可管理已有短信模版和创建新短信模版；点击“创建模版”根据创建模版弹窗页面的提示内容进行信息填写；填写完成后点击“提交”后等待运营人员进行模版审核。

发送任务：
推广短信和不带变量的通知类短信可以通过控制台 "发送短信" 页面进行在线发送；验证码短信和带变量的通知短信需要通过API或SDK调用。
在内容设置界面中填写相关资料，并选择已审核通过的 '短信签名' 和 '短信模板'，设置发送时间并根据格式要求上传手机号后，点击下一步

核对发送的信息后，点击确认发送，完成短信任务创建
注：
推广短信发送时间：每日 8:30 -- 21:30
定时发送时间限制：仅可选择当前时刻后推14天内的时间
系统将自动过滤掉重复的手机号

您可以在发送短信列表页查看短信发送状态，并且可以导出结果查看各手机号发送情况。

1.3.2.2 应用-数据统计

数据总览：在数据总览项中，您可以查看最近 7 天，最近 30 天或指定时间段的短信发送量和费用清单。

短信记录：在短信记录项中，输入手机号码，选择发送状态，单击【查询】，可以查看单个手机号在指定时间段的短信下发记录。

模板查询：在模板查询项中，选择模板名称后，单击【查询】，可查看指定时间内该模板的短信发送量和发送成功率。

回执分析：在回执分析项中，您可以查看最近 7 天，最近 30 天或指定时间段的短信回执详情和回执成功率分析。

1.3.2.3 应用-通用设置

在通用设置页面，您可以对发送频率、发送超量提醒及回调地址信息设置

1.4 短信发送

除在云鼎控制台文本短信创建短信任务发送外，其他短信可通过api方式发送，可以参考2.2部分内容。

2、API方式开通及操作

请按以下说明准备好环境。
JAVA环境依赖, 请确保已经安装了 JDK 8 环境，若未安装请前往 Oracle 官网下载；
SDK环境依赖, 建议使用Maven 方式引入依赖：

<dependency>
    <groupId>com.jdcloud.sdk</groupId>
    <artifactId>ydsms</artifactId>
    <version>1.0.5</version>
</dependency>

关于 Java SDK 的最新版本号，请查看
调用openapi接口accessKeyId和secretAccessKey前往京东云控制台AccessKey管理页面查看

2.1 短信基础接口

2.1.1 开通短信服务

请求方式
POST

请求地址
https://ydsms.jdcloud-api.com/v1/smsUsers

请求参数
无

返回参数

Result

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void openService() {
        OpenServiceUsingPOSTRequest openServiceUsingPOSTRequest = new OpenServiceUsingPOSTRequest();
        System.out.println(new Gson().toJson(ydsmsClient.openServiceUsingPOST(openServiceUsingPOSTRequest)));
    }
}

2.1.2、创建短信应用

请求方式
POST

请求地址
https://ydsms.jdcloud-api.com/v1/smsApps

请求参数

返回参数

Result

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void createSmsApp() {
        CreateSmsAppUsingPOSTRequest request = new CreateSmsAppUsingPOSTRequest();
        request.setAppId("yd-app-02d73869hx111");
        request.setAppDesc("测试");
        request.setAppName("测试");
        System.out.println(new Gson().toJson(ydsmsClient.createSmsAppUsingPOST(request)));
    }
}

2.1.3、查询应用列表

请求方式
GET

请求地址
https://ydsms.jdcloud-api.com/v1/smsApps

请求参数

返回参数

Result

SmsAppVO

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void listSmsApps() {
        ListSmsAppsUsingGETRequest listSmsAppsUsingGETRequest = new ListSmsAppsUsingGETRequest();
        ListSmsAppsUsingGETResponse listSmsAppsUsingGETResponse = ydsmsClient.listSmsAppsUsingGET(listSmsAppsUsingGETRequest);
        System.out.println(new Gson().toJson(listSmsAppsUsingGETResponse));
    }
}

2.1.4、创建短信签名

请求方式
POST

请求地址
https://ydsms.jdcloud-api.com/v1/smsSigns

请求参数

返回参数

Result

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void createSign() {
        CreateSmsSignUsingPOSTRequest request = new CreateSmsSignUsingPOSTRequest();
        request.setAppId("yd-app-02d73869hx1");
        request.setApplyExplanation("测试");
        request.setSignAttorneyUrl("xx");
        request.setSignCertificateUrl("xx");
        request.setSignOtherCertificateUrl("xx");
        request.setSignContent("测试");
        request.setSignPurpose(0);
        request.setSignTypeId(1);
        System.out.println(new Gson().toJson(ydsmsClient.createSmsSignUsingPOST(request)));
    }
}

2.1.5、查询签名列表

请求方式
GET

请求地址
https://ydsms.jdcloud-api.com/v1/smsSigns

请求参数

返回参数

Result

SmsSignVO

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void listSign() {
        ListSmsSignsUsingGETRequest request = new ListSmsSignsUsingGETRequest();
        request.setAppId("yd-app-02d73869hx1");
        System.out.println(new Gson().toJson(ydsmsClient.listSmsSignsUsingGET(request)));
    }
}

2.1.6、创建短信模板

请求方式
POST

请求地址
https://ydsms.jdcloud-api.com/v1/smsTemplates

请求参数

返回参数

Result

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void createTemplate() {
        CreateSmsTemplateUsingPOSTRequest request = new CreateSmsTemplateUsingPOSTRequest();
        request.setAppId("yd-app-02d73869hx1");
        request.setApplyExplanation("测试");
        request.setTemplateContent("欢迎您注册成为京东云用户，验证码为：${1}， 5分钟内有效！");
        request.setTemplateName("测试");
        request.setTemplateType(1);
        System.out.println(new Gson().toJson(ydsmsClient.createSmsTemplateUsingPOST(request)));
    }
}

2.1.7、查询短信模板列表

请求方式
GET

请求地址
https://ydsms.jdcloud-api.com/v1/smsTemplates

请求参数

返回参数

Result

SmsTemplateVO

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void createTemplate() {
        ListSmsTemplatesUsingGETRequest request = new ListSmsTemplatesUsingGETRequest();
        request.setAppId("yd-app-xxxx");
        System.out.println(new Gson().toJson(ydsmsClient.listSmsTemplatesUsingGET(request)));
    }
}

2.2、短信发送接口

2.2.1、根据明文手机号发送短信

请求方式
POST

请求地址
https://ydsms.jdcloud-api.com/v1/smsSendMessages

请求参数

返回参数

Result

MtResVO

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void send() {
        SendMessagesUsingPOSTRequest request = new SendMessagesUsingPOSTRequest();
        request.setAppId("yd-app-XXXXXXXXX");
        request.setParams(Collections.singletonList("测试"));
        request.setSignId("342d698979d9434787597c71492xxxxx");
        request.setTemplateId("608de5ffdcc347419291b684a32xxxxx");
        request.setPhoneList(Collections.singletonList("1881171xxxxx"));
        System.out.println(new Gson().toJson(request));
        System.out.println(new Gson().toJson(ydsmsClient.sendMessagesUsingPOST(request)));
    }
}

2.2.2、根据京东pin发送短信

请求方式
POST

请求地址
https://ydsms.jdcloud-api.com/v1/sendMessagesByPin

请求参数

返回参数

Result

MtResVO

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void sendByPin() {
        SendMessagesByPinUsingPOSTRequest request = new SendMessagesByPinUsingPOSTRequest();
        request.setAppId("yd-app-17b42xxxx");
        request.setParams(Collections.singletonList("测试"));
        request.setSignId("342d698979d9434787597c71492xxxx");
        request.setTemplateId("608de5ffdcc347419291b684a32xxxx");
        request.setPin("1823318xxxx");
        System.out.println(new Gson().toJson(request));
        System.out.println(new Gson().toJson(ydsmsClient.sendMessagesByPinUsingPOST(request)));
    }
}

2.2.3、根据商家id和订单号发送短信

请求方式
POST

请求地址
https://ydsms.jdcloud-api.com/v1/sendMessagesByOrderId

请求参数

返回参数

Result

MtResVO

代码示例：

public class YdsmsDemo {
    //1. 设置accessKey和secretKey线上环境
    private static String accessKeyId = "xxx";
    private static String secretAccessKey = "xxx";
    private static CredentialsProvider credentialsProvider = new StaticCredentialsProvider(accessKeyId, secretAccessKey);
    private static YdsmsClient ydsmsClient;

    static {
        ydsmsClient = YdsmsClient.builder()
                .credentialsProvider(credentialsProvider)
                .httpRequestConfig(new HttpRequestConfig.Builder().protocol(Protocol.HTTPS).build()) //默认为HTTPS
                .build();
    }

    @Test
    public void sendByOrderId() {
        SendMessagesByOrderIdUsingPOSTRequest request = new SendMessagesByOrderIdUsingPOSTRequest();
        request.setAppId("yd-app-17b42xxxx");
        request.setParams(Collections.singletonList("测试"));
        request.setSignId("342d698979d9434787597c71492xxxx");
        request.setTemplateId("608de5ffdcc347419291b684a32xxxx");
        request.setVenderId(123456L);
        request.setOrderId(1234567890L);
        System.out.println(new Gson().toJson(ydsmsClient.sendMessagesByOrderIdUsingPOST(request)));
    }
}

2.2.4、短信回执、上行消息

配置短信回执、上行消息回调地址
选择要配置回调地址的应用，点击 "应用名称"，进入设置页面，点击 短信状态回调地址设置，回调服务需要返回指定的json字符串 { "status": true }。

注：回执和上行消息回调地址为同一个
短信回执参数格式

示例：

{
    "reqid":"211123161429108512100003",
    "phone":"188****3290",
    "time":"2021-11-23 16:14:37",
    "status":"0",
    "code":"DELIVRD",
    "desc":"成功"
}

上行消息参数格式

示例：

{
    "content":"very good",
    "phone":"188****3290",
    "time":"2021-11-19 13:53:53",
    "sign":"测试"
}