申银万国外围交易系统协议接口标准.docx

1、申银万国外围交易系统协议接口标准申银万国外围交易系统协议接口标准V3.70版ForExternal Application Gateway (AG-X)通信协议标准申银万国证券有限公司电脑网络中心2013年3月（一）概况申银万国交易系统采用三层结构组成，中间层为应用网关。应用网关接受与转发前台应用程序的请求，经后台处理后将结果返回给前台应用程序。前台应用1 . . . . . .前台应用n 前台应用程序必须通过应用网关访问有关数据，本文提供了外围应用软件处理交易业务所必需的协议接口定义。协议描述整体说明本说明使用C语法来定义网络数据结构，并假定结构中各字段是字节对齐的。 1、采用面向连接的网络

2、通信，支持 SPX以及其他面向连接的网络协议，如自定义带纠错的RS232流等。2、网络上传送的数据定义为连续的数据流，而不强行限制物理帧的格式。3、SWI定义一个安全套接字层(SWSSL), 提供一个安全高效的数据通道，进行逻辑数据流和加密的物理数据流之间的透明转换。4、逻辑数据流由一个个长度不等的网络消息组成。5、网络消息可以有连接请求、连接应答、请求、返回状态、查询结果行、取消查询、报警信息、扩展消息等6、每个网络消息由消息头和消息体组成消息头消息体其中消息头的格式如下：struct SWI_BlockHead WORD block_size; / 整个消息块字节数WORD crc; /

3、从下个字段block_type起 (不包括block_size和 / crc字段本身) 的CRC校验码 BYTE block_type; / 块类型 1 请求 （SWI_Request） / 2 返回状态 （SWI_Return） / 3 查询结果行 （SWI_Result） / 5 取消查询 / 4 警报信息 / 5 网络对话 / 6 连接请求(交换密钥) / 7 连接应答(交换密钥) / 8 扩展请求消息 / 9 扩展应答消息 BYTE reserved1; / 保留，必须置0 WORD function_no; / 功能号 long cn_id; / 网关连接号WORD reserved

4、2; / 保留，内部使用（原营业部）WORD dest_dpt; / 目的营业部编号;7、每个在网络上传送的网络消息如果长度不是8的倍数，应补充若干个字节的二进制0，直到实际传送长度是8的倍数。以便于进行DES加密/解密。但消息头中的长度字段仍为有效数据的长度，不对齐到8的倍数。8、服务器端针对每个连接在一个时刻只处理一个请求，客户端应处理完上次请求的所有应答后才能提交下个请求。9、当该客户不再需要服务时, 客户端应断开网络连接来结束服务, 服务器端和客户端任何一方都可断开连接。网络故障、连接空闲超时和某个网络消息校验非法也可导致连接中断。连接中断时服务器端和客户端各自清理现场、取消未完成的事

5、务。客户端下笔业务必须重新连接方可进行。连接空闲超时限制值为5分钟。10、版本兼容性设计。随业务发展，现定义的返回结果可能会增加字段，为保证本接口的向上兼容性，约定新增字段一率增加在原有结构的尾部，客户端应检查返回结果和应答消息的长度，并丢弃客户端当前版本不能识别的新增字段。保证按较老版本接口开发的应用可以不修改地与升版后的网关正常通信。SWSSL实现：应用层：SWSSL层： 连接过程：（1）客户端用connect系统调用建立网络连接。（2）协商加密方式客户端发出“连接请求”消息struct SWI_ConnectRequest SWI_BlockHead head; / 消息头 block_

6、type = 6WORD method; / 客户端的加密方式char entrust_method; / 委托方式（见数据字典说明） BYTE return_cp; / 客户端希望的返回结构中中文字段的代码页 / 0 - MBCS （CP936简体中文） / 1 - Unicode(Java客户需要) BYTE network4; / 客户端Novell网段号 BYTE address6; / 客户端网卡地址（Novell节点地址） WORD client_major_ver; / 客户端协议接口主版本号（用于版本协商） WORD client_minor_ver;/ 客户端协议接口次版本号

