网银适配器二次开发手册.doc

网银适配器2.0版二次开发手册一、 版本说明网银适配器1.X版主要实现了和全国性银行的连接。为了满足越来越多的地区性商业银行、外资银行与标准产品连接的需求，网银适配器2.0中增加了集成框架，便于用友的二次开发人员、伙伴开发人员、客户开发人员在此基础上进行地区性商业银行、外资银行接口的开发，且开发成果具有一致性，能与NC、U8等标准产品正确连接。二、 支持银行及NCU8版本目前网银适配器支持包括国内各大银行在内的17家银行，外资银行支持日本瑞穗，银行的业务功能主要支持余额查询、明细下载、支付转账、支付转账查询、集团支付、集团支付查询等业务功能。注意银行功能对应的ERP版本号。功能银行余额明细支付支付查询集团支付及查询财务室批量指令财务室批量指令查询对应NC版本对应U8版本北京银行是是是是NC3.1+SP2交通银行是是是是NC3.1+SP2U852中国银行是是是是是NC3.1+SP2U852建设银行是是是是NC3.1+SP2U860建设银行外联是是是是NC3.1+SP2U861光大银行是是是是NC3.1+SP2U860中信实业银行是是是是NC3.1+SP2招商银行是是是是是NC3.1+SP2U860民生银行是是是是NC3.1+SP2农业银行是是是是NC3.1+SP2U861广发银行是是是是NC3.1+SP2华夏银行是是是是NC3.1+SP2工商银行是是是是是是NC3.1+SP2U860工商银行专业版是是是是NC3.1+SP2U861日本瑞穗银行是是NC3.1+SP2U861上海浦发银行是是是是是NC3.1+SP2U861兴业银行是是是是是NC3.1+SP2U861备注：对应U8版本是U861、U852、U860依次向后兼容！三、 运行环境硬件要求：CPU：1.6GHz，内存：512M，磁盘空间：500M操作系统：Windows2000 Professional 支持二次开发语言：可编译生成动态库的任何语言，如：VB，VC等。四、 软件加密暂无。五、 网银适配器原理1、UFBank作用网银适配器（UFBank）的主要作用是作为业务系统（即NC、U8等）与银行系统连接的桥梁。UFBank屏蔽了不同银行数据格式和连接方式的不同，将其转换成统一的数据格式（内部标准格式）和连接方式，业务系统只与内部标准接口打交道。在增加新的银行接口，或银行系统升级时，只需要升级UFBank即可，从而有效地保证了业务系统的相对独立性，使其受增加新的银行接口、银行系统升级的影响很小。在UFBank中，不进行任何业务处理。UFBank只有银行参数配置、日志查询、测试界面外。在实际运行时没有可见界面。2、UFBank构成与工作原理UFBank主要由两部分组成：UFBank Service和UFBankPlugin。UFBank Service主要包括：l 一个Web Service，通过WEB服务的方式接收来自业务系统的指令，并将执行结果通过WEB服务再传回业务系统。在UFBank2.0中，Web Service的核心文件是UFBank.asp。其核心代码如下：Set objDom = CreateObject(msxml2.domdocument)objDom.Load(Request) 获得业务系统发来的指令srcData = objDom.xml 将指令数据赋予字符串变量srcDataobjUFBank = CreateObject(UFBank.clsService)创建接口服务对象retdata=objUFBank.sendBank(cstr(srcdata)调用接口服务对象的方法，并返回指令执行的结果Response.write retdata将执行结果返回业务系统l 一个接口服务类UFBank.clsService。该接口服务类主要作用是：解析业务系统的指令数据，根据指令数据中的银行标识调用相应的银行接口插件（即UFBankPlugin）。该类是UFBank Service的核心。银行接口插件必须实现UFBank.clsService要求的接口方法sendBank(tasked as string, strBankID as string, strFunc as string, lngParaNum as long, aParaValue as variant, SrcData as string, RetData as string, strErrMsg as string, objLog as object)。l 一个日志文件类UFBank.clsLog。该类实现了对日志文件的读和写，该类的一个实例会通过UFBank.clsSercice传递给银行接口插件，供其写日志文件用。l 一个银行接口插件注册文件UFBankConfig.xml及读写该注册文件的类UFBank.clsConfig。l 一个用户使用的银行参数配置的模块（可执行文件为UFBankConfig.exe）。用户通过该模块设置各个银行需要的参数。此外，本模块还额外提供了日志查询的功能。UFBankPlugin指银行接口插件。银行接口插件的主要功能是：（1）将业务系统发来的指令数据（内部标准格式）转换为相应银行的格式；（2）连接银行并向其发送指令数据；（3）接收银行的返回值并将其转换为内部标准格式；（4）将返回值传递给UFBank.clsSercice。网银适配器二次开发的主要工作就是开发新的银行接口插件。UFBank2.0中提供了17个银行接口插件，对于UFBank2.0中没有提供的银行接口，分公司、伙伴、用户可以自在本手册的指导下二次开发新的银行接口插件。在银行接口插件中，必须实现UFBank.clsService要求的接口方法sendBank。银行接口插件必须编译为dll并且在银行接口插件注册文件UFBankConfig.xml中注册。六、 二次开发过程开发一个新的银行接口，过程如下：1、 安装业务系统（NC、U8），并在业务系统中注册银行标识等信息。银行标识指银行的唯一标识，如浦发银行标识为：SPDB，民生银行标识为CMBC。一般采用银行的英文缩写。在业务系统中注册的银行标识与在UFBank中注册的银行标识要前后一致（包括大小写）。NC3.1SP及以上版本支持银行标识等信息的注册，NC3.1及以前版本、U8各版本不支持二次开发人员注册，需要通知NC资金开发部、U8财务开发部的开发人员修改程序并发放专项补丁。2、 建立UFBank的二次开发环境。获得UFBank的安装盘，安装后自动建立起了UFBank的二次开发环境。最新版本的UFBank安装盘可从技术支持网站或知识中心下载，或向集团网银适配器开发经理索取。2006年网银适配器的开发经理为郑传炎（分机电话：2756，EMAIL：zhengcyU）。3、 注册银行接口插件类及银行参数。在UFBank的安装目录下找到UFBankConfig.xml。用文本编辑器（如记事本、UltraEdit等）打开，在其中添加新的银行信息。下表是一个样例：配置文件是一个XML文件，其根结点为，在根节点下面有若干节点，每一个节点代表一套银行系统（之所以不说代表一家银行是因为有的银行有多套系统，如工行有专业版和普通版、建行有重客和外联）。元素说明了要注册一个新的银行接口插件。银行接口插件的信息通过其属性表示。元素的各属性值说明如下：l bankid：必须，全局唯一，指银行的唯一标识,该标识必须与在业务系统(NC/U8等)中注册的标识完全相同,包括大小写。这是最重要的属性。l shortname：必须，银行系统的简称，将会显示在银行参数配置界面的按钮上。l fullname：必须，值不能为空，银行系统的全称，将会显示在银行参数配置界面的参数上方。l pluginclass：必须，即要进行二次开发的银行接口插件的类名。该属性与bankid属性同等重要，将决定要调用哪个银行接口插件。l developer：插件开发者名称，可选的属性。l corpration：插件开发者所属公司，可选的属性。l developtime：插件开发完成时间，可选的属性。l tel：插件开发者联系电话，可选的属性。l email：插件开发者email，可选的属性。每个元素则代表一个该银行需要的参数。在连接银行时，必须有一些参数，如银行服务器的IP、端口号、企业代码、操作员、操作员口令等等。这些参数的具体值须由用户在运行时指定，所以银行接口必须提供参数设置的界面。为了避免每个银行接口插件都开发参数设置界面，UFBank Service提供了统一的参数设置界面（UFBankConfig.exe），只要将银行需要的参数在配置文件中注册，UFBank Service的参数设置界面在运行时就会自动调用这些参数，由用户对其值进行设置。在UFBank Service调用银行接口插件时，会从配置文件中取出各个参数的值，作为参数传给银行接口插件的接口方法SendBank。元素的各属性值说明如下：l paraid：必须，参数ID，在一个下面，paraid必须唯一，否则会引发未知错误。l paraname：必须，参数名称，将在银行参数设置界面显示出来。l paravalue：必须，参数值，在二次开发人员注册时该属性的值为空串，在运行时用户在“参数设置界面”输入后会自动保存到配置文件中。l ispassword：必须，该参数是否口令字段，值必须为下列之一:Y|N|YES|NO|T|F|TRUE|FALSE，大小写不限，如为是，则参数设置界面保存paravalue时会对其值进行加密。这样，在配置文件中看到的paravalue就不会是密码的源文了，由此保证密码数据的安全。l note：必须，参数说明，对该参数进行的详细说明，本详细说明在参数设置界面会进行显示。为了更清楚地说明和属性的含义，下面对照参数设置界面进行说明：当元素的ispassword属性为Y等值时，文本框显示为密码框，且该框中的文本内容在保存到配置文件中时加密。在点击保存按钮时，文本框内的文本会被保存到配置文件中中paravalue属性的值。该处的文本对应于元素的paraname属性的值。屏幕提示的文本对应于元素的note属性的值。括起来的内容来自于配置文件中元素的fullname属性的值。每一个按钮对应着配置文件中一个节点。按钮上显示的文本为元素的shortname属性的值。重要说明：（1） 严禁修改配置文件中原有数据，只能向其中添加新的数据。（2） 银行标识符（元素bankid属性的值）与业务系统（NC、U8等）要严格一致，包括大小写。（3） 配置文件中内容是区分大小写的。（4） 添加的数据必须严格符合上述的要求。UFBank Service提供了会对配置文件进行有效性校验，如其格式不符合格式要求，会影响整个UFBank系统的运行，包括其他的银行接口插件。（5） 可以通过参数设置界面（执行UFBank安装目录下的UFBankConfig.exe文件）来测试添加的数据的有效性。如新增加的银行对应的按钮，以及点击该铵钮后的参数都能正确显示，则说明数据是有效的。4、 开发银行接口插件。银行接口插件必须编译为dll，插件必须实现UFBank Service要求的sendBank接口方法。该插件编译后的名称必须是上一步在配置文件中注册的元素的pluginclass属性的值。sendBank接口方法声明如下所示：sendBank(taskID as string, _BankID as string, _FuncID as string, _ParaNum as long, _ParaValue as variant, _SrcData as string, _RstData as string, _TranFlag as integer, _ErrMsg as string, _Log as object , _optional param1 as strng, _optional param2 as string, _optional param3 as string, _optional param4 as variant, _optional param5 as variant) as boolean返回值说明：执行成功返回True，执行失败返回False。参数说明：l taskid：任务号，业务系统每次调用UFBank，UFBank都会随机产生一个任务号。该任务号的主要作用是作为写日志文件时的参数，用以对日志进行分析时使用。l BankID：银行标识，在业务系统和UFBank中注册的银行标识。银行标识主要在UFBank Service中使用，用以从配置文件中寻找该银行标识对应的银行接口插件。该参数对银行接口插件的二次开发者暂时无用。l FuncID：功能号，即要求银行做什么样的操作。UFBank2.0中，要求银行接口插件实现5个功能，这5个功能的功能号分别为：功能号含义ye余额查询mx明细查询（对账单下载）zf支付jtzf集团支付zfcx支付查询 如果二次开发的银行对上述有的功能没实现，可返回错误信息。l ParaNum、ParaValue：参数个数和参数值，UFBank Service从配置文件中找到其注册的参数，并将其参数的个数、参数值通过这两个参数传递过来。ParaValue是一个String型的一维数组，数组的下限为0，上限为ParaNum-1。如果ParaNum=0，则说明银行接口插件没有在配置文件中注册参数，或取参数数据发生错误，这种情况下ParaValue未初始化，不要对其进行读取，否则会会发生运行时错误。l SrcData：业务系统传送过来的指令数据（内部标准格式）。二次开发人员需要将其转换成银行需要的格式。内部标准格式的详细说明请参看附录。l RstData：指令执行正确后的返回值（内部标准格式）。内部标准格式的详细说明请参看附录。l TranFlag：返回值类型，0成功，1失败，2不明（主要用于支付，由于网络问题、程序异常或银行问题等原因，导致银行没有显式返回成功或失败信息，支付情况不明，此时业务系统（NC、U8等）会限制用户再次支付，用户应尽快手工核对该笔业务的支付情况并根据核对结果再作后续处理）。l ErrMsg：指令执行错误后的错误提示。错误提示的详细说明请参看附录。l Log：日志访问对象。可利用该对象来写日志文件，写日志的方法原型如下：Public function PrintLog(taskID as string,className as string,msg as string) as BooleantaskID指任务号，即sendBank方法的第一个参数。className指类名和方法名（格式className:FunctionName），用来说明从哪个类中写的日志，这样如发生错误，在分析日志文件时会迅速定位到发生错误的类及方法。msg指要写入日志的具体内容。写日志成功返回true，失败返回false为了减少文件操作，建议不要过于频繁的写日志文件，建议在下面关键点写日志文件：写日志文件的关键点写入日志的主要内容sendBank方法的开始接收到的各参数数据值。银行连接成功说明银行已成功连接向银行发送数据向银行发送的数据内容银行返回数据银行返回数据的内容sendBank方法的结束返回的数据内容（发生错误则指错误数据内容）l param1param5：预留的参数，将来扩展使用。在银行接口插件中，需要实现的主要功能如下：（1） 将指令数据SrcData转换成银行要求的格式。（2） 连接银行服务器。（3） 向银行服务器发送转换后的指令格式。（4） 得到银行的返回值。（5） 将返回值转换为内部标准格式，并通过retData返回给调用者。七、 银行接口插件核心代码示例（兴业银行：CIB.clsCIB）。八、 传输代码段。1、 Http传输：Dim obj as Object 传输控件实例Dim lRet as Long 通讯状态标识Set obj = CreateObject(iisagent.datatran) 创建控件lRet = obj.posthttpex(sURL, strHead, vRet, vData) 传输数据If lRet = 0 Then 发送成功else 发送失败End IfSet obj = Nothing说明：iisagent.datatran是UFBank安装盘中自带的Http传输控件，二次开发和伙伴开发人员可以创建它并调用其Http传输接口。Posthttpex参数sURL：银行服务器URLstrHead：发送数据报文头vRet：返回数据报文vData：发送数据报文2、 TCPIP传输请参照下面附件VB模块文件TCPSend.bas中的TCPSend方法九、 发布。1、 准备一台服务器，UFBank一般与银行的前置机安装在一台机器上。2、 安装UFBank2.0版。3、 用包含二次开发银行接口插件的配置文件UFBankConfig.xml替换UFBank安装目录下的该文件。4、 将二次开发的银行接口插件（dll文件及其需要的配套文件）拷贝到UFBank安装的机器上，一般建议将其拷贝至UFBank安装目录的UFBankPlugin子目录下。5、 注册银行接口插件 regsvr32 xxxx.dll注册后用户即可使用了，具体的使用方法见网银适配器操作手册。十、 安装说明获得安装包解压双击“setup.exe”即可。默认安装到c:ufbank目录下。