{ "openapi": "3.0.3", "info": { "title": "三网短信通知类（需要模板）", "description": "1、三网合一短信接口，适用于各类短信验证码，短信通知，会员短信、行业短信、登录验证、密码找回等信息发送；2、支持虚拟运营商短信发送；3、可参照模板，也支持自定义变量内容；4、3秒到达、成功率99%以上。【注意：该接口仅对企业用户提供服务，使用之前请确保已做企业认证；注意细则，请点击查看】", "termsOfService": "https://www.showapi.com/helpcenter/view#/4019/2", "version": "1.0.0" }, "servers": [ { "url": "https://route.showapi.com" } ], "paths": { "/28-18": { "x-pointCode": 18, "x-mode": "mapping", "x-read-timeout": 50, "x-connect-timeout": 50, "post": { "summary": "步骤(2)_查询自定义签名", "description": "短信api接口的步骤(2)_查询自定义签名，是用来查询申请签名是否得到运营商的审批通过。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": {}, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_18_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "用户签名" } } } } } } } }, "/28-17": { "x-pointCode": 17, "x-mode": "mapping", "x-read-timeout": 15, "x-connect-timeout": 15, "post": { "summary": "修改自定义签名", "description": "通过修改自定义短信前面，短信签名提交给运营商审核，通常需要3-5个工作日。广泛应用于用户验证、账户通知、预约确认和客户服务等应用场景。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "成功标记 0 成功其他失败" }, "remark": { "type": "string", "description": "备注" }, "title": { "type": "string", "description": "签名" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_17_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "短信签名,使用UTF-8编码请使用地区+名称简称，不要跳字" }, "use_for_des": { "type": "string", "description": "签名用途：\n1、已备案网站\n2、已上线APP\n3、公众号或小程序\n4、电商平台店铺名\n5、已注册商标名\n6、其它" }, "use_for_explain": { "type": "string", "description": "签名用途描述（产品链接等）" }, "legal_name": { "type": "string", "description": "营业执照法定代表人姓名" }, "legal_ID": { "type": "string", "description": "营业执照法定代表人身份证号" }, "legal": { "type": "string", "description": "营业执照法定代表人身份证正面照base64" }, "notiPhone": { "type": "string", "description": "通知号码" }, "biz": { "type": "string", "description": "该签名对应营业执照图片base64，（格式：jpg、png）" } } } } } } } }, "/28-16": { "x-pointCode": 16, "x-mode": "mapping", "x-read-timeout": 15, "x-connect-timeout": 15, "post": { "summary": "步骤(1)_创建自定义签名", "description": "短信api接口，自定义创建短信签名提交给运营商审核（需提交身份证正面照到客服处），一般3-5个工作日。提供了一种简便的方式来发送通知、验证信息和其他类型的消息。由于运营商对签名的使用时效有严格的要求，若签名命中以下任一条件时，签名将自动失效，需重新报备后才可正常使用\n试用期：签名实名成功后有7天试用期，期间若未使用，签名将自动失效\n使用期：签名实名成功后，通过试用期后，若6个月内未使用，签名将自动失效", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "成功标记 0 成功其他失败" }, "remark": { "type": "string", "description": "备注" }, "title": { "type": "string", "description": "签名" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_16_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "模板签名,使用UTF-8编码，请使用地区+名称简称，不要跳字" }, "use_for": { "type": "string", "description": "使用对象（1、自用，2、他用）" }, "use_for_des": { "type": "string", "description": "签名用途：\n1、已备案网站\n2、已上线APP\n3、公众号或小程序\n4、电商平台店铺名\n5、已注册商标名\n6、其它用途" }, "legal_name": { "type": "string", "description": "营业执照法定代表人姓名（必填）" }, "legal_ID": { "type": "string", "description": "营业执照法定代表人身份证号（必填）" }, "legal": { "type": "string", "description": "营业执照法定代表人身份证正面照base64（必填）" }, "notiPhone": { "type": "string", "description": "联系人号码" }, "biz": { "type": "string", "description": "该签名对应营业执照图片base64，（格式：jpg、png）" }, "use_for_explain": { "type": "string", "description": "签名用途描述（产品链接等）" } }, "required": [ "title", "use_for", "use_for_des", "legal_name", "legal_ID", "legal", "notiPhone", "biz", "use_for_explain" ] } } } } } }, "/28-15": { "x-pointCode": 15, "x-mode": "mapping", "x-read-timeout": 15, "x-connect-timeout": 15, "post": { "summary": "获取上行短信", "description": "接收用户回复的信息。通过这一功能，应用程序可以实时接收并处理用户发送的短信，实现与用户的互动。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "allPages": { "type": "number", "description": "总页码" }, "ret_code": { "type": "string", "description": "返回标识，0为成功，其它失败" }, "contentlist": { "type": "array", "items": { "type": "object", "properties": { "receiveTime": { "type": "string", "description": "回复时间" }, "msg": { "type": "string", "description": "回复内容" }, "mobile": { "type": "string", "description": "回复号码" } } }, "description": "内容列表" }, "remark": { "type": "string", "description": "返回表述" }, "currentPage": { "type": "number", "description": "当前页" }, "allNum": { "type": "number", "description": "查询总数" }, "maxResult": { "type": "number", "description": "当前返回最大数" }, "success": { "type": "number", "description": "扣费标识" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_15_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "page": { "type": "string", "description": "查询页码" }, "date": { "type": "string", "description": "查询日期（yyyy-MM-dd）" }, "mobile": { "type": "string", "description": "查询号码" } } } } } } } }, "/28-13": { "x-pointCode": 13, "x-mode": "mapping", "x-read-timeout": 5, "x-connect-timeout": 5, "post": { "summary": "屏蔽词关键字查询", "description": "检测短信内容是否含有屏蔽词,含有屏蔽词的短信是不能进行发送的。这些屏蔽词可能包括一些敏感词汇、侮辱性语言或其他被禁止的内容。如果短信内容中含有这些屏蔽词，短信将无法发送。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "扣费标识,0标识接口操作成功,已扣费. 其他值不扣费" }, "msg": { "type": "string", "description": "检测结果说明(内容中有多个屏蔽词的时候,只返回最先检测到的屏蔽词)" }, "flag": { "type": "string", "description": "检测结果是否通过" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_13_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "要检测的短信内容" } }, "required": [ "content" ] } } } } } }, "/28-12": { "x-pointCode": 12, "x-mode": "mapping", "x-read-timeout": 30, "x-connect-timeout": 30, "post": { "summary": "发送语音验证码", "description": "提供4-6位的语音验证码,验证码通过打电话的方式告知接收方", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "提交是否成功,为0表示成功,其他为失败" }, "remark": { "type": "string", "description": "提示信息" }, "taskID": { "type": "string", "description": "请求流水" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_12_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "mobile": { "type": "string", "description": "接收语音验证码的手机号码" }, "content": { "type": "string", "description": "发送的验证码,只能是4-6位的数字" } }, "required": [ "mobile", "content" ] } } } } } }, "/28-9": { "x-pointCode": 9, "x-mode": "mapping", "x-read-timeout": 5, "x-connect-timeout": 5, "post": { "summary": "删除自定义模板", "description": "每位易源平台上的用户，最多只能创建有限的签名和短信模板，该操作可以清除无用的模板，节省模板使用量", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "0成功其他失败" }, "remark": { "type": "string", "description": "备注" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_9_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "tNum": { "type": "string", "description": "模板id" }, "tNumAlias": { "type": "string", "description": "短信自定义code，每个用户下唯一" } } } } } } } }, "/28-7": { "x-pointCode": 7, "x-mode": "mapping", "x-read-timeout": 30, "x-connect-timeout": 30, "post": { "summary": "步骤(6)_查询发送历史及结果", "description": "短信API通常提供了一个查询发送历史及结果的功能。通过这个功能，用户可以回顾过去的短信发送记录情况，此接口的历史数据只保留15天内的。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "查询结果 0成功其他失败" }, "remark": { "type": "string", "description": "备注" }, "allNum": { "type": "string", "description": "总条数" }, "allPages": { "type": "string", "description": "总页数" }, "currentPage": { "type": "string", "description": "当前页数" }, "maxResult": { "type": "string", "description": "每页最大条数(固定值20条)" }, "datas": { "type": "array", "items": { "type": "object", "properties": { "statusCode": { "type": "string", "description": "运营商返回的状态码，有DELIVRD或0:0字样是成功" }, "content": { "type": "string", "description": "短信正文" }, "successCounts": { "type": "string", "description": "扣费次数" }, "remark": { "type": "string", "description": "备注" }, "receiveTime": { "type": "string", "description": "短信状态确定时间（状态由0变为10或20的时间）" }, "sendStatus": { "type": "string", "description": "状态。0为待发送，10发送成功，20发送失败。判断短信状态以此字段即可" }, "ct": { "type": "string", "description": "短信发送时间" }, "mobile": { "type": "string", "description": "机主号码" } } }, "description": "历史数据条目" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_7_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "mobile": { "type": "string", "description": "发送的号码(每次查询一个号码)" }, "page": { "type": "string", "description": "页码" }, "taskID": { "type": "string", "description": "任务ID（与其他参数互斥,如果输入taskID,其他参数则不需要输入）" }, "startDate": { "type": "string", "description": "查询开始时间（yyyy-MM-dd）" }, "endDate": { "type": "string", "description": "查询结束时间（yyyy-MM-dd）" } } } } } } } }, "/28-3": { "x-pointCode": 3, "x-mode": "mapping", "x-read-timeout": 15, "x-connect-timeout": 15, "post": { "summary": "步骤(4)_查询自定义短信模板", "description": "该接入点用于查询该用户下，已经创建的模板情况，比如是否审核通过、不通过的原因说明等信息", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "成功标记 0成功其他失败" }, "templates": { "type": "array", "items": { "type": "object", "properties": { "0": { "type": "object", "properties": { "content": { "type": "string", "description": "模板内容" }, "title": { "type": "string", "description": "模板标题" }, "status": { "type": "string", "description": "模板状态（0、待审核，1、审核通过，2、审核驳回）" }, "tNum": { "type": "string", "description": "模板ID" }, "ct": { "type": "string", "description": "创建时间" }, "sendContentSample": { "type": "string", "description": "发送内容的示例jsonstring" }, "latest_check_template": { "type": "object", "properties": {}, "description": "最后一次编辑提交审核的模板内容" }, "check_time": { "type": "string", "description": "审核时间" } } } } }, "description": "模板列表" }, "remark": { "type": "string", "description": "备注" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_3_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "page": { "type": "string", "description": "页码" }, "tNum": { "type": "string", "description": "创建模板返回的模板编号" }, "title": { "type": "string", "description": "已创建的短信签名" }, "tNumAlias": { "type": "string", "description": "创建模板时输入您的模板名称" } } } } } } } }, "/28-2": { "x-pointCode": 2, "x-mode": "mapping", "x-read-timeout": 15, "x-connect-timeout": 15, "post": { "summary": "步骤(3)_创建自定义短信模板", "description": "创建短信模板的作用是便于运营商和易源平台方，知晓接口使用方的短信需求，以确认使用方是否合理合法的使用我方的短信API。所以，创建模板是需要我方平台进行人工审核的，一般为1个工作日内审核完毕。平台审核通过后即可进行短信接口的对接和发送，同时我们也会提交给运营商审核，一般1-3个工作日。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "成功标记 0 成功其他失败" }, "remark": { "type": "string", "description": "备注" }, "tNum": { "type": "string", "description": "在平台创建好的模板id" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_2_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "tNumAlias": { "type": "string", "description": "短信模板名称，用户自定义传入，与返回字段tNum一样用来识别模板，每个账号下的别名不能重复" }, "title": { "type": "string", "description": "已创建的模板签名,公司名称或项目名称，使用UTF-8编码（3-8个字符的纯中文或中英文）" }, "content": { "type": "string", "description": "动态内容使用,使用UTF-8编码 (70字符含自定义签名,超过70，请传big_msg=1参数,超过70字符按67个字符算一条短信)最多400个字符" }, "notiPhone": { "type": "string", "description": "模板的联系人信息,便于审核模板后,告知模板的审核情况!" }, "real_content": { "type": "string", "description": "短信发信真实的内容样例，请勿乱填" }, "description": { "type": "string", "description": "短信内容场景说明" } }, "required": [ "tNumAlias", "title", "content", "notiPhone", "real_content", "description" ] } } } } } }, "/28-1": { "x-pointCode": 1, "x-mode": "mapping", "x-read-timeout": 40, "x-connect-timeout": 40, "post": { "summary": "步骤(5)_发送短信", "description": "提交短信接收方的手机号（国内用户）、模板编号和对应模板中的参数值，短信接口会根据模板内容和参数值，组装成完整的短信发送给接收方。当批量发送或者发送长短信时，认为是发送了多条短信，所以一次请求可能会有多条短信的扣费记录。", "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ShowapiResEnvelope" }, { "type": "object", "properties": { "showapi_res_body": { "type": "object", "properties": { "ret_code": { "type": "string", "description": "0为提交到队列成功，其他失败。" }, "remark": { "type": "string", "description": "描述信息" }, "taskID": { "type": "string", "description": "任务ID" }, "successCounts": { "type": "string", "description": "计费长度" } }, "description": "业务返回体" } } } ] } } } } }, "operationId": "28_1_POST", "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "tNum": { "type": "string", "description": "短信模板ID。用户创建模板时返回，和tNumAlias短信模板别名不能同时为空，同时传入以tNum为主，(请先按照示例,建立自己的模板库)" }, "tNumAlias": { "type": "string", "description": "短信模板别名。用户创建模板时自定义传入，与tNum一样用来识别模板，每个账号下的别名不能重复，两者不能同时为空，同时传入以tNum为主" }, "mobile": { "type": "string", "description": "手机号码。如需群发短信，多个号码之间请使用英文逗号隔开，上限为20个号码。例如:13800008888,13900223366,..." }, "content": { "type": "string", "description": "用于替换短信模板内容中的参数。支持两种格式：1、name**:张三@@code**:1234\n2、使用json格式对应模板的键值对，请使用使用UTF-8编码。强调下,json中的key和value如果不是数字,则必须用双引号包裹,不要用单引号。" }, "big_msg": { "type": "string", "description": "长短信标识。当短信字符个数超过70字符时，此标识请设置为1。不设置或设置为其他值，默认发70以内字符个数的短信，此时若发生长短信会因字符数限制导致发送失败。短信字符数是指替换模板中参数后加上签名的字符数之和，及用户收到的完整的短信字符个数。当请求big_msg=1且字符个数超过70时，每条短信按67字符计费，一条长短信请限制在400个字符以内。 " } }, "required": [ "mobile" ] } } } } } } }, "components": { "securitySchemes": { "AppKeyAuth": { "type": "apiKey", "in": "query", "name": "appKey", "description": "从 ShowAPI 控制台获取的 appKey，管理地址：https://www.showapi.com/console#/myApp" } }, "schemas": { "ShowapiResEnvelope": { "type": "object", "description": "ShowAPI 统一返回包裹（业务数据位于 showapi_res_body）", "properties": { "showapi_res_code": { "type": "integer", "description": "API 返回的状态码" }, "showapi_res_error": { "type": "string", "description": "API 返回的错误信息" }, "showapi_res_id": { "type": "string", "description": "API 请求的唯一标识" }, "showapi_fee_num": { "type": "integer", "description": "API 调用计费次数" } } } } }, "security": [ { "AppKeyAuth": [] } ], "externalDocs": { "url": "https://www.showapi.com/apiGateway/view/28?tab=book" }, "x-apiCode": "28", "x-is-own": false, "x-is-op": true }