申银万国外围交易系统协议接口标准.docx
《申银万国外围交易系统协议接口标准.docx》由会员分享，可在线阅读，更多相关《申银万国外围交易系统协议接口标准.docx（267页珍藏版）》请在冰豆网上搜索。
申银万国外围交易系统协议接口标准
申银万国外围交易系统协议接口标准
V3.70版
For
ExternalApplicationGateway（AG-X）
通信协议标准
申银万国证券有限公司电脑网络中心
2013年3月
（一）概况
申银万国交易系统采用三层结构组成，中间层为应用网关。
应用网关接受与转发前台应用程序的请求，经后台处理后将结果返回给前台应用程序。
前台应用1
......
前台应用n
前台应用程序必须通过应用网关访问有关数据，本文提供了外围应用软件处理交易业务所必需的协议接口定义。
协议描述
整体说明
本说明使用C语法来定义网络数据结构，并假定结构中各字段是字节对齐的。
1、采用面向连接的网络通信，支持SPX以及其他面向连接的网络协议，如自定义带纠错的RS232流等。
2、网络上传送的数据定义为连续的数据流，而不强行限制物理帧的格式。
3、SWI定义一个安全套接字层（SWSSL）,提供一个安全高效的数据通道，进行逻辑数据流和加密的物理数据流之间的透明转换。
4、逻辑数据流由一个个长度不等的网络消息组成。
5、网络消息可以有连接请求、连接应答、请求、返回状态、查询结果行、取消查询、报警信息、扩展消息等
6、每个网络消息由消息头和消息体组成
消息头
消息体
其中消息头的格式如下：
structSWI_BlockHead
{
WORDblock_size;//整个消息块字节数
WORDcrc;//从下个字段block_type起（不包括block_size和
//crc字段本身）的CRC校验码
BYTEblock_type;//块类型1–请求（SWI_Request）
//2–返回状态（SWI_Return）
//3–查询结果行（SWI_Result）
//5–取消查询
//4–警报信息
//5–网络对话
//6–连接请求（交换密钥）
//7–连接应答（交换密钥）
//8–扩展请求消息
//9–扩展应答消息
BYTEreserved1;//保留，必须置0
WORDfunction_no;//功能号
longcn_id;//网关连接号
WORDreserved2;//保留，内部使用（原营业部）
WORDdest_dpt;//目的营业部编号
};
7、每个在网络上传送的网络消息如果长度不是8的倍数，应补充若干个字节的二进制0，直到实际传送长度是8的倍数。
以便于进行DES加密/解密。
但消息头中的长度字段仍为有效数据的长度，不对齐到8的倍数。
8、服务器端针对每个连接在一个时刻只处理一个请求，客户端应处理完上次请求的所有应答后才能提交下个请求。
9、当该客户不再需要服务时,客户端应断开网络连接来结束服务,服务器端和客户端任何一方都可断开连接。
网络故障、连接空闲超时和某个网络消息校验非法也可导致连接中断。
连接中断时服务器端和客户端各自清理现场、取消未完成的事务。
客户端下笔业务必须重新连接方可进行。
连接空闲超时限制值为5分钟。
10、版本兼容性设计。
随业务发展，现定义的返回结果可能会增加字段，为保证本接口的向上兼容性，约定新增字段一率增加在原有结构的尾部，客户端应检查返回结果和应答消息的长度，并丢弃客户端当前版本不能识别的新增字段。
保证按较老版本接口开发的应用可以不修改地与升版后的网关正常通信。
SWSSL实现：
应用层：
SWSSL层：
连接过程：
（1）客户端用connect系统调用建立网络连接。
（2）协商加密方式
客户端发出“连接请求”消息
structSWI_ConnectRequest
{
SWI_BlockHeadhead;//消息头block_type==6
WORDmethod;//客户端的加密方式
charentrust_method;//委托方式（见数据字典说明）
BYTEreturn_cp;//客户端希望的返回结构中中文字段的代码页
//0--MBCS（CP936简体中文）
//1--Unicode（Java客户需要）
BYTEnetwork[4];//客户端Novell网段号
BYTEaddress[6];//客户端网卡地址（Novell节点地址）
WORDclient_major_ver;//客户端协议接口主版本号（用于版本协商）
WORDclient_minor_ver;//客户端协议接口次版本号（用于版本协商）
WORDkey_length;//RSA密钥长度（对method1,key_length=0）
};
消息头中：
block_type6–连接请求（交换密钥）
function_no忽略
cn_id0
dest_dpt忽略
服务器端“连接应答”消息
structSWI_ConnectResponse
{
SWI_BlockHeadhead;//消息头block_type==7
WORDreturn_value;//返回状态
WORDmethod;//网关同意的加密方式
chardepartment_name[60];//营业部名称（MBCS/Unicode）
WORDkey_length;//DES密钥长度（key_length=8）
BYTEdes_key[8];//DES密钥（请用“ExpressT”作为密钥des解密）
}
消息头中：
block_type7
function_no忽略
cn_id分配到的连接标识，客户端应缓存此连接标识，用于填充后续请求中的相应字段
dest_dpt本地营业部编号
注：
1.当前企业网内应用，规定密钥交换采用method==1。
服务器端生成一个随机的DES密钥，在连接应答中发送到客户端，以后的通信内容均采用DES加密。
2.跨营业部（通买通卖）交易请求处理，从校验股民交易密码调用起在head的dest_dpt中指定客户指定交易所在营业部编号，（本营业部也可用0表示）。
但因为协商加密方式时客户端应用程序尚不知道客户帐号和所在营业部，所以SWI_ConnectRequest中dest_dpt不需指定。
3．约定请求中dest_dpt为目的营业部编号（客户指定交易所在营业部），应答中的dest_dpt为本地营业部编号（客户端应用程序直接连接的网关所在营业部）
4.Method=1整包加密
Method=2仅对密码部分加密（包括0x101，0x111，0x102，0x705所含的密码字段）
请求与应答时序：
请求消息
head.block_type=1，由head.function_no来区分不同功能调用
应答消息
head.block_type=3，
表示查询结果集的某条结果，可以有多条
head.block_type=2，
表示功能调用的应答，如果有查询结果集，则跟在查询结果集之后收到，如果没有查询结果集，则直接收到该应答，收到该应答后表示本笔请求的服务器端处理已经全部结束。
时序图:
客户端服务器端
3
2
有
无N
Y
服务结束
错误功能号约定：
当请求方调用AGC不支持的功能号时，AGC返回一个通用RETURN包:
structSWI_CommonReturn
{
structSWI_BlockHeadhead;//function_no=请求功能号
longreturn_status;//返回状态
charerrmsg[80];//失败原因
}
其中，return_status=-999,errmsg为“新增功能暂不支持”。
其他约定
为了实现“应用程序版本统计”工作，要求每个应用程序在启动时完成以下工作：
1、与AGX建立网络连接，发送连接请求包。
2、调用“功能号0x801”SWI_QueryCommon，参数如下：
SWI_BlockH_id=0
function_id=1
cmd_buf=“产品名称|开发商|版本号|升版日期”
返回：
100成功〈=0失败
（二）功能列表
功能号高字节表示功能大类：
1---帐号操作
2---交易
3---单条结果查询
4---当天多结果集查询
5---历史多结果集查询
6---查证券信息
7---银证转帐相关操作
9---辅助操作
特别注意：
2012/3/5日起新增功能全部启用功能号“0x1000-0x1999”定义区间，不再遵循以前的上述功能号高字节分类定义，将以“业务类型”为主线分配新增功能号。
2013/3/31日，对于功能列表进行扩充。
截止目前为止，已定义的功能列表分类整理如下：
业务类型
功能定义
备注
客户认证
0x101-客户登录
0x111替代不推荐用
0x111-客户综合登录
0x101增强功能
0x102-客户密码修改
0x103-客户退出
0x1121-资金密码校验
0x1301-取验签原文
强身份认证
0x1302-强身份认证验签
强身份认证
普通交易
0x201-录入委托
0x202-撤单
0x402-查询委托
0x403-查询实时成交
0x301-查询资金
0x311替代不推荐用
0x311-查询综合资金信息
0x301增强功能
0x401-查询股票
0x410-查询客户可委托股数
0x404-查询后台证券信息设置
公共信息查询
0x601-查询证券信息
公共信息查询
批量交易
0x205-批量委托
0x215-批量委托2
0x205增强功能
0x206-批量撤单
0x421-批量查库存
0x423-批量查委托成交
0x424-批量查委托
银证转帐
0x705-券商银证转帐申请
0x706-查询银证转帐申请
0x704-查询银证转帐帐户
0x608-查询多资金帐户
0x709-资金内转申请
0x1921-重置银证转账密码验证次数
结算服务
0x503-查询历史成交
0x504-查询资金明细/客户台帐
0x505-查询交割单
0x203-确认交割单已打印
0x231-调整实现盈亏
普通回购
0x405-查询回购记录明细
0x409-查询债券质押库存
报价回购
0x241-报价回购申购委托
0x241-报价回购终止
0x441-报价回购当日业务查询
0x443-报价回购历史业务查询
0x612-报价回购品种查询
公共信息查询
0x2243-续约中止预约
ETF
0x407-ETF可申赎份额查询
0x408-ETF篮子股票查询
公共信息查询
0x4409-ETF现金差额明细查询
场外基金
0x441-场外基金分红方式查询
0x221-场外基金分红方式修改
0x222-开放式基金基金转换
0x602-查询代销场外基金列表
公共信息查询
0x603-查询代销场外基金公司列表
公共信息查询
理财产品
0x232-设置现金理财产品
0x507-查询现金理财产品
特别转让
0x604-查询定价委托行情
基金分拆合并
0x605-查询基金分拆合并信息
融资融券
0x207-非交易划转
担保品提交、担保品返还、
直接还券
0x209-非交易划转撤单
0x406-非交易划转查询
0x303-资产负债查询
0x431-融资负债明细查询
0x432-融券负债明细查询
0x412-融资融券标的证券查询
公共信息查询
转融通业务
0x2301-转融通出借证券
0x2302-转融通出借证券撤单
0x4301-证券出借查询
约定购回
0x4501-约定购回交易明细查询
杂类
0x606查询客户登陆密码错误次数
0x801-查询公共数据
0x901-出错信息解释
0x507-查询自营发生记录
自营专用
停用功能
0x302-查询客户基本信息
0x111接口替代
客服API接口替代
0x322-新查询客户基本信息
客服API接口替代
0x103-修改客户资料
客服API接口替代
0x124-新修改客户基本信息
客服API接口替代
0x204-服务费用收取
0x323-查询客户证券市场信息
0x111接口替代
0x400-查询客户所有相关帐号
0x111接口替代
0x506-查询回购发生记录
0x405接口替代
（三）功能说明
功能号高字节表示功能大类：
1---帐号操作
2---交易
3---单条结果查询
4---当天多结果集查询
5---历史多结果集查询
6---查证券信息
7---银证转帐相关操作
9---辅助操作
1、功能号0x101客户登录
调用此功能，如校验股民交易密码通过，该客户的帐号将处于允许交易的打开状态，直到下列情况之一发生：
1．该连接调用功能0x103关闭帐号
2．该连接关闭。
请求消息
structSWI_OpenAccountRequest
{
structSWI_BlockHeadhead;//function_no==0x101,block_type==1
characcount_type;//客户帐号类型
characcount[16];//客户帐号
charpwd[8];//交易密码（如为操作员登陆，则为操作员密码）
shortop_code;//操作员工号
unsigned longflag;//"特殊条件"判断标志位组合,每一个二进制位对应一个"特殊条件",缺省值为0表示不判断任何"特殊条件"
charproductno[7];//产品信息编号：
5位电脑网络中心产品编码+2位子
产品编码（共7位字符）；缺省值为空。
Charnote[30];//备注：
目前用于在客户委托时存放外围客户登陆的MAC地址或IP地址或电话号码等信息。
charnote2[30];//备注，和note字段共同使用，具体使用方法见注意事项5
charlogin_flag;//记录本此登录信息的标志，‘0’——不记录（默认）；
‘1’——记录，客户界面主动发起的登录应填‘1’
charst_auth_type;//强身份认证类型‘0’代表令牌，‘1’代表证书
charst_antu_info[352];//当强身份认证类型为‘0’时，表示动态密码仅前6位有效，当强身份认证类型为‘1’时，表示验签信息
};
目前已定义flag的"特殊条件"判断，列表如下：
二进制位对应的十六进制数对应的特殊条件 对应的返回状态
10x0001不允许使用"简单密码" -159
20x0002基本登陆验证仅支持资金帐号登陆 无
30x0004操作员登陆 无
40x0008未定义 无
50x0010未定义，。
。
。
无
160x8000大集中系统保留使用,不对外围定义
对跨营业部（通买通卖）交易请求，
在head中dest_dpt中指定客户指定交易所在营业部编号（下同）。
应答消息
structSWI_OpenAccountReturn
{
structSWI_BlockHeadhead;//function_no==0x101
longreturn_status;//返回状态
BYTEflag;//（新扩充字段）大集中网关标志，0—否（默认）；1—是
当客户号登录返回1时,适用于【大集中约定】
charlast_login_date[9];//上次登录的日期，格式为：
YYYYMMDD
charlast_login_time[9];//上次登录的时间，格式为：
HH:
MM:
SS
charlast_full_note[60];//上次的登陆信息，参见注意事项5的说明
charreserved_auth_info[20];//客户预留验证信息
charst_auth_perm_flag;//客户开通哪种强身份论证
//‘0’令牌，‘1’证书，‘’未开通
（缺省为未开通）
charst_busi_set[20];//强身份认证业务集‘a’:
修改密码
‘b’:
券商转银行
longend_date;//令牌或证书的有效期结束日期（形如：
yyyymmdd）
};
返回状态：
>0成功
<=0失败
注意：
1）如果返回状态为-159，则说明用户输入的为简单密码
2）如果flag为2，则用于基本登陆验证（仅支持资金帐号登陆）
3）如果flag为4，则为操作员登陆，此时密码项为操作员密码，每个操作员仅可携带一个客户号登陆，登陆成功后等同于该客户登陆成功
4）备注项note字段目前用于记录客户登陆时的MAC地址，IP地址或者电话号码等信息，在委托时写入委托表，网关负责将该内容如实地记入后台表中，其内部的定义由外围自行组织和定义
5）Note和note2字段可各填29个字符,当note字段填满时需要填写note2字段，note和note2字段均采用左对齐方式进行填写。
其格式为：
IP=255.255.255.255|MAC=FFFFFFFFFFFF|TEL*************
信息TAG
说明
需要记录的委托方式
IP
IP地址
网上交易、自助委托
MAC
MAC地址
网上交易、自助委托
TEL
电话号码
电话委托
6）当客户主动发起界面登陆，且校验密码错误时（密码错误时返回状态-70）,可以调用0x606功能，进行密码错误次数的查询。
7）多银行三方存管辅资金账户不能登陆。
8）新增错误号（见errmsg），方便外围容错登陆时，返回给外围，外围根据错误信息进行下一步的强身份论证的登陆。
2、功能号0x111客户综合登录
请求消息
structSWI_AccountLoginRequest
{
structSWI_BlockHeadhead;//function_no==0x111,block_type==1
characcount_type;//客户帐号类型（见数据字典说明）
characcount[16];//客户帐号
charpwd[8];//交易密码
unsigned longflag;//"特殊条件"判断标志位组合,每一个二进制位对应一个"特殊条件",缺省值为0表示不判断任何"特殊条件"
charproductno[7];//产品信息编号：
5位电脑网络中心产品编码+2位子
产品编码（共7位字符）；缺省值为空。
Charnote[30];//备注：
目前用于在客户委托时存放外围客户登陆的MAC地址或IP地址或电话号码等信息。
charnote2[30];//备注，和note字段共同使用，具体使用方法见0x101注意事项5
charlogin_flag;//记录本此登录信息的标志，‘0’——不记录（默认）；
‘1’——记录，客户界面主动发起的登录应填‘1’
charst_auth_type;//强身份认证类型‘0’代表令牌，‘1’代表证书
charst_antu_info[352];//当强身份认证类型为‘0’时，表示动态密码仅前6位有效，当强身份认证类型为‘1’时，表示验签信息
};
目前已定义flag的"特殊条件"判断，列表如下：
二进制位对应的十六进制数对应的特殊条件 对应的返回状态
10x0001不允许使用"简单密码" -159
20x0002未定义 无
30x0004未定义 无
40x0008未定义 无
50x0010未定义，。
。
。
无
160x8000大集中系统保留使用,不对外围定义
查询结果行应答
structSWI_AccountLoginResult
{
structSWI_BlockHeadhead;//function==0x111,block_type==3
WORDrow_no;//记录号，0xFFFF表示记录集结束
longbankbook_number;//资金帐号
characcount_type;//帐号类型（见数据字典,不含资金帐号‘0’）
charsecurity_account[16];//证券帐号
};
应答消息
structSWI_AccountLoginReturn
{
structSWI_BlockHeadhead;//function_no=0x111,block_type==2
longreturn_status;//返回状态
longbankbook_number;//资金帐号
BYTEaccount_status;//帐号状态（见数据字典说明）
charname[20];//客户姓名（MBCS/Unicode）
charid[19];//身份证号
BYTEcard_version;//磁卡版本号
charcustomer_flag[16];//客户个性化信息标志
charCust_flag[32];//客户权限标志（字段中如出现R——允许融资融券）
charCust_risk_type;//客户风险评级类别（见数据字典说明）
shortdepart_number;//营业部编码（4位）
charlas
升级会员 