服务端 REST API 概述

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

与此同时，为方便开发者使用 JSMS API，还提供多种常用编程语言的开发包（SDK）。

REST API 基本约束

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

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	短信开发者账号冻结，请联系技术支持