服务端 REST API 概述
最近更新:2021-12-15

服务端 REST API 概述

JSMS 提供遵从 REST 规范的 HTTP API,以供开发者远程调用 JSMS 提供的服务。

与此同时,为方便开发者使用 JSMS API,还提供多种常用编程语言的开发包(SDK)


REST API 基本约束

  • API 被设计为符合 HTTP, REST 规范。例如:查询请求使用 Get 方法,提交请求使用 Post 方法。如果一个请求不是相应的 HTTP 方法,将返回错误。
  • 如无特殊说明,调用参数值应转码为:UTF-8, URL 编码 [^1]。

[1]: URL 编码 - WikiPedia 定义


API 资源列表

短信发送 API

名称 资源
发送文本验证码短信 API POST https://api.sms.jpush.cn/v1/codes
发送语音验证码短信 API POST https://api.sms.jpush.cn/v1/voice_codes
验证码验证 API POST https://api.sms.jpush.cn/v1/codes/{msg_id}/valid
发送单条模板短信 API POST https://api.sms.jpush.cn/v1/messages
发送批量模板短信 API POST https://api.sms.jpush.cn/v1/messages/batch

短信定时发送 API

名称 资源
单条定时短信提交 API POST https://api.sms.jpush.cn/v1/schedule
批量定时短信提交 API POST https://api.sms.jpush.cn/v1/schedule/batch
单条定时短信修改 API PUT https://api.sms.jpush.cn/v1/schedule/{schedule_id}
批量定时短信修改 API PUT https://api.sms.jpush.cn/v1/schedule/batch/{schedule_id}
定时短信查询API GET https://api.sms.jpush.cn/v1/schedule/{schedule_id}
定时短信删除 API DELETE https://api.sms.jpush.cn/v1/schedule/{schedule_id}

短信余量查询 API

名称 资源
账号余量查询 API GET https://api.sms.jpush.cn/v1/accounts/dev
应用余量查询 API GET https://api.sms.jpush.cn/v1/accounts/app

短信回执 API

名称 资源
获取短信发送状态 API GET https://api.sms.jpush.cn/v1/report
获取上行短信消息 API GET https://api.sms.jpush.cn/v1/reply

返回码

若请求失败,API 会返回如下 JSON 格式的返回码及说明

{ "error": { "code": *****, "message": "*****" } }
          {
    "error": {
        "code": *****,
        "message": "*****"
    }
}

        
此代码块在浮窗中显示

REST API 返回码汇总

HTTP CODE CODE MESSAGE DESC
200 50000 success 请求成功
400 50001 missing auth auth 为空
401 50002 auth failed auth 鉴权失败
400 50003 missing body body 为空
400 50004 missing mobile 手机号码为空
400 50005 missing temp_id 模版 ID 为空
403 50006 invalid mobile 手机号码无效
403 50007 invalid body body 无效
403 50008 no sms code auth 未开通短信业务
403 50009 out of freq 发送超频
针对同一应用,同一被叫手机号码,发送频率限制如下:
1. 语音短信每次获取短信需间隔 20s
2. 文本验证码短信 24h/200 条
3. 通知短信相同内容 10min/3 条,不同内容无限制,所有通知短信一天发送上限 200 条
4. 营销短信 10min/3 条
403 50010 invalid code 验证码无效
403 50011 expired code 验证码过期
403 50012 verified code 验证码已验证
403 50013 invalid temp_id 模版 ID 无效
403 50014 no money 可发短信余量不足
400 50015 missing code 验证码为空
404 50016 api not found API 不存在
415 50017 media not supported 媒体类型不支持
405 50018 request method not support 请求方法不支持
500 50019 server error 服务端异常
403 50020 template auditing 模板审核中
403 50021 template not pass 模板审核未通过
403 50022 parameters not all replaced 模板中参数未全部替换
403 50023 parameters is empty 参数为空
403 50024 unsubscribed mobile 手机号码已退订
403 50025 wrong template type 该 API 不支持此模版类型
403 50026 wrong msg_id msg_id 无效
403 50027 invalid send_time 发送时间为空或在当前时间之前
403 50028 invalid schedule_id schedule_id 无效
403 50029 wrong schedule status 定时短信已发送或已删除,无法再修改
403 50030 recipients is empty recipients 为空
403 50031 too much recipients recipients 短信接收者数量超过 1000
403 50034 repeat send 重复发送
403 50035 illegal IP 请求 IP 不合法
403 50036 app in black 应用被列为黑名单
403 50037 has black word 短信内容存在敏感词汇
403 50038 invalid content length 短信内容长度错误,文本短信长度不超过 500 个字,语音短信验证码长度 4 ~ 8 数字
403 50039 invalid code type 语音验证码内容错误,验证码仅支持数字
403 50040 invalid voice language type 语音验证码播报语言类型错误
403 50041 invalid ttl value 验证码有效期错误
403 50042 template is empty 模板内容为空
403 50043 template too long 模板内容过长,含签名长度限制为 500 字符
403 50044 template parameter invalid 模板参数无效
403 50045 remark too long 备注内容过长,长度限制为 500 字符
403 50046 signature not set 该应用未设置签名,请先设置签名
403 50047 modify template not allow 该模版不支持修改,仅状态为审核不通过的模板支持修改
403 50051 signatures not exist 签名不存在/未创建签名
403 50052 template contains special symbol 模板不能含有特殊符号,如【】
403 50053 special template parameter need extra remark for confirmation 模板中存在链接变量,请在 remark 参数中填写链接以报备,避免短信发送时因进入人工审核而导致发送延迟
403 50054 content contains special symbol 短信正文不能含有特殊符号,如【】
403 50101 invalid image 图片不合法
403 50102 invalid sign id 签名 ID 不合法
403 50103 other signatures in the audit 已经存在其他待审核的签名,不能提交
403 50104 invalid signature 签名内容不合法
403 50105 default signature cannot be deleted 默认签名不能删除
403 50201 pull out of frequency 超频,API 调用频率:单个 appKey 5 秒/次
403 50202 pull not allow 禁止拉取,建议:请排查当前是否正在使用回调的形式获取数据
403 50301 invalid account 短信开发者账号冻结,请联系技术支持
文档内容是否对您有帮助?

Copyright 2011-2022, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

在文档中心打开