7、（用于版本协商）WORD key_length; / RSA密钥长度（对method 1, key_length=0）;消息头中：block_type 6 连接请求(交换密钥) function_no 忽略 cn_id 0dest_dpt 忽略服务器端“连接应答”消息struct SWI_ConnectResponse SWI_BlockHead head; / 消息头 block_type = 7 WORD return_value; / 返回状态 WORD method; / 网关同意的加密方式char department_name60;/ 营业部名称（MBCS/Unicode） WOR

8、D key_length; / DES密钥长度（key_length=8）BYTE des_key8; / DES密钥(请用“ExpressT”作为密钥des解密)消息头中：block_type 7 function_no 忽略cn_id 分配到的连接标识，客户端应缓存此连接标识，用于填充后续请求 中的相应字段dest_dpt 本地营业部编号注：1. 当前企业网内应用，规定密钥交换采用method = 1。服务器端生成一个随机的DES密钥，在连接应答中发送到客户端，以后的通信内容均采用DES加密。2. 跨营业部(通买通卖)交易请求处理，从校验股民交易密码调用起在head的dest_dpt中指定

9、客户指定交易所在营业部编号，（本营业部也可用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 来区分不同功能调用应答

10、消息head.block_type = 3，表示查询结果集的某条结果，可以有多条head.block_type = 2，表示功能调用的应答，如果有查询结果集，则跟在查询结果集之后收到，如果没有查询结果集，则直接收到该应答，收到该应答后表示本笔请求的服务器端处理已经全部结束。时序图: 客户端 服务器端 3 2 有 无 N Y服务结束错误功能号约定：当请求方调用AGC不支持的功能号时，AGC返回一个通用RETURN包:struct SWI_CommonReturn struct SWI_BlockHead head; / function_no=请求功能号 long return_status;

11、/ 返回状态char errmsg80; / 失败原因 其中，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

12、- 历史多结果集查询 6 - 查证券信息7 - 银证转帐相关操作 9 - 辅助操作 特别注意：2012/3/5日起新增功能全部启用功能号“0x1000-0x1999”定义区间，不再遵循以前的上述功能号高字节分类定义，将以“业务类型”为主线分配新增功能号。2013/3/31日，对于功能列表进行扩充。截止目前为止，已定义的功能列表分类整理如下：业务类型功能定义备注客户认证0x101-客户登录0x111替代不推荐用0x111-客户综合登录0x101增强功能0x102-客户密码修改0x103-客户退出0x1121-资金密码校验0x1301-取验签原文强身份认证0x1302-强身份认证验签强身份认证普通

13、交易0x201-录入委托0x202-撤单0x402-查询委托0x403-查询实时成交0x301-查询资金0x311替代不推荐用0x311-查询综合资金信息0x301增强功能0x401-查询股票0x410-查询客户可委托股数0x404-查询后台证券信息设置公共信息查询0x601-查询证券信息公共信息查询批量交易0x205-批量委托0x215-批量委托20x205增强功能0x206-批量撤单0x421-批量查库存0x423-批量查委托成交0x424-批量查委托银证转帐0x705-券商银证转帐申请0x706-查询银证转帐申请0x704-查询银证转帐帐户0x608-查询多资金帐户0x709-资金内转申

14、请0x1921-重置银证转账密码验证次数结算服务0x503-查询历史成交0x504-查询资金明细/客户台帐0x505-查询交割单0x203-确认交割单已打印0x231-调整实现盈亏普通回购0x405-查询回购记录明细0x409-查询债券质押库存报价回购0x241-报价回购申购委托0x241-报价回购终止0x441-报价回购当日业务查询0x443-报价回购历史业务查询0x612-报价回购品种查询公共信息查询0x2243-续约中止预约ETF0x407-ETF可申赎份额查询0x408-ETF篮子股票查询公共信息查询0x4409-ETF现金差额明细查询场外基金0x441-场外基金分红方式查询0x221

