{ "openapi": "3.0.3", "info": { "title": "三网短信通知类（需要模板）", "description": "三网合一短信通知接口，适用于验证码、通知等场景，支持虚拟运营商，可自定义模板变量，快速送达，可靠服务。仅对企业用户提供服务，需企业认证。", "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": "步骤(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": "创建自定义签名需提交身份证正面照至客服处审核，通常3-5个工作日。签名有使用时效：实名成功后7天试用期未使用则失效；通过试用期后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": "创建短信模板旨在让运营商和易源平台了解使用方的短信需求，以便确认使用是否合规。模板需经平台人工审核，通常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": false }