短信平台接口说明.doc

短信平台接口说明第1章 基本约定 第1节 基本术语:前台流水号：前台流水号就是发送短信上送的批次号，一般在私有字段里面。后台流水号：后台流水号是当提交成功之后短信平台返回给前端的流水号，此流水号在短信的所有业务中都是唯一的。(1) 上送文件格式以一行为一条短信数据.(2) 提交成功之后,返回报文的分隔符为”:”.(3) 群发短信手机号码之间采用的分隔符为”,”.(4) 私有字段的分隔符采用”$”(5) 非明确说明的,分隔符都采用”|”. 第2节 基本原理及提交成功返回短信平台基本原理如下所示:提交成功有文件类和单条短信返回:(1) 单条短信单条短信返回的格式为:|respcode 0000| respmsg发送成功| frountid前台流水号| backofficeid后台流水号|其中前台流水号为发送时前台请求时上送的批次号,后台流水为短信平台后台的流水号.webservice返回定义:key描述valuerespcode返回码respmsg返回信息frountid前台流水号backofficeid后台流水号(2) 文件请求文件格式的报文返回为:|respcode0000|respmsg发送成功|frountid前台文件批次号| frontfilename前台文件名| backofficeid后台文件批次号| 其中后台文件序列号由短信平台生成.webservice返回定义:key描述valuerespcode返回码respmsg返回信息frountid前台文件批次号frontfilename前台文件名backofficeid后台文件批次号 第3节 tcp接口必须要传送报文头报文头的定义如下:含义位置长度类型属性说明报文域长度04xm报文体长度流水号4路由号4第一个为报文域长度，其中包含整个报文头的12字节。第二个为流水号，可以传定值1第三个是路由号，传8十六进制例子表示如下:33 00 00 00 01 00 00 00 08 00 00 00 7c 39 39 39 39 7c 7c 31 33 33 32 33 35 39 31 36 33 38 7c b6 cc cf fb cf a2 b2 e2 ca d4 b7 a2 cb cd d0 c5 cf a2 7c 5e 定义的结构体typedef structunsigned int uipacketlength; /包长，包含包头长度的总长度unsigned int uisequenceid; /标识包的唯一id，由客户端填写unsigned int commandid; /路由号，一般固定为8或与短信平台协商msg_header_t;第2章 webservice接口说明提供两个类型的方法给调用即：单条发送方法，群发serviceurl：http:/指定ip地址:端口 / smswebservice.asmxservicename: smswebservice 第1节 单条发送方法短信串的具体内容如下:|短信发送交易码|私有字段|手机号码|发送信息|其中短信交易码为9999.私有字段定义:短信类型$发送人(部门)$提交人$业务类型$提交时间$开始日期$开始时间$结束日期$结束时间$批次号$是否需要回执$其中，开始日期、开始时间、结束日期、结束时间不定义（置空）则立即发送例如: 6$xd$3$20090907102700$20090907$102700$20090907$205959$0907123456$ 短信类型为6,7,其中6为信贷系统日间短信,7为信贷系统日终短信.业务类型为2,人工定制短信.例如:|trancode9999|smstype6|departmentxd|sender6221|bussinesstype1|sendtime20100514134500|begindate20100514|begintime080101|enddate20100514|endtime205959|seriono1253535|isback1|mobilcontent信贷系统短信测试|具体描述:key描述valuetrancode短信发送交易码9999smstype短信类型6department发送人(部门)xdsender提交人bussinesstype业务类型1sendtime提交时间begindate开始日期begintime开始时间enddate结束日期endtime结束时间seriono批次号isback是否需要回执mobile手机号码content发送信息/ / 单条发送短信(标准版)/ / 短信串/ 返回-1:数据库操作失败;0:数据没更新:大于0:正确public int sendsms(string content) 第2节 群发（一笔最大条数1000,tcp方式一次最多20）短信串的具体内容如下:|短信发送交易码|私有字段|手机号码串|发送信息|群发短信分隔符|其中短信交易码为9996.私有字段定义:短信类型$发送人(部门)$提交人$业务类型$提交时间$开始日期$开始时间$结束日期$结束时间$批次号$是否需要回执$其中，开始日期、开始时间、结束日期、结束时间不定义（置空）则立即发送,分隔符为空,则默认”,”作为分割符.例如: 6$xd$3$20090907102700$20090907$102700$20090907$205959$0907123456$ key描述valuetrancode短信发送交易码9996smstype短信类型6department发送人(部门)xdsender提交人bussinesstype业务类型1sendtime提交时间begindate开始日期begintime开始时间enddate结束日期endtime结束时间seriono批次号isback是否需要回执mobile手机号码content发送信息separator群发短信手机号码分隔符/ / 群发短信(标准版)分隔符是“,”/ / 短信串/ 返回-1:数据库操作失败;0:数据没更新:大于0:正确public int sendmoresms(string content) 第3章 文件群发接口 第1节 通讯接口文件接口的目的是当客户端需要通过文件发送短信的时候,首先通过webservice或者tcp/ip告知短信平台要发送文件.文件传送采用ftp和tcp/ip的方式.具体如下:1. webservice接口.短信串的具体内容如下:|短信发送交易码|私有字段|文件类型|文件名|其中短信交易码为9995.私有字段定义:短信类型$发送人(部门)$提交人$业务类型$提交时间$开始日期$开始时间$结束日期$结束时间$批次号$是否需要回执$发送文件时,批次号为前台上送的文件批次号例如：|trancode9995|smstype6|departmentxd|sender6221|bussinesstype1|sendtime20100514134500|begindate20100514|begintime080101|enddate20100514|endtime205959|seriono1253535|isback1|filetypetxt|filenametemp.txt|key描述valuetrancode短信发送交易码9995smstype短信类型6department发送人(部门)xdsender提交人bussinesstype业务类型1sendtime提交时间begindate开始日期begintime开始时间enddate结束日期endtime结束时间seriono批次号isback是否需要回执filetype文件类型filename文件名/ / / / 短信串/ 返回-1:数据库操作失败;0:数据没更新:大于0:正确public int sendmoresms(string content)返回报文：|respcode0000|respmsg发送成功|frountid5|frontfilenametemp.txt|backofficeid|2. tcp/ip接口短信串的具体内容如下:|短信发送交易码|私有字段|文件类型|文件名|其中短信交易码为9995.私有字段定义:短信类型$发送人(部门)$提交人$业务类型$提交时间$开始日期$开始时间$结束日期$结束时间$批次号$是否需要回执$发送文件时,批次号为上送的文件批次号如:00$hx$8001$0$20090907102700$20090907$102700$20090907$205959$0907123456$1$ 第2节 文件传输接口文件传输接口的方式有以下两种,其中一种为通过socket传输文件流的方式,另外一种就是ftp方式,文件最大为20m.文件内部每条短信的定义如下:|序列号|手机号码|内容|(1) socket传输文件流的方式暂时不支持(2) ftp方式当短信平台收到发送文件类型的短信之后,通过ftp双方约定的目录获取文件,然后解析文件开始发送.第4章 数据库的接口接口模式：采用数据库模式数据库版本：sql server 2000实现原理：直接把数据插入到短信数据库（call）的短信提交表（sms_request），通过短信平台发出，提交之前需要先通过nextvalue方式获取内部流水号。短信提交表的建表语句和字段说明：create table sms_request(smsidint identity (1, 1) not null , priority int not null default 0, -优先级，默认0：最低batchnovarchar(16), -批次号summittimevarchar(14), -提交时间beginsetdatevarchar(8), -设置发送日期beginsettime varchar(6), -设置发送时间endsetdatevarchar(8), -设置发送日期endsettime varchar(6), -设置结束时间smstypevarchar(4), -短信类型departmentvarchar(4), -业务部门bussniesstypevarchar(4), -业务类型telephonevarchar(18), -手机号码contentvarchar(1024), -短信内容)插入数据说明：不必填写smsid。必须填写的字段包括：提交时间（summittime），设置开始发送日期（beginsetdate），设置开始发送时间（beginsettime），设置结束发送日期（endsetdate），设置结束发送时间（endsettime），短信类型（smstype），手机号码（telephone），短信内容（content）其中提交时间一般是取当前时间就可以了，短信类型固定填写3。第5章 socket接口说明 第1节 原理图银行后台commgw，负责与短信平台的客户端通信、重发机制等emg短信网关，与移动、联通、固网的协议接口银行后台或其他短信平台的客户端通过与commgw接口实现短信发送的功能。 第2节 交易格式支持不可变和可变两种交易格式。9999交易是简单的不可变格式的方式，仅需把号码和信息完整内容发出即可；9998交易或其他自定义的交易，是可转化格式的方式，可由银行后台与短信平台做出字段约定，并对多个字段做转化处理，拼接成完整的短信内容。5.2.1 内容不可变得简单格式的交易交易请求格式：|9999|privatedata|mobileno|context|9999|私有字段|手机号码|发送信息|注：私有字段一般为空即可若需要,请参照以下定义.私有字段定义:短信类型$发送人(部门)$提交人$业务类型$提交时间$开始日期$开始时间$结束日期$结束时间$批次号$是否需要回执$其中，开始日期、开始时间、结束日期、结束时间不定义（置空）则立即发送例如: 6$xd$3$20090907102700$20090907$102700$20090907$205959$0907123456$如：|9999|6$xd$5031$3$20090907102700$20090907$102700$20090907$205959$0907123456$1您尾号6002单位帐号于09:04转出人民币2,001.00元，余额791,053.83元。24小时服务热线:96558。|5.2.2 可转换信息格式的交易交易请求格式如下：|9998|privatedata|account|briefcode|tradeflag|trandate|tranamount|amountflag|currency|mobileno|name|gender|context|businesscode|9998|附加信息|卡号|交易类型|交易标志|交易日期时间|交易金额|交易金额符号|币种|手机号码|姓名|性别|发送信息|业务代码|如：|9998|6224280002510100|7000|o|0621090041|500.00|-|156王锋|lc|字段里的内容可根据短信平台的客户端与短信平台协商说明，可参考shortmessage.ini。亦可自定义其他交易。 第3节 通讯协议短信平台与银行后台采用tcp协议短连接方式。报文具体格式如下：5.3.1 短信平台的请求报文 描述含义位置长度类型属性说明报文域长度04xm报文体长度流水号4路由号4第一个为报文域长度，其中包含整个报文头的12字节。第二个为流水号，可以传定值1第三个是路由号，传8十六进制例子表示如下:33 00 00 00 01 00 00 00 08 00 00 00 7c 39 39 39 39 7c 7c 31 33 33 32 33 35 39 31 36 33 38 7c b6 cc cf fb cf a2 b2 e2 ca d4 b7 a2 cb cd d0 c5 cf a2 7c 5e 定义的结构体 报文头typedef structunsigned int uipacketlength; /包长，包含包头长度的总长度unsigned int uisequenceid; /标识包的唯一id，由客户端填写unsigned int commandid; /路由号，一般固定为8或与短信平台协商msg_header_t; 报文体typedef structchar commanddata1; /交易请求字符串，此处不固定长度具体见5.2.1msg_request_t;5.3.2 短信平台的应答报文 描述返回的例子:0000:发送成功 报文头typedef structunsigned int uipacketlength; /包长，包含包头长度的总长度unsigned int uisequenceid; /标识包的唯一id，由客户端填写msg_header_t; 报文体typedef structint status; /包状态，0表示发送成功，非0表示出错无法发送char resultdata1; /响应包数据，此处不固定长度msg_response_t;第6章 短信回执接口说明短信回执接口是当客户端需要短信回执的时候,由客户端主动发起获取短信回执的交易,短信平台通过查询相应的短信回执.回执接口查询支持webservice和tcp/ip两种类型的接口.其中webservice仍然采用短信串的方式.tcp/ip请求和返回的时候需要有报文头.报文头定义如下:含义位置长度类型属性说明报文域长度04xm报文体长度流水号4路由号4 第1节 单条短信查询(1) 请求报文短信格式如下:|短信发送交易码|私有字段|后台流水号|其中短信交易码为9994.私有字段定义:短信类型$发送人(部门)$提交人$业务类型$批次号$后台流水号为提交成功时返回的后台流水号.批次号为各业务部门发送短信时上送的批次号.webserivice接口定义如下:例子: |trancode9994|smstype6|departmentxd|sender6221|bussinesstype1|seriono1253535|backid1124366|key描述valuetrancode短信发送交易码9994smstype短信类型6department发送人(部门)xdsender提交人bussinesstype业务类型1seriono批次号backid后台流水号(2) 应答报文返回报文的格式如下:|返回码|返回信息|前台流水号|后台流水号|其中前台流水号为发送短信上送的批次号,后台流水号为提交成功时返回的后台流水号.webserivec接口返回定义如下:例如: |respcode 0000| respmsg发送成功| frountid前台流水号| backofficeid后台流水号|key描述valuerespcode返回码respmsg返回信息frountid前台流水号backofficeid后台流水号 第2节 文件类短信查询接口(1) 请求报文短信格式如下:|短信发送交易码|私有字段|文件类型|前台文件名|后台文件序列号|其中短信交易码为9993.私有字段定义:短信类型$发送人(部门)$提交人$业务类型$批次号$其中前台文件名为上送的文件名,后台文件序列号为返回的文件序列号,文件接口批次号填写前台文件webservice接口定义如下:例子：|trancode9993|smstype6|departmentxd|sender6221|bussinesstype1|seriono1253535|filetypetxt|filenametemp.txt|backofficeid1234567|key描述valuetrancode短信发送交易码9993smstype短信类型6department发送人(部门)xdsender提交人bussinesstype业务类型1seriono批次号filetype文件类型frontfilename前台文件名backofficeid后台文件序列号(2) 应答报文返回报文的格式如下:|返回码|返回信息|前台文件名|后台文件序列号|返回文件名|返回文件名为返回时存储返回信息的文件名称.回执的文件格式如下:|返回码|返回信息|前台序列号|后台序列号|webservice接口定义如下:key描述valuerespcode返回码respmsg返回信息frountfilename前台文件名backofficeid后台文件序列号backfilename返回文件名第7章 短信平台返回码定义短信平台的发送过程包括六种错误码：（1） 外围系统提交过程的错误码（06000699）（2） smsgw从数据库中获取数据的错误码（05000599）（3） smsgw发送到emg的错误码（04000499）（4） emg提交到运营商的错误码（03000399）（5） emg提交到运营商之后返回的错误码（02000299）（6） 运营商返回的回执。（00000199）具体返回码定义如下： 第1节 外围系统提交过程的错误码（06000699）错误码错误信息类型后台返回码备注0600提交成功0601提交失败成功与失败是以数据库插入成功为标志的，而不是仅仅收到。0602ftp上文件为空0603发送格式不正确0604报文头不正确0605短信类型不能为空每个接入短信的部门都有自己的业务类型，不能为空0606业务类型不能为空主要保证发送的优先级0607批次号不能为空批次号可以送定值，但是不能送空值，送定值时查询回执需要保留返回的后台流水号0608发送文件时，文件名不能为空0609短信内容为空0610连接数据库失败0611群发短信超过限制群发短信提交的手机号码串最多一千个手机号码。tcp方式为20s001短信服务器错误(db)s002短信服务器错误(gw)g001未知路由g002网关无响应g003网关类型错误s003报文超长s004报文长度校验错0612手机号码错包括手机号码不符合规定0613操作员受限制或未授权操作员设定的短信数目超限或者无此操作员 第2节 smsgw从数据库中获取数据的错误码（05000599）错误码错误信息类型后台返回码备注0500获取短信息成功0501smsgw取数据时连接数据库失败0502手机头没有配置prefix表中没有配置此手机前三位的头0503此手机号为黑名单0504超过规定的最后发送时间当前时间超过enddate和endtime0505超过重发的最大次数重发一般最多30次0506手机号码不合法手机号码不合法，比如手机号码含有字母 第3节 smsgw发送到emg的错误码（04000499）错误码错误信息类型后台返回码备注0400发送到emg成功成功的标志为发送到emg成功0401发送到emg失败smsgw做sendtoemg的时候失败了 第4节 smsgw提交之后emg返回的错误码，（03000399）此时提交的错误码是emg返回的，只有两种值，此时smsgw会收到消息respcti_magic_erequestservice。宏定义如下：#define e_ums_ok0#define e_ums_noacd_ctemediasym(0x001)#define e_ums_timeout_ctemediasym(0x002)#define e_ums_key_error_ctemediasym(0x003)#define e_ums_makecall_failed_ctemediasym(0x004)#define e_ums_session_full_ctemediasym(0x005)#define e_ums_session_confusion_ctemediasym(0x006)#define e_ums_serail_session_ctemediasym(0x007)#define e_ums_not_support_ctemediasym(0x008)#define e_ums_failed_ctemediasym(0x009)#define e_ums_waiting_response_ctemediasym(0x00a)#define e_ums_directly_go_ctemediasym(0x00b)错误码错误信息类型后台返回码备注0300提交到运营商成功e_ums_waiting_responsemakecall运营商是成功的0301提交到运营商失败smsgw做sendtoemg的时候失败了0309emg申请任务的时候失败了e_ums_failedemg请求任务的时候失败了,可能此时忙 第5节 emg提交到运营商之后返回的错误码（02000299）收到的消息 evtcti_magic_eservicecompleted。错误码错误信息类型后台返回码备注0200无错误，命令正确接收0包括联通，移动，电信7.5.1 联通短信（02010299）错误码错误信息类型后台返回码备注0201非法登录，如登录名、口令出错、登录名与口令不符等1联通短信0202重复登录，如在同一tcp/ip连接中连续两次以上请求登录2联通短信0203连接过多，指单个节点要求同时建立的连接数过多。3联通短信0204登录类型错，指bind命令中的logintype字段出错。4联通短信0205参数格式错，指命令中参数值与参数类型不符或与协议规定的范围不符。5联通短信0206非法手机号码，协议中所有手机号码字段出现非86130号码或手机号码前未加“86”时都应报错。6联通短信0207消息id错7联通短信0208信息长度错8联通短信0209非法序列号，包括序列号重复、序列号格式错误等9联通短信0210非法操作gns10联通短信0211节点忙，指本节点存储队列满或其他原因，暂时不能提供服务的情况11联通短信7.5.2 移动和电信短信错误码（01010149）错误码错误信息类型后台返回码备注0201消息结构错移动短信0202命令字错移动短信0203消息序号重复移动短信0204消息长度错移动短信0205资费代码错。移动短信0206超过最大信息长移动短信0207业务代码错移动短信0208流量控制错移动短信0209本网关不负责服务此计费号码；移动短信0210src_id错误移动短信0211msg_src错误移动短信0212fee_terminal_id错误移动短信0213dest_terminal_id错误移动短信 第6节 运营商返回的回执。（00000100）收到的消息 cmdrequesteservice。错误码错误信息类型后台返回码备注0000已送达0包括联通，移动，电信7.6.1 联通短信回执0021目的地址不可达，指路由表存在路由且消息路由正确但被路由的节点暂时不能提供服务的情况21联通短信0022路由错，指路由表存在路由但消息路由出错的情况，如转错smg等22联通短信0023路由不存在，指消息路由的节点在路由表中不存在23联通短信0024计费号码无效，鉴权不成功时反馈的错误信息24联通短信0025用户不能通信（如不在服务区、未开机等情况）25联通短信0026手机内存不足26联通短信0027手机不支持短消息27联通短信0028手机接收短消息出现错误28联通短信0029不知道的用户29联通短信0030不提供此功能30联通短信0031非法设备31联通短信0032系统失败32联通短信0033短信中心队列满33联通短信0034其他34联通短信7.6.2 移动和电信返回状态报告错误码错误信息类型后台返回码备注0001短消息转发成功delivrd0002短消息超过有效期expired 0003短消息已经被删除deleted 0004短消息是不可转发的undeliv 0005短消息已经被最终用户接收(为保持与smpp 兼容，保留)acceptd 0006未知短消息状态unknown 0007短消息被拒绝(为保持与smpp 兼容，保留)rejectd 第8章 附录 第1节 附1: 联通短信回执/sgip协议的状态报告标记（reportflag）/0-该条消息只有最后出错时要返回状态报告/1-该条消息无论最后是否成功都要返回状态报告/2-该条消息不需要返回状态报告/3-该条消息仅携带包月计费信息，不下发给用户，要返回状态报告/其它-保留/缺省设置为/ 如果这个消息本身就是回执，那么不需要状态报告发送的应答字段长度（字节）类型说明result1integersubmit命令是否成功接收。0：接收成功其它：错误码reserve8text保留，扩展用表4-18 submit_resp消息格式联通的report信息：字段长度（字节）类型说明submitsequencenumber12integer该命令所涉及的submit或deliver命令的序列号reporttype1integerreport命令类型0：对先前一条submit命令的状态报告1：对先前一条前转deliver命令的状态报告usernumber21text接收短消息的手机号，手机号码前加“86”国别标志state1integer该命令所涉及的短消息的当前执行状态0：发送成功1：等待发送2：发送失败errorcode1integer当state=2时为错误码值，否则为0reserve8text保留，扩展用错误码描述0无错误，命令正确接收1非法登录，如登录名、口令出错、登录名与口令不符等。2重复登录，如在同一tcp/ip连接中连续两次以上请求登录。3连接过多，指单个节点要求同时建立的连接数过多。4登录类型错，指bind命令中的logintype字段出错。5参数格式错，指命令中参数值与参数类型不符或与协议规定的范围不符。6非法手机号码，协议中所有手机号码字段出现非86130号码或手机号码前未加“86”时都应报错。7消息id错8信息长度错9非法序列号，包括序列号重复、序列号格式错误等10非法操作gns11节点忙，指本节点存储队列满或其他原因，暂时不能提供服务的情况21目的地址不可达，指路由表存在路由且消息路由正确但被路由的节点暂时不能提供服务的情况22路由错，指路由表存在路由但消息路由出错的情况，如转错smg等23路由不存在，指消息路由的节点在路由表中不存在24计费号码无效，鉴权不成功时反馈的错误信息25用户不能通信（如不在服务区、未开机等情况）26手机内存不足27手机不支持短消息28手机接收短消息出现错误29不知道的用户30不提供此功能31非法设备32系统失败33短信中心队列满其它其它错误码(待定义)表5-2 错误码定义注：错误码1-20所指错误一般在各类命令的应答中用到，21-32所指错误一般在report命令中用到。 第2节 附录2：smgp返回码定义：0 成功1 系统忙2 超过最大连接数3 系统超时4 发送失败5-9 保留10 消息结构错11 命令字错12 序列号错13-19 保留20 ip地址错21 认证错22 版本号不匹配23-29 保留30 非法消息类型（msgtype）31 非法优先级（priority）32 非法资费类型（feetype）33 非法资费代码（feecode）34 非法短消息编码格式（msgformat）35 非法时间格式36 非法短消息长度（msglength）37 有效期已过38 非法查询类别（querytype）39 路由错误40 非法包月费/封顶费（fixedfee）43 非法业务代码（serviceid）44 非法短消息有效时间（validtime）45 非法定时发送时间（attime）46 非法发送用户号码（srctermid）47 非法接收用户号码（desttermid）48 非法计费用户号码（chargetermid）49 非法sp 代码50 非预付费用户51 余额不足52 非注册用户：属于预付费用户，但该号码还未被注册53 非注册sp54 帐号不可用：属于预付费用户，但该帐号处于不可用状态，如已冻结等55 扣费失败56-111 保留112 终端存储部件不存在113 终端存储部件满114 终端不支持的加密模式115 非法交互信息类型（iitype）116 非法交互码（icode）117-127 保留128-255 厂家自定义状态名 状态值(字符串) 说明delivered delivrd 短消息转发成功expired expired 短消息超过有效期deleted deleted 短消息已经被删除undeliverable undeliv 短消息是不可转发的accepted acceptd 短消息已经被最终用户接收(为保持与smpp 兼容，保留)unknown unknown 未知短消息状态rejected rejectd 短消息被拒绝(为保持与smpp 兼容，保留)err 错误代码表 状态值(字符串) 说明对应状态000 成功 delivrd001 用户不能通信 expired002 用户忙 expired003 终