15、-场外基金分红方式修改0x222-开放式基金基金转换0x602-查询代销场外基金列表公共信息查询0x603-查询代销场外基金公司列表公共信息查询理财产品0x232-设置现金理财产品0x507-查询现金理财产品特别转让0x604-查询定价委托行情基金分拆合并0x605-查询基金分拆合并信息融资融券0x207-非交易划转担保品提交、担保品返还、直接还券0x209-非交易划转撤单0x406-非交易划转查询0x303-资产负债查询0x431-融资负债明细查询0x432-融券负债明细查询0x412-融资融券标的证券查询公共信息查询转融通业务0x2301-转融通出借证券0x2302-转融通出借证券撤单0x

16、4301-证券出借查询约定购回0x4501-约定购回交易明细查询杂类0x606查询客户登陆密码错误次数0x801-查询公共数据0x901-出错信息解释0x507-查询自营发生记录自营专用停用功能0x302-查询客户基本信息0x111接口替代客服API接口替代0x322-新查询客户基本信息客服API接口替代0x103-修改客户资料客服API接口替代0x124-新修改客户基本信息客服API接口替代0x204-服务费用收取0x323-查询客户证券市场信息0x111接口替代0x400-查询客户所有相关帐号0x111接口替代0x506-查询回购发生记录0x405接口替代（三）功能说明功能号高字节表示功能

17、大类： 1 - 帐号操作 2 - 交易 3 - 单条结果查询 4 - 当天多结果集查询 5 - 历史多结果集查询 6 - 查证券信息7 - 银证转帐相关操作 9 - 辅助操作1、功能号0x101 客户登录调用此功能，如校验股民交易密码通过，该客户的帐号将处于允许交易的打开状态，直到下列情况之一发生： 1该连接调用功能0x103关闭帐号 2该连接关闭。请求消息struct SWI_OpenAccountRequest struct SWI_BlockHead head; / function_no=0x101, block_type = 1 char account_type; / 客户帐号类型

18、 char account16; / 客户帐号 char pwd8; / 交易密码（如为操作员登陆，则为操作员密码）short op_code; / 操作员工号unsigned long flag; /特殊条件判断标志位组合,每一个二进制位对应一个特殊条件,缺省值为0表示不判断任何特殊条件char productno 7; /产品信息编号：5位电脑网络中心产品编码+2位子 产品编码（共7位字符）；缺省值为空。Char note30; /备注：目前用于在客户委托时存放外围客户登陆的MAC地址 或IP 地址或电话号码等信息。char note230; / 备注，和note字段共同使用，具体使用方法

19、见注意事项5char login_flag; / 记录本此登录信息的标志，0不记录（默认）；1记录，客户界面主动发起的登录应填1char st_auth_type; / 强身份认证类型 0代表令牌，1代表证书char st_antu_info352; / 当强身份认证类型为0时，表示动态密码仅前6位有效，当强身份认证类型为1时，表示验签信息;目前已定义flag的特殊条件判断，列表如下： 二进制位 对应的十六进制数 对应的特殊条件 对应的返回状态 1 0x0001 不允许使用简单密码 -159 2 0x0002 基本登陆验证仅支持资金帐号登陆 无3 0x0004 操作员登陆 无 4 0x0008

20、 未定义 无 5 0x0010 未定义，。 无 16 0x8000 大集中系统保留使用,不对外围定义对跨营业部(通买通卖)交易请求，在head中 dest_dpt中指定客户指定交易所在营业部编号（下同）。应答消息struct SWI_OpenAccountReturn struct SWI_BlockHead head; / function_no=0x101 long return_status; / 返回状态BYTE flag; / (新扩充字段)大集中网关标志，0否（默认）；1是 当客户号登录返回1时,适用于【大集中约定】char last_login_date9; / 上次登录的日期，

