SDK通用版接口文档.doc

SDK通用版接口调用说明Ao SDK通用版接口调用说明版本：2.0 第一次修订时间：2011-01-06第二次修订时间：2011-01-14 第三次修订时间：2011-12-15目录1请仔细阅读信息安全责任保证条款- 3 -1.1安全信息责任条款- 3 -1.2注意事项：- 4 -2Webservice接口- 4 -2.1webservice返回集合对照表- 4 -2.2Register注册(信息必须真实, 短信出现问题联系不上使用者后果自负.)- 5 -2.3balance 查询余额- 6 -2.4ChargUp充值- 6 -2.5mt 发送短信- 7 -2.6mo接收短信- 8 -2.7gxmt 个性发送- 9 -3Http接口- 11 -3.1http返回集合对照表- 11 -3.2发送短信- 11 -3.3接收短信- 11 - 3.4查询余额- 11 -5发送说明- 16 -5.1做单发说明- 16 -5.2做群发说明- 16 -5.3编码说明- 16 -5.4长短信说明- 16 -5.5长短信扣费说明- 16 -6接收说明- 17 -7附加说明- 17 -7.1接口地址- 17 -7.2其它说明- 17 -7.3郑重声明- 17 -1 请仔细阅读信息安全责任保证条款1.1 安全信息责任条款本人/本公司在使用本软件过程中，将严格遵守国家相关法律、法规、保证本公司信息发布的安全，并切实做到：（1） 建立健全本公司信息发布的内部保障制度、信息安全保密制度、用户信息安全管理制度，建立健全本公司信息安全责任制度和信息发布的审批制度，严格审查本公司产品所发布信息。（2） 严格遵守互联网信息服务管理办法，对用户编辑的信息内容进行把关，保证信息内容的健康、合法。 （3） 明确本企业的客户群和客户范围，所有通讯受众必须是自愿且明确同意接受企业服务。（4） 若发送未经用户允许的信息等所造成的影响、投诉等一切损失与本软件版权方无关、由本人/本公司承担全部责任；同时，本人/本公司也应承担若因此给本软件版权方造成的全部损失。（5） 不利用本软件制作、复制、发布、传播含有下列内容的信息： 反对宪法所确定的基本原则的； 危害国家安全，泄露国家秘密，颠覆国家政权，破坏国家统一的； 损坏国家荣誉和利益的； 煽动民族仇恨、民族歧视，破坏民族团结的； 破坏国家民族宗教政策，宣扬邪教和封建迷信的； 散布谣言，扰乱社会秩序，破坏社会稳定的； 散布淫秽、色情、赌博、暴力、凶杀、恐怖或者教唆犯罪的； 侮辱或者诽谤他人，侵害他人合法权益的； 含有法律、行政法规禁止的其他内容的；（6） 自信息发布六个月内不修改删除信息发送日志内容，日志记录的备份应至少保持6个月以上，在国家机关进行依法查询时，予以提供。（7） 若发现本公司所发布的信息明显属于上述第（5）款所列内容，保证立即停止传输，并向国家有关机关报告。 （8） 对本公司所发布的信息一时难以辨别是否属于以上所列内容之一的，应报相关主管部门审核同意后再发布。（9） 对客户的个人信息保密，未经客户同意不得向他人泄漏，但法律规定的除外。本人/本公司保证：在使用本软件进行信息发布活动中，服从监督和管理；若未做到上述一至八条，本人/本公司愿意承担由此引起的一切法律责任，并接受相应的处罚。1.2 注意事项：同一个序列号提交，必须提交到同一个SDK服务器；同一个序列号提交，必须等上一批次返回后再提交下一批次；相同内容，不同手机号，请使用mt，每次建议5000个手机号；不同内容，不同手机号，请使用gxmt，每次建议1000个手机号；为了便于技术与技术之间的沟通及后期维护事宜的及时通知, 请负责开发人员将您的联系方式发至Email: 或者直接添加QQ(技术支持): 1582387575、1615759500.谢谢配合.各个发短信的方法，都没有数据合法性的验证。请您在提交之前，做好此项工作，以避免不必要的扣费。2 Webservice接口2.1 webservice返回集合对照表 返回值返回值说明问题描述1没有需要取得的数据取用户回复就出现1的返回值,表示没有回复数据-1重复注册多次点击“注册”按钮或注册方法（Register）的“调用”按钮-2 帐号/密码不正确1.序列号未注册2.密码加密不正确3.密码已被修改4.序列号已注销-4余额不足直接调用查询看是否余额为0或不足-5数据格式错误只能自行调试了。或与技术支持联系-6参数有误看参数传的是否均正常,请调试程序查看各参数-7权限受限该序列号是否已经开通了调用该方法的权限-8流量控制错误-9扩展码权限错误该序列号是否已经开通了扩展子号的权限,把ext这个参数置空。-10内容长度长短信内容过长，纯单字节不能超过1000个，双字节不能超过500个字符2.彩信不得超过50KB-11内部数据库错误-12序列号状态错误序列号是否被禁用-13没有提交增值内容提交时，无文本或无图片-14服务器写文件失败-15文件内容base64编码错误-16返回报告库参数错误-17没有权限如发送彩信仅限于SDK3-18上次提交没有等待返回不能继续提交默认不支持多线程-19禁止同时使用多个接口地址每个序列号提交只能使用一个接口地址-20相同手机号，相同内容重复提交-21Ip鉴权失败提交的IP不是所绑定的IP注:以上返回值针对个别方法.请具体参看每个用到方法的详细说明。2.2 Register注册(信息必须真实, 短信出现问题联系不上使用者后果自负.)参数名称说明备注Sn软件序列号格式XXX-XXX-XXX-XXXXX 由商务处获得Pwd密码6-8位 明文Province省必填City市必填Trade行业必填Entname公司名称必填Linkman联系人必填Phone电话必填Mobile移动电话必填Email邮件地址必填Fax传真必填Address地址必填Postcode邮政编码必填Sign企业签名(2-15个字符) 可空注:使用序列号的第一步即激活序列号的状态.和使用者进行绑定.如不注册便发送短信会返回相应的返回值-2.除sign参数可为空其它均为必填项.请认真对待这些参数的真实性.短信出现问题联系不上使用者后果自负.返回结果:XML格式: 文本格式: 0 成功。2.3 balance 查询余额参数名称说明备注Sn软件序列号格式XXX-XXX-XXX-XXXXXPwd密码md5(sn+password) 32位大写 密文 +表示连接函数返回值：String（余额）示例：序列号SDK-BBX-010-00001 密码 123456参数输入：SN= SDK-BBX-010-00001PWD= 3B5D3C427365F40C1D27682D78BB31E0返回结果:XML格式:文本格式:791092.4 ChargUp充值参数名称说明备注Sn软件序列号XXX-XXX-XXX-XXXXXpwd密码123456 此处为明文cardno充值卡号充值卡号 由商务处获得cardpwd充值卡密码充值密码 由商务处获得函数返回值:string返回结果:XML格式:文本格式:0 成功。2.5 mt 发送短信参数名称说明是否必须 备注Sn软件序列号是格式XXX-XXX-XXX-XXXXXPwd密码是md5(sn+password) 32位大写密文Mobile手机号是必填(支持10000个手机号,建议=5000)多个手机号中间以英文逗号隔开Content内容是支持长短信(详细请看长短信扣费说明)Ext扩展码否例如：123（默认置空）stime定时时间否例如：2010-12-29 16:27:03（非定时置空）Rrid唯一标识否最长18位 ( 如要传值 只能传：数字或者 字母 或者数字+字母的组合)函数返回值：String（唯一标识，即当前发送短信批次的唯一标识,和rrid对应，如为空则返回系统生成的rrid）此方法推荐用于大量群发.内容相同手机号多个示例1SN= SDK-BBX-010-00001PWD=3B5D3C427365F40C1D27682D78BB31E0Mobile:139*404,138*213.Content:测试Ext: Stime: Rrid: 输出结果:XML格式:文本格式:201012300908160937。示例2：输入参数：SN= SDK-BBX-010-00001PWD=3B5D3C427365F40C1D27682D78BB31E0Mobile:139*404,138*213.Content:测试Ext:21（默认，请置空）Stime: 2009-10-19 16:34:00 （如果不需要定时，请置空）Rrid:123456 （如果填写则系统返回填写内容，如果置空，返回系统生成的rrid）输出结果：XML格式:文本格式:123456补充说明：扩展码即ext参数，需要您和商务或着客服沟通好。确定您要扩展码的位数。是2位还是3位还是几位。（扩展码不是想要多少位都可以，比如超过6位，基本上都是无效的）然后由我们技术来开通。扩展码的用法：您发送短信时，有个ext参数，您给它传值并且要保证每次唯一，用于区分给同一个客户发的多条短信。例如：您给客户A，在10点发了一条短信，在12点又发了一条，15点又发了一条，到了晚上，客户A给您回复了。您如何判断客户A回复的是哪条短信呢。可以通过ext这个参数实现。您在10点发那条短信时，当时给ext传的是3，一旦客户回复了您一条短信。我们会把这个3，带回给您，以此来达到区分给同一个客户发的多条短信的目的。2.6 mo接收短信参数名称说明备注Sn软件序列号格式XXX-XXX-XXX-XXXXXPwd密码md5(sn+password) 32位大写密文函数返回值：Stirng 返回值说明：mo ID，特服号，手机号，内容（对内容进行gb2312解码），时间 如有多条回车换行隔开 n返回结果:XML格式:文本格式:12323666,47512%b2%e2%ca%d41,2010-12-30 9:15:56注:拆分形式为 先n拆分成数组,然后逗号拆分成数组.根据索引读出需要的数据.内容要GB2312解码。如果发送时ext=3 用子号3发送了 那么调用mo之后 第二个参数47512 就变成了475123了由此可以判断用户是回复的那条短信或者哪个应用!上行只能取一次，即客户的回复内容只能取一次。2.7 gxmt 个性发送参数名称说明是否必须 备注Sn软件序列号是格式XXX-XXX-XXX-XXXXXPwd密码是md5(sn+password)32位大写密文Mobile手机号是必填(建议一次最多提交1000个)Content内容是支持长短信(详细请看长短信扣费说明)Ext扩展码否例如：123（默认置空）Stime定时时间否例如： 2010-12-30 9:23:20（非定时置空）Rrid唯一标识否最长18位( 如要传值 只能传：数字或者 字母 或者数字+字母的组合)函数返回值：String （唯一标识，即当前发送短信批次的唯一标识,和rrid对应，如为空则返回系统生成的rrid,此处的rrid和mt发送的rrid用法相同,此方法用于发送多条内容不相同手机号多个的情况）需要注意:1、手机号以英文逗号隔开2、发送内容GB2312编码后，以英文逗号隔开，个数和手机号个数一致3、扩展码可以为空，单个，或多个（以英文逗号隔开，个数和手机号个数一致）4、定时时间可以为空，单个，或多个（以英文逗号隔开，个数和手机号个数一致）返回结果:XML格式:示例1：输入参数：SN= SDK-BBX-010-00001PWD=3B5D3C427365F40C1D27682D78BB31E0Mobile:139*404,138*213Content: %B2%E2%CA%D41, %B2%E2%CA%D42Ext:（默认，请置空）Stime: （如果不需要定时，请置空）Rrid:123456 （如果填写则系统返回填写内容，如果置空，返回系统生成的rrid）输出结果：XML格式:文本格式:123456示例2SN= SDK-BBX-010-00001PWD=3B5D3C427365F40C1D27682D78BB31E0Mobile:139*404,138*213.Content: %B2%E2%CA%D41, %B2%E2%CA%D42Ext: Stime: Rrid: 此处为空输出结果:XML格式:文本格式:201012300908160937。3 Http接口3.1 http返回集合对照表返回值返回值说明问题描述0没有需要取得的数据取用户回复就出现0的返回值,表示没有回复数据-4扩展码错误把ext参数置空-3序列号密码不正确1.序列号未注册2.密码加密不正确3.密码已被修改-2参数错误看参数传的是否均正常,请调试程序查看各参数-1发送失败检查是否有余额,3.2 发送短信默认情况下，序列号是单机版。如果不知道自己的序列号是不是网络版的，可以问销售人员或技术人员或客服。Eg: (ext不传值):8060/z_mdsmssend.aspx?sn=SDK-XXX-010-XXXXX&pwd=MD5(sn+pwd)&mobile=135*4752&content=你好Eg: (ext可传值):8060/z_mdsmssend.aspx?sn=SDK-XXX-010-XXXXX&pwd=MD5(sn+pwd)&mobile=135*4752&content=你好&ext=1sn:序列号，pwd:密码(密码要经过Md5(sn+pwd)32位大写加密)，mobile:手机号，用,隔开，content:发送内容，ext:扩展码注1：如果是第一次使用，请先注册(注册方法请参看附加说明)注2:HTTP方式只有发送和接收两种方法，其它方法可以通过demo或webservice接口实现其它功能的操作注:Get由于字符串长度限制,手机号个数请小于等于500 Post 理论是没有长度限制,但手机号一次不能超过10000.3.3 接收短信结果说明结果说明-2参数错误 0 表示没有需要接受的短信-1 操作失败 -3序列号密码错误Eg: (单机版):8060/z_receive.aspx?sn=SDK-XXX-010-XXXXX&pwd=888888ext=0sn:序列号，pwd:密码 注：http方式需保证帐号是正常状态 Eg: (接收子号的上行,需要和发送短信时配合使用):8060/z_receive.aspx?sn=SDK-XXX-010-XXXXX&pwd=888888&ext=子号sn:序列号，pwd:密码，ext:扩展码(0：接收所有子号码；其他：接收此子号码注：http方式需保证帐号是正常状态 返回示例:331307652547XXX1520169XXXX测试12011-1-13 17:51:181307652947XXX1520169XXXX测试22011-1-13 17:51:241307653247XXX1520169XXXX测试32011-1-13 17:51:29返回值说明:第一行表示 总数 当前行数从第二行开始是用户回复的数据 各个元素分别为:数据id,特服号,手机号,内容,用户回复时间行与行之间是n 分隔 各个元素之间是t分隔 一次最多返回5条记录3.4 接收短信 :8060/z_balance.aspx?sn=SDK-XXX-010-XXXXX&pwd=888888返回值为:string 4 发送说明4.1 做单发说明（每次提交只有一个手机号）时，在一个时间点需要发送N条相同内容不得超过20次.如果需要发送大量的单条信息并且内容不相同,请参考gxmt的方法;4.2 做群发说明(提交内容相同)时,请参看mt 的使用方法,禁止连续一条一条的提交.4.3 编码说明接口所