21、格式为：YYYYMMDDchar last_login_time9; / 上次登录的时间，格式为：HH:MM:SSchar last_full_note60; / 上次的登陆信息，参见注意事项5的说明char reserved_auth_info20; / 客户预留验证信息char st_auth_perm_flag; / 客户开通哪种强身份论证 /0令牌，1证书，未开通(缺省为未开通)char st_busi_set20; / 强身份认证业务集 a:修改密码 b:券商转银行long end_date; / 令牌或证书的有效期结束日期（形如：yyyymmdd）;返回状态： 0 成功 = 0 失

22、败注意：1）如果返回状态为-159，则说明用户输入的为简单密码2）如果flag为2，则用于基本登陆验证（仅支持资金帐号登陆）3）如果flag为4，则为操作员登陆，此时密码项为操作员密码，每个操作员仅可携带一个客户号登陆，登陆成功后等同于该客户登陆成功4）备注项note字段目前用于记录客户登陆时的MAC地址，IP地址或者电话号码等信息，在委托时写入委托表，网关负责将该内容如实地记入后台表中，其内部的定义由外围自行组织和定义5）Note和note2字段可各填29个字符,当note字段填满时需要填写note2字段，note和note2字段均采用左对齐方式进行填写。其格式为：IP=255.255.25

23、5.255|MAC=FFFFFFFFFFFF|TEL*信息TAG说明需要记录的委托方式IPIP地址网上交易、自助委托MACMAC地址网上交易、自助委托TEL电话号码电话委托 6）当客户主动发起界面登陆，且校验密码错误时（密码错误时返回状态-70）,可以调用0x606功能，进行密码错误次数的查询。7) 多银行三方存管辅资金账户不能登陆。8) 新增错误号(见errmsg)，方便外围容错登陆时，返回给外围，外围根据错误信息进行下一步的强身份论证的登陆。2、功能号0x111 客户综合登录请求消息struct SWI_AccountLoginRequest struct SWI_BlockHead he

24、ad; / function_no=0x111, block_type = 1 char account_type; / 客户帐号类型（见数据字典说明） char account16; / 客户帐号 char pwd8; / 交易密码unsigned long flag; /特殊条件判断标志位组合,每一个二进制位对应一个特殊条件,缺省值为0表示不判断任何特殊条件char productno 7; /产品信息编号：5位电脑网络中心产品编码+2位子 产品编码（共7位字符）；缺省值为空。Char note30; /备注：目前用于在客户委托时存放外围客户登陆的MAC地址 或IP 地址或电话号码等信息。

25、char note230; / 备注，和note字段共同使用，具体使用方法见0x101注意事项5char login_flag; / 记录本此登录信息的标志，0不记录（默认）；1记录，客户界面主动发起的登录应填1char st_auth_type; / 强身份认证类型 0代表令牌，1代表证书char st_antu_info352; / 当强身份认证类型为0时，表示动态密码仅前6位有效，当强身份认证类型为1时，表示验签信息;目前已定义flag的特殊条件判断，列表如下： 二进制位 对应的十六进制数 对应的特殊条件 对应的返回状态 1 0x0001 不允许使用简单密码-159 2 0x0002 未

26、定义 无 3 0x0004 未定义 无 4 0x0008 未定义 无 5 0x0010 未定义，。 无 16 0x8000 大集中系统保留使用,不对外围定义查询结果行应答struct SWI_AccountLoginResult struct SWI_BlockHead head; / function=0x111,block_type=3 WORD row_no; / 记录号，0xFFFF表示记录集结束 long bankbook_number; / 资金帐号char account_type; / 帐号类型（见数据字典, 不含资金帐号0） char security_account16;

27、/ 证券帐号;应答消息struct SWI_AccountLoginReturn struct SWI_BlockHead head; / function_no = 0x111,block_type=2 long return_status; / 返回状态long bankbook_number; / 资金帐号BYTE account_status; / 帐号状态（见数据字典说明） char name20; / 客户姓名（MBCS/Unicode）char id19; / 身份证号BYTE card_version; /磁卡版本号 char customer_flag16; /客户个性化信息标志char Cust_flag32; /客户权限标志（字段中如出现R允许融资融券）char Cust_risk_type; /客户风险评级类别（见数据字典说明）short depart_number; /营业部编码（4位）char las