招商銀行直聯(lián)系統(tǒng)開發(fā)指

1、招商銀行直聯(lián)系統(tǒng)開發(fā)指南version 1.0.0修訂記錄日期修訂版本修訂人修訂內(nèi)容2010-10-181.0.0楊成海新建招商銀行直聯(lián)系統(tǒng)開發(fā)指南11系統(tǒng)簡介31.1概述31.2背景31.2.1前置機式直聯(lián)：31.2.2嵌入式直聯(lián)：31.3閱讀對象31.4術(shù)語定義42解決方案42.1概述42.2功能52.3整體要求62.3.1系統(tǒng)要求62.3.2技術(shù)要求62.3.3企業(yè)要求62.4開發(fā)流程62.4.1準(zhǔn)備62.4.2開發(fā)72.4.3使用73前置機式83.1前置程序說明83.1.1概述83.1.2程序主界面說明83.1.3菜單功能說明93.1.4注意事項123.2通訊協(xié)議說明133.2.1概述

2、133.2.2http/https協(xié)議133.2.3socket協(xié)議133.3xml報文格式133.3.1概述133.3.2格式三143.3.3格式一153.3.4格式二163.3.5說明173.4調(diào)用頻率173.4.1說明173.5并發(fā)性能183.5.1說明184嵌入式184.1開發(fā)概述184.1.1概述184.1.2數(shù)據(jù)格式184.1.3接口返回值194.2多線程調(diào)用204.2.1概述204.2.2調(diào)用方法204.2.3調(diào)用說明204.2.4術(shù)語定義214.3編程接口214.3.1xml請求(xmlcomm)214.3.2系統(tǒng)函數(shù)224.3.3賬戶信息304.3.4支付結(jié)算354.3.5代

3、發(fā)代扣404.3.6國內(nèi)信用證464.3.7商務(wù)支付524.3.8其他接口545版本說明555.1版本信息555.2升級建議565.3查看版本信息566資源下載576.1招商銀行銀企直連接口說明書(xml格式三說明文檔)576.2人行電子票據(jù)銀企直連接口說明書(xml格式三)576.3招商銀行票據(jù)通銀企直連接口說明書(xml格式三)576.4xml格式一和格式二報文說明文檔586.5開發(fā)范例源碼581 系統(tǒng)簡介1.1 概述本開發(fā)指南對招商銀行企業(yè)銀行直聯(lián)系統(tǒng)（以下簡稱本系統(tǒng)）進行詳細地描述，通過該指南可以對本系統(tǒng)有個全面地了解，并可用于指導(dǎo)如何在該系統(tǒng)上進行二次開發(fā)，實現(xiàn)與企業(yè)財務(wù)/erp/電

4、子商務(wù)交易平臺等系統(tǒng)（以下簡稱企業(yè)財務(wù)系統(tǒng)）平滑對接和有機融合。 1.2 背景招商銀行網(wǎng)上企業(yè)銀行本身有一套完整的經(jīng)辦、審批機制，幫助企業(yè)規(guī)范財務(wù)制度、安全地做網(wǎng)上業(yè)務(wù)，但是它有一定的限制，就是必須在企業(yè)銀行系統(tǒng)內(nèi)封閉的完成。 很多企業(yè)都有一套自己的財務(wù)系統(tǒng)，企業(yè)使用財務(wù)系統(tǒng)生成一些經(jīng)辦業(yè)務(wù)需要的數(shù)據(jù)，如支付脫機制單數(shù)據(jù)、工資表和收方信息等，然后將生成的數(shù)據(jù)交由企業(yè)銀行系統(tǒng)經(jīng)辦和審批，再將銀行返回的數(shù)據(jù)導(dǎo)入到財務(wù)系統(tǒng)中。目前企業(yè)財務(wù)系統(tǒng)與企業(yè)銀行系統(tǒng)間只能以文件形式進行數(shù)據(jù)交換，而企業(yè)希望能在自己的系統(tǒng)內(nèi)和企業(yè)銀行間進行直接的數(shù)據(jù)交換。 基于以上情況，招商銀行開發(fā)了本系統(tǒng)。本系統(tǒng)提供兩種方式與

5、企業(yè)財務(wù)系統(tǒng)對接。一種是前置機式；一種是嵌入式。 1.2.1 前置機式直聯(lián)：即通過在企業(yè)內(nèi)部網(wǎng)絡(luò)內(nèi)安裝一臺前置機（即安裝了本系統(tǒng)并啟動了直連服務(wù)的pc機），企業(yè)財務(wù)系統(tǒng)通過報文交互的方式與前置機通訊，以實現(xiàn)向企業(yè)銀行系統(tǒng)發(fā)送指令，并接收銀行返回的數(shù)據(jù)。 1.2.2 嵌入式直聯(lián)：即通過在企業(yè)財務(wù)系統(tǒng)內(nèi)部調(diào)用本系統(tǒng)提供的接口，實現(xiàn)財務(wù)系統(tǒng)和企業(yè)銀行間的直接交互。本系統(tǒng)作為財務(wù)系統(tǒng)的一個組成部分嵌入到財務(wù)系統(tǒng)，在財務(wù)系統(tǒng)和企業(yè)銀行間采用不落地方式交換數(shù)據(jù)，財務(wù)系統(tǒng)通過本系統(tǒng)提供的接口直接向企業(yè)銀行系統(tǒng)發(fā)送指令，并接收銀行返回的數(shù)據(jù)。 1.3 閱讀對象預(yù)期讀者為利用本系統(tǒng)進行二次開發(fā)的相關(guān)人員，以及其

6、他需要了解本系統(tǒng)的人員。 1.4 術(shù)語定義招行銀企直聯(lián)：招商銀行提供的一種網(wǎng)上“企業(yè)銀行”系統(tǒng)與企業(yè)的財務(wù)軟件系統(tǒng)的直接聯(lián)接的接入方式。招行企業(yè)網(wǎng)銀：招商銀行企業(yè)網(wǎng)銀是使用本地客戶端軟件，通過internet網(wǎng)絡(luò)或其它信息網(wǎng)絡(luò)，將用戶電腦終端連接至銀行，實現(xiàn)將銀行服務(wù)直接送到用戶辦公室和家中。它改變了銀行傳統(tǒng)的服務(wù)方式，是銀行業(yè)務(wù)系統(tǒng)的擴充和延伸。用戶管理：企業(yè)銀行系統(tǒng)的用戶分為系統(tǒng)管理員和一般用戶。企業(yè)到銀行申請開辦“企業(yè)銀行”業(yè)務(wù)時，由銀行為企業(yè)生成兩個系統(tǒng)管理員，兩個系統(tǒng)管理員的權(quán)限完全平等，共同負責(zé)企業(yè)銀行管理的工作。通常系統(tǒng)的設(shè)置必須由一個系統(tǒng)管理員進行經(jīng)辦而由另一個系統(tǒng)管理員進行授

7、權(quán)，必須兩個系統(tǒng)管理員同時認(rèn)可后設(shè)置方才有效；系統(tǒng)管理員不能為自己設(shè)置業(yè)務(wù)權(quán)限，也不能對自己經(jīng)辦的系統(tǒng)設(shè)置進行授權(quán)。建議由公司財務(wù)經(jīng)理擔(dān)任系統(tǒng)管理員之一。一般用戶由系統(tǒng)管理員使用“用戶管理”功能增加到系統(tǒng)中，由系統(tǒng)管理員設(shè)置其權(quán)限。負責(zé)在權(quán)限內(nèi)經(jīng)辦和授權(quán)各項企業(yè)銀行業(yè)務(wù)。另外，系統(tǒng)管理員也可具有業(yè)務(wù)權(quán)限，處理企業(yè)銀行業(yè)務(wù)。業(yè)務(wù)管理：業(yè)務(wù)管理用于在網(wǎng)上企業(yè)銀行上建立適應(yīng)企業(yè)內(nèi)部財務(wù)管理要求的業(yè)務(wù)操作規(guī)范。網(wǎng)上企業(yè)銀行采用靈活的預(yù)設(shè)模式方式，實行“操作鏈”式管理，系統(tǒng)性地固化企業(yè)財務(wù)管理制度?？蛻艨梢宰杂啥ㄖ破髽I(yè)內(nèi)部財務(wù)授權(quán)管理模式，適應(yīng)多種個性化財務(wù)管理需求?！安僮麈湣毙蜗蟮孛枋隽似髽I(yè)內(nèi)部財務(wù)管

8、理的崗位設(shè)置、業(yè)務(wù)分工和業(yè)務(wù)流程，同時規(guī)定了崗位上不同身份的人員的操作權(quán)限和關(guān)系。“操作鏈”上設(shè)經(jīng)辦崗位一個，設(shè)審批崗位一級或多級。經(jīng)辦崗位可以設(shè)置多人，人數(shù)不限制。經(jīng)辦人員負責(zé)所有其有權(quán)處理的業(yè)務(wù)的制單發(fā)起操作，經(jīng)辦人員之間是同一級別的并列關(guān)系。每一級審批崗位只可以設(shè)一名審批人員，審批人員負責(zé)其有權(quán)處理的業(yè)務(wù)的復(fù)核審批操作，不同級別審批崗位之間是上下級的關(guān)系，審批的權(quán)限依次增大，但是審批的流程必須依次進行，不得越級。備注：招行銀企直聯(lián)與招行企業(yè)網(wǎng)銀共用一套用戶管理、業(yè)務(wù)管理系統(tǒng)，后臺業(yè)務(wù)處理系統(tǒng)也相同，是招行網(wǎng)上企業(yè)銀行系統(tǒng)的兩個不同接入渠道。用戶、業(yè)務(wù)管理只能在企業(yè)網(wǎng)銀上管理。ca（認(rèn)證中

9、心）：（certification authority 認(rèn)證中心）是用來頒發(fā)數(shù)字證書的權(quán)威機構(gòu)，它具有權(quán)威性、公正性和可靠性。其主要任務(wù)是受理數(shù)字證書的申請、簽發(fā)及對數(shù)字證書的管理。在受理申請的同時，一般還會核對申請者的身份，以確保正確。數(shù)字證書：數(shù)字證書是用電子手段來證實一個用戶的身份和對網(wǎng)絡(luò)資源的訪問權(quán)限。數(shù)字證書是由權(quán)威機構(gòu)(ca)采用數(shù)字簽名技術(shù)，頒發(fā)給用戶，用以在數(shù)字領(lǐng)域中證實用戶其本身的一種數(shù)字憑證。本系統(tǒng)的證書由招商銀行ca簽發(fā)，用于確認(rèn)用戶在招行企業(yè)銀行系統(tǒng)中的身份。2 解決方案2.1 概述本系統(tǒng)支持兩種直連方式： 前置機式：向本系統(tǒng)發(fā)送http請求，實現(xiàn)和銀行的直聯(lián)。（具體請

10、參考目錄前置機式） 嵌入式：以win32動態(tài)鏈接庫（dll）和java開發(fā)包(jar)的方式提供編程調(diào)用接口，企業(yè)可利用這些接口進行相應(yīng)的二次開發(fā)。該方式支持vc、vb、c#、delphi、cb、pb、java等開發(fā)工具。（具體請參考目錄嵌入式） 結(jié)構(gòu)示意圖如上圖所示，企業(yè)可以有自己完善的財務(wù)管理系統(tǒng)，公司內(nèi)部資金調(diào)撥及對外支付先經(jīng)過其內(nèi)在的財務(wù)管理流程，再通過招行提供的編程接口把生成的指令直接提交到招行，招行根據(jù)該指令進行處理；企業(yè)的帳戶信息、交易信息等也可以通過直聯(lián)接口從招行獲得。 2.2 功能 本系統(tǒng)目前提供的主要功能包括： 查詢帳戶信息 查詢交易信息 支付/直接支付 集團支付/直接集團

11、支付 直接代發(fā)/代扣 內(nèi)部轉(zhuǎn)賬 國內(nèi)信用證 商務(wù)支付 接收各種通知信息 配置系統(tǒng)參數(shù) 委托貸款 定期業(yè)務(wù) 信用管理 人民幣現(xiàn)金池 代理清算 外匯匯款 人行電子票據(jù) 招商網(wǎng)上電子票據(jù) 支付限額協(xié)議管理 資金余額管理大額劃撥后續(xù)將根據(jù)市場需求，逐步添加其他業(yè)務(wù)。2.3 整體要求2.3.1 系統(tǒng)要求 硬件：建議pentium133以上cpu，32mb ram，至少256色（建議16位以上真彩）顯示，100m以上的空閑硬盤空間。對數(shù)字證書卡用戶，需要一個串口或usb口，用于安裝數(shù)字證書卡驅(qū)動器； 操作系統(tǒng)：建議中文/英文windows 98/nt/2000/xp/2003，對英文windows，需要外

12、掛中文平臺； 瀏覽器：必須安裝microsoft internet explorer 4.0以上的瀏覽器。本系統(tǒng)不支持netscape的瀏覽器； 系統(tǒng)環(huán)境：建議使用一臺電腦專門運行財務(wù)系統(tǒng)和直聯(lián)系統(tǒng)，應(yīng)確保系統(tǒng)中沒有病毒、木馬等有害程序。 2.3.2 技術(shù)要求 在正式使用直聯(lián)系統(tǒng)前，請確認(rèn)您所使用的財務(wù)系統(tǒng)和本系統(tǒng)的直聯(lián)已在招行的測試環(huán)境下經(jīng)過嚴(yán)格測試，并得到招行技術(shù)部門的認(rèn)證； 請確認(rèn)所使用的本系統(tǒng)的動態(tài)庫均有招行的數(shù)字簽名。 2.3.3 企業(yè)要求 開通招行網(wǎng)上企業(yè)銀行； 與招行簽訂直聯(lián)協(xié)議； 開通帳戶查詢、直接支付等所需業(yè)務(wù)，經(jīng)辦用戶需要擁有招行簽發(fā)的數(shù)字證書卡。 2.4 開發(fā)流程2.4.

13、1 準(zhǔn)備 到所在地招行的分/支行開通招行企業(yè)銀行； 到所在地招行的分/支行申請調(diào)試直聯(lián)系統(tǒng)，銀行分配用于測試的用戶id、密碼等； 到招行網(wǎng)站下載本系統(tǒng)的開發(fā)工具包（包括開發(fā)包安裝程序、本開發(fā)指南等）； 運行開發(fā)包安裝程序完成本系統(tǒng)的安裝； 修改system32driversetchosts文件，增加兩行數(shù)據(jù)：6 6 使用fbsdkmanager.exe或者fbsdktest.exe修改通訊方式的服務(wù)器為測試機，如下圖所示： 通過提供的測試程序驗證測試環(huán)境是否正確。（注：在測試環(huán)境，允許

14、經(jīng)辦用戶采用非證書卡方式登錄） 2.4.2 開發(fā) 根據(jù)提供的編程接口，在自己的財務(wù)系統(tǒng)上進行開發(fā)，實現(xiàn)所需要的業(yè)務(wù)功能（接口調(diào)用可參考提供的測試程序源代碼）； 對自己財務(wù)系統(tǒng)的業(yè)務(wù)功能進行測試（可根據(jù)提供的測試程序進行驗證）。 2.4.3 使用 到所在地招行的分/支行簽訂直聯(lián)協(xié)議； 到所在地招行的分/支行開通直接支付/賬戶查詢等所需業(yè)務(wù)； 到招行網(wǎng)站下載本系統(tǒng)的正式發(fā)布包； 運行正式發(fā)布包安裝程序完成本系統(tǒng)的安裝； 在企業(yè)銀行客戶端，由企業(yè)系統(tǒng)管理員對業(yè)務(wù)模式進行設(shè)置； 可在自己財務(wù)系統(tǒng)上進行相應(yīng)的直聯(lián)操作，完成相關(guān)業(yè)務(wù)。（注：在真實環(huán)境，經(jīng)辦用戶必須采用證書卡方式登錄） 專線用戶，且無dns

15、服務(wù)器時需要在系統(tǒng)host文件中增加如下域名的映射：，，，， 3 前置機式3.1 前置程序說明3.1.1 概述本系統(tǒng)支持http/https/socket請求，企業(yè)通過http/https（post方式）或socket協(xié)議發(fā)送請求到前置程序fbsdkmanager，并處理接收到的應(yīng)答報文來實現(xiàn)和銀行系統(tǒng)的交互。3.1.2 程序主界面說明1、登錄信息：顯示目前登錄的用戶信息。2、系統(tǒng)日志：顯示系統(tǒng)操

16、作日志等信息。3、提示欄：從左到右依次為：服務(wù)啟動信息、用戶登陸信息、系統(tǒng)啟動時間信息。4、系統(tǒng)菜單：詳情見菜單功能說明。5、菜單工具欄：從左至右依次為：啟動服務(wù)、停止服務(wù)、登陸銀行、退出銀行、系統(tǒng)設(shè)置、銀行通訊設(shè)置、查看系統(tǒng)日志、系統(tǒng)開發(fā)指南。3.1.3 菜單功能說明1、系統(tǒng)系統(tǒng)設(shè)置：設(shè)置服務(wù)類型以及監(jiān)聽端口、設(shè)置是否記錄業(yè)務(wù)報文日志、設(shè)置是否過濾企業(yè)端ip地址、設(shè)置程序是否自動鎖定。設(shè)置服務(wù)類型以及監(jiān)聽端口設(shè)置是否記錄業(yè)務(wù)報文日志：記錄直聯(lián)系統(tǒng)接收到的xml報文以及發(fā)送給企業(yè)財務(wù)軟件系統(tǒng)的xml報文。設(shè)置是否過濾企業(yè)端ip地址：當(dāng)啟用ip過濾時，系統(tǒng)如發(fā)現(xiàn)請求報文來自允許訪問列表之外的地址

17、，將拒絕訪問。設(shè)置程序是否自動鎖定2、系統(tǒng)鎖定程序：隱藏直聯(lián)前置程序窗口，恢復(fù)窗口需要輸入鎖定密碼。3、服務(wù)啟動服務(wù)：啟動服務(wù)前必須先設(shè)置服務(wù)類型以及監(jiān)聽端口。4、服務(wù)停止服務(wù)：必須在所有登陸用戶退出銀行系統(tǒng)后才能停止服務(wù)。5、登陸登陸銀行：必須啟動服務(wù)后才能登陸銀行系統(tǒng)。6、登陸退出銀行：退出銀行系統(tǒng)，選中登陸用戶后該菜單才可操作。7、登陸銀行通訊設(shè)置：設(shè)置登陸銀行通訊參數(shù)，該參數(shù)必須在用戶登錄前設(shè)置。8、查看查看日志：日志分為兩種：一種是業(yè)務(wù)報文日志，密文保存(可保存為明文）；一種是系統(tǒng)操作日志，明文保存。9、查看查看業(yè)務(wù)模式：選中登陸用戶后，可查看該用戶下的業(yè)務(wù)模式信息（包括業(yè)務(wù)名稱以及

18、編號）。需要輸入業(yè)務(wù)代碼，業(yè)務(wù)代碼在接口文檔中有詳細說明。10、幫助開發(fā)指南：顯示招商銀行銀企直聯(lián)系統(tǒng)對接開發(fā)指南。11、幫助關(guān)于銀企直聯(lián)：顯示招商銀行銀企直聯(lián)系統(tǒng)版本等信息。3.1.4 注意事項1、該系統(tǒng)實現(xiàn)了和銀行自動重連的功能（當(dāng)收到http/https/socket請求時，如果和銀行的連接已經(jīng)斷開，會自動進行重連）。2、請求和應(yīng)答的報文都采用xml格式（請參考xml報文格式）。3、請求的報文需要在中增加，內(nèi)容為登錄的用戶名。4、不支持下列接口的請求：登陸(login)簽退(logout)，系統(tǒng)參數(shù)設(shè)置(setconfig),保持連接(setalive)釋放緩沖區(qū)(freebuffer)

19、，xml 接口調(diào)用(xmlcomm)。5、注意：只要能向運行前置程序fbsdkmanager的機器發(fā)送http/socket請求就能和銀行進行直聯(lián)，因此必須保證該機器網(wǎng)絡(luò)的安全性，和其它無關(guān)的機器在網(wǎng)絡(luò)上做到安全隔離。3.2 通訊協(xié)議說明3.2.1 概述企業(yè)財務(wù)系統(tǒng)與直聯(lián)前置程序間通訊協(xié)議支持http、https、socket三種協(xié)議。3.2.2 http/https協(xié)議企業(yè)端使用http/https協(xié)議，通過post方式提交xml報文數(shù)據(jù)到直聯(lián)前置程序，并接收返回xml報文數(shù)據(jù)，完成報文數(shù)據(jù)交換。3.2.3 socket協(xié)議 企業(yè)端使用socket協(xié)議，通過以下數(shù)據(jù)包格式提交xml報文數(shù)據(jù)到

20、直聯(lián)前置程序，完成報文數(shù)據(jù)交換。通訊數(shù)據(jù)包格式為：8位字節(jié)報頭（xml報文長度，左對齊，長度不夠右補空格) + xml報文。范例：假如xml報文長度為1300個字節(jié)，通訊數(shù)據(jù)包格式為：“1300”（右邊4個空格） + xml報文。3.3 xml報文格式3.3.1 概述本系統(tǒng)共提供了三種xml報文格式，主要用于前置機與企業(yè)端數(shù)據(jù)交換以及嵌入式開發(fā)中的xml請求(xmlcomm)函數(shù)。格式三在v1.7版本推出，新直連用戶請使用格式三的標(biāo)準(zhǔn)進行開發(fā)，將來新功能都只支持格式三的報文格式。3.3.2 格式三請求報文： / encoding如果設(shè)置成big5表示繁體報文 / 函數(shù)名 2 / 數(shù)據(jù)格式（固定

21、為2） / 用戶自定義數(shù)據(jù)，應(yīng)答報文會原樣返回，建議字段名不要用6位的字母 / 自定義接口名稱 field-value /自定義字段名稱，字段值 /可以定義多個字段 / 可以定義多個接口 應(yīng)答報文： / encoding和請求一致 / 函數(shù)名 2 / 數(shù)據(jù)格式（固定為2） / 調(diào)用結(jié)果 / 錯誤消息 / 用戶自定義數(shù)據(jù) / 自定義接口名稱 field-value /自定義字段名稱，字段值 /可以定義多個字段 / 可以定義多個接口 備注：不同的交易接口名稱不一樣，一個請求報文中可以有多個不同的接口，接口名也可以重名。3.3.3 格式一請求報文： / encoding如果設(shè)置成big5表示繁體報文

22、 / 函數(shù)名 0 / 數(shù)據(jù)格式（固定為0） / 用戶自定義數(shù)據(jù)，應(yīng)答報文會原樣返回，建議字段名不要用6位的字母 / 概要信息 / 詳細信息 應(yīng)答報文： / encoding和請求一致 / 函數(shù)名 0 / 數(shù)據(jù)格式（固定為0） / 調(diào)用結(jié)果 / 錯誤消息 / 用戶自定義數(shù)據(jù) / 概要信息 / 詳細信息備注：1、概要信息為單條記錄，明細信息支持多條記錄，每條記錄由多個字段組成，字段間用 ;(空格加分號)分開，各個字段格式為：字段名=數(shù)值。2、對于明細信息，如果是多條記錄，每條記錄用rn分開（rn是指回車符和換行符）。3.3.4 格式二請求報文： / encoding如果設(shè)置成big5表示繁體報文

23、/ 函數(shù)名 1 / 數(shù)據(jù)格式（固定為1） / 用戶自定義數(shù)據(jù)，應(yīng)答報文會原樣返回，建議字段名不要用6位的字母 / 概要信息 / 詳細信息 / 詳細信息數(shù)據(jù) 應(yīng)答報文： / encoding和請求一致 / 函數(shù)名 1 / 數(shù)據(jù)格式（固定為1） / 調(diào)用結(jié)果 / 錯誤消息 / 用戶自定義數(shù)據(jù) / 概要信息 / 詳細信息 / 詳細信息數(shù)據(jù) 備注：概要信息和詳細信息的數(shù)據(jù)由多個字段組成，格式為數(shù)值。3.3.5 說明1、對于函數(shù)名()，除了用getaccinfo表示getaccinfoa，gettransinfo表示gettransinfoa，payment代替directpayment和directg

24、rouppayment，其他和編程接口的函數(shù)名保持一致。2、對于調(diào)用結(jié)果()錯誤消息()，和調(diào)用指定函數(shù)后的返回值和錯誤信息相同。3、概要和明細的具體信息請參考各個函數(shù)的說明。4、請求報文字段值中的&和&，<，應(yīng)答報文要做相反的格式轉(zhuǎn)換。格式三說明文檔：見招商銀行銀企直連接口說明書(xml格式三說明文檔)格式一和格式二說明文檔：見xml格式一和格式二報文說明文檔3.4 調(diào)用頻率3.4.1 說明請求調(diào)用間隔：本次請求調(diào)用與上次請求調(diào)用之間的時間差；調(diào)用頻率控制按接口種類區(qū)別控制： 經(jīng)辦類請求：兩次經(jīng)辦類請求最小調(diào)用間隔為1秒； 查詢類請求：兩次查詢類請求最小調(diào)用間隔為2秒； 通知類

25、請求：兩次通知類請求最小調(diào)用間隔為5秒。1 當(dāng)調(diào)用頻率沒有滿足以上條件時（實際調(diào)用間隔小于最小調(diào)用間隔），系統(tǒng)默認(rèn)會內(nèi)部等待，等待時間為：最小調(diào)用間隔 實際調(diào)用間隔，等待完成后再處理該請求。2 當(dāng)調(diào)用頻率滿足以上條件時（實際調(diào)用間隔大于或等于最小調(diào)用間隔），系統(tǒng)立即處理該請求并轉(zhuǎn)發(fā)到銀行后臺系統(tǒng)。 調(diào)用頻率控制以登陸用戶為單位，不同登陸用戶之間不受影響。3.5 并發(fā)性能3.5.1 說明本系統(tǒng)支持多用戶并發(fā)請求，同一用戶的多個請求按照優(yōu)先隊列排隊處理，為了避免請求等待時間過長，建議同一用戶并發(fā)請求不要超過50個，登陸用戶數(shù)沒有限制。備注：一臺電腦只能安裝一個招行前置機，多臺電腦允許安裝多個招行前

26、置機。4 嵌入式4.1 開發(fā)概述4.1.1 概述本系統(tǒng)提供了兩種編程接口： c編程接口（用int _stdcall定義） java編程接口（用public sdkresult定義） 所有編程接口都由本系統(tǒng)的fbsdk.dll文件提供，請確保您的系統(tǒng)正確加載了此文件。對java開發(fā)還提供了fbsdk.jar文件，編程接口封裝在類fbsdkjni中，返回結(jié)果封裝在類sdkresult中企業(yè)向招行提交的指令數(shù)據(jù)要求、招行向企業(yè)返回數(shù)據(jù)的定義等請參考數(shù)據(jù)接口手冊(2.1版)。 4.1.2 數(shù)據(jù)格式調(diào)用本系統(tǒng)編程接口時，傳入的指令和返回的結(jié)果，一般采用以下的數(shù)據(jù)格式： 以0結(jié)束； 支持多條記錄，每條記錄

27、用rn分開（rn是指回車符和換行符）； 每條記錄由多個字段組成，字段間用 ;(空格加分號)分開，各個字段格式為：字段名=數(shù)值； 字段之間沒有順序關(guān)系； 如果某個字段對應(yīng)的數(shù)值為空，則該字段可以省略； 字段如果對應(yīng)日期，格式為：yyyymmdd；對應(yīng)時間，格式為：hhmmss；對應(yīng)日期+時間，格式為：yyyymmddhhmmss； 字段如果對應(yīng)金額，格式為：nnnnnnnnnnnnn.nn，整數(shù)部分最多13位，小數(shù)部分最多2位。 4.1.3 接口返回值 c編程接口采用統(tǒng)一的返回編碼（整數(shù)）：0：成功；-1：提交主機失??；-2：執(zhí)行失?。?3：數(shù)據(jù)格式錯誤；-4：尚未登錄系統(tǒng)；-5：請求太頻繁；-

28、6：不是證書卡用戶；-7：用戶取消操作；-9：其它錯誤；當(dāng)返回編碼不是0時，函數(shù)參數(shù)中的szerrormsg有效，表示具體錯誤信息（字符串szerrormsg以0結(jié)束）。當(dāng)返回編碼不是0時，可通過setalive函數(shù)來判斷和銀行服務(wù)器的連接是否出現(xiàn)錯誤。 java編程接口返回結(jié)果封裝在類sdkresult中。下面是類sdkresult接口函數(shù)的說明： / 判斷接口調(diào)用是否有正確（true：正確；false：錯誤） public boolean iserror(); / 獲得錯誤id（編碼和c編程接口一致） / 判斷錯誤id是否為0，等同于調(diào)用iserror(); public int gete

29、rrorid(); / 獲得錯誤信息 public string geterrormessage(); / 獲得返回結(jié)果數(shù)據(jù) public string getdata(); 4.2 多線程調(diào)用4.2.1 概述以前的版本已經(jīng)支持多線程調(diào)用，但只允許登錄一個用戶，所有線程都共用該用戶的身份進行業(yè)務(wù)處理。為了支持多個用戶登錄，不同用戶可以各自進行自己的業(yè)務(wù)處理，及以后的版本對多線程的支持進行了改進。如果您的系統(tǒng)使用了多線程，請務(wù)必仔細閱讀本文。4.2.2 調(diào)用方法 單用戶單線程（只登錄一個用戶，所有接口調(diào)用都在一個線程里完成） 主登錄后，直接調(diào)用所需接口，不需要任何特別

30、處理 單用戶多線程（只登錄一個用戶，多個線程進行接口調(diào)用） 在一個線程中進行主登錄；如：login(, 0, szerrormsg); 登錄后通過getsysinfo取得用戶登錄名；如：假設(shè)這里取到的用戶登錄名為sh01 在其它線程進行線程登錄，實現(xiàn)該用戶的共享連接；如login(lgntyp=-2 ;lgnnam=sh01, 0, szerrormsg); 登錄后，各個線程調(diào)用各自所需的接口進行業(yè)務(wù)處理。 多用戶多線程（登錄多個用戶，每個用戶有多個線程進行接口調(diào)用） 各個用戶在各自的線程進行主登錄； 每個用戶的其它線程進行線程登錄，實現(xiàn)各個用戶的共享連接； 登錄后，各個線程調(diào)用各自所需的接口

31、進行業(yè)務(wù)處理。 4.2.3 調(diào)用說明1、主登錄必須用同步的方法進行調(diào)用（線程登錄不需要同步）。2、主登錄的線程：該線程以后只能進行主登錄，不允許進行線程登錄。3、主登錄的線程：該線程可以調(diào)用logout方法，調(diào)用后，和它共享連接的的所有線程自動退出登錄。4、主登錄的線程調(diào)用主登錄重新登錄后，和它共享連接的所有線程必須重新調(diào)用線程登錄。5、線程登錄時，必須確保該線程已經(jīng)創(chuàng)建了（如果線程是通過類實現(xiàn)的，不要在類的構(gòu)造函數(shù)中調(diào)用，因為這時候該線程還未真正創(chuàng)建）。6、線程登錄的線程：該線程以后只能進行線程登錄，不允許進行主登錄。7、線程登錄的線程：該線程不允許調(diào)用logout方法。8、線程登錄的線程：

32、進行業(yè)務(wù)處理時，主登錄的線程必須還沒有結(jié)束。9、不支持一個線程登錄多個用戶，一個線程只能登錄一個用戶（如果在一個線程創(chuàng)建多個fbsdk實例，這些fbsdk實例會共享同一個用戶連接）。10、如果登錄多個證書卡用戶，這些用戶必須關(guān)聯(lián)同一張證書卡。11、共享同一用戶連接的線程和銀行端只保持一個連接，銀行端今后可能會對同一用戶多個連接進行控制。因此不要在多個線程以非線程登錄的方式登錄同一用戶，這樣這些線程就不是共享同一用戶連接，而是各自獨立地連接到銀行端。12、如果用戶在之前的版本使用了單用戶多線程功能，要升級到及以后的版本，請按照上文給出的調(diào)用方法進行相應(yīng)的修改。4.2.

33、4 術(shù)語定義主登錄：使用自動登錄、重登錄、手工登錄等方式調(diào)用login。線程登錄：使用線程登錄的方式調(diào)用login。4.3 編程接口4.3.1 xml請求(xmlcomm)int _stdcallxmlcomm(const char *szrequest, char *szresponse, int *ilength, char *szerrormsg);public sdkresultxmlcomm(string srequest);說明：xml接口調(diào)用，通過該接口可以實現(xiàn)其他接口的調(diào)用，報文格式請參考xml報文格式。參數(shù)：inszrequest： srequest：xml請求報文。outs

34、zresponse：xml應(yīng)答報文。 該參數(shù)為指向指針的指針，數(shù)據(jù)緩沖區(qū)在dll中創(chuàng)建，只要接口調(diào)用成功，就必須調(diào)用freebuffer函數(shù)釋放該緩沖區(qū)。 outilength：xml應(yīng)答報文長度。只有大于0時，szrespond才有效。outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本4.3.2 系統(tǒng)函數(shù) loginint _stdcalllogin(const char *szdata, int ilength, char *szerrormsg);public sdkresultlogin();public

35、sdkresultlogin(string sdata);說明：登錄系統(tǒng)。該接口封裝了安全通訊管道的建立以及企業(yè)用戶的身份認(rèn)證。其它接口函數(shù)如果沒有特別說明，都要成功登錄后才能調(diào)用。參數(shù)：inszdata： sdata：登錄信息。只有一條記錄（數(shù)據(jù)格式），由以下幾個字段組成：lgntyp：登錄方式（可空）0：指定用戶名/密碼登錄；-1：重登陸；-2：線程登錄；其它：顯示登錄對話框手動登錄lgnnam：登錄用戶名lgnpwd：登錄密碼iccpwd：卡密碼corkey：企業(yè)鍵值（可空，保留，不需要）inilength：保留字段 0：建議值-1：重登錄，和lgntyp=-1相同，如果lgntyp有值

36、，忽略該字段（只是為了兼容以前的版本，建議不要通過該字段實現(xiàn)重登錄功能）outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本支持手工登錄及之后版本支持手工登錄；自動登錄；重登錄；線程登錄備注：系統(tǒng)提供以下幾種登錄方式：登錄方式lgntyplgnnamlgnpwdiccpwd備注自動登錄0非空非空可空不顯示登錄對話框，以傳入的登錄信息直接登錄 iccpwd非空時：以證書卡用戶身份登錄 范例：login(lgntyp=0 ;lgnnam=sh01 ;lgnpwd=88889999 ;iccpwd=88889999, 0,

37、 szerrormsg); iccpwd為空時：以非證書卡用戶身份登錄 范例：login(lgntyp=0 ;lgnnam=sh02 ;lgnpwd=88889999, 0, szerrormsg); 重登錄-1忽略忽略忽略未成功登錄過系統(tǒng)：顯示登錄對話框，用戶輸入登錄信息進行登錄。 成功登錄過系統(tǒng)：不顯示登錄對話框，以上次登錄的登錄信息自動登錄 范例：login(lgntyp=-1, 0, szerrormsg); / 方法一，建議 范例：login(, -1, szerrormsg); / 方法二，不建議 線程登錄-2非空忽略忽略同一用戶共享連接。如果該用戶尚未登錄，返回錯誤。參考多線程調(diào)

38、用范例：login(lgntyp=-2 ;lgnnam=sh01, 0, szerrormsg); 手工登錄忽略忽略忽略忽略顯示登錄對話框，用戶輸入登錄信息進行登錄 范例：login(, 0, szerrormsg); logoutint _stdcalllogout(char *szerrormsg);public sdkresultlogout();說明：退出登錄。參數(shù)：outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本 setconfigint _stdcallsetconfig(int it

39、ype, char *szerrormsg);public sdkresultsetconfig(int itype);說明：系統(tǒng)參數(shù)設(shè)置。參數(shù)：initype：設(shè)置類型。包括以下幾種類型：1：修改通訊參數(shù)。可以在未登錄的情況下修改2：修改登陸名。只有登錄后才能修改3：修改聯(lián)機登陸密碼。只有登錄后才能修改4：修改數(shù)字證書卡密碼。只有以證書卡方式登錄后才能修改5：查看證書。只有以證書卡方式登錄后才能查看outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本 getnewnoticeint _stdcallgetnewno

40、tice(char *szdata, int *ilength, char *szerrormsg);public sdkresultgetnewnotice();說明：取新的通知。參數(shù)：outszdata：通知信息數(shù)據(jù)指針。緩沖區(qū)必須不小于64k，每條通知作為一條記錄（數(shù)據(jù)格式），具體格式請參考招商銀行直連接口說明書中1.4取新通知的響應(yīng)報文接口ntqntcgtz，他包含了到賬、付款交易通知和直接支付結(jié)果通知兩種格式。outilength：通知信息數(shù)據(jù)長度。只有大于0時，szdata才有效。outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：1.1.0

41、.0及之后版本備注：1、本系統(tǒng)目前返回的通知共有三種：直接支付結(jié)果通知(ncdrtpay)、到賬通知（nccrttrs）和付款通知（ncdbttrs）。2、只能取到新的通知，已經(jīng)取過的通知不會再次發(fā)送。3、一次調(diào)用只會返回一定條數(shù)的通知，可反復(fù)調(diào)用該接口，直到取完所有通知。4、每筆到賬/付款通知都會對應(yīng)一筆交易信息，可通過通知信息中的帳號（accnbr）+交易日（trsdat）+流水號（seqnbr），和交易信息中該帳號的交易日（etydat）+流水號（refnbr）進行關(guān)聯(lián)。范例：int iret = 0;int ilength = 0;do char szdata64*1024 = 0;

42、char szerrormsg256 = 0; iret = getnewnotice(szdata, &ilength, szerrormsg);while (0 != iret) & (0 ilength); getsysinfoint _stdcallgetsysinfo(const char *szquery, char *szdata, int *ilength, char *szerrormsg);public sdkresultgetsysinfo(string squery);說明：取系統(tǒng)信息。參數(shù)：inszquery： squery：查詢條件。只有一條記錄(數(shù)據(jù)

43、格式)，由一個字段組成：systyp：系統(tǒng)信息類別（非空，目前只支持取用戶信息（usrinf）outszdata：系統(tǒng)信息數(shù)據(jù)?？赡馨鄺l系統(tǒng)信息，每條系統(tǒng)信息一條記錄(數(shù)據(jù)格式)。 該參數(shù)為指向指針的指針，數(shù)據(jù)緩沖區(qū)在dll中創(chuàng)建，只要接口調(diào)用成功，就必須調(diào)用freebuffer函數(shù)釋放該緩沖區(qū)。 目前只有取用戶信息，返回一條記錄，包含以下幾個字段：lgnnam：用戶登錄名usrnam：用戶姓名lgntim：用戶上次成功登錄時間（日期+時間）usrtyp：用戶類型（p：系統(tǒng)管理員；s：普通用戶）cortyp：用戶所屬公司的類型（g：集團企業(yè)；n：普通企業(yè)）cornam：用戶所屬公司名稱gr

44、pnam：用戶所屬集團公司（對普通企業(yè)，和cornam一致）icclgn：是否證書卡用戶（y：是；n：不是）iccnbr：證書卡卡號（對非證書卡用戶無效）outilength：系統(tǒng)信息數(shù)據(jù)長度。只有大于0時，szdata才有效。outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本范例：char *szdata = null;int ilength = 0;char szerrormsg256 = 0;getsysinfo(systyp=usrinf, &szdata, &ilength, szerrormsg); l

45、istmodeint _stdcalllistmode(const char *szquery, char *szdata, int *ilength, char *szerrormsg);public sdkresultlistmode(string squery);說明：查詢可經(jīng)辦的業(yè)務(wù)模式信息。參數(shù)：inszquery： squery：查詢條件。只有一條記錄（數(shù)據(jù)格式）由一個字段組成：buscod：業(yè)務(wù)代碼（非空，具體請參考招商銀行直連接口說明書中附錄a.4 業(yè)務(wù)代碼）outszdata：查詢業(yè)務(wù)模式結(jié)果數(shù)據(jù)的指針。緩沖區(qū)必須不小于64k，每個業(yè)務(wù)模式作為一條記錄（數(shù)據(jù)格式），由兩個字段

46、組成：busmod：業(yè)務(wù)模式編號modals：業(yè)務(wù)模式名稱outilength：業(yè)務(wù)模式結(jié)果數(shù)據(jù)長度。只有大于0時，szdata才有效。outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本范例：int ilength = 0;char szdata64*1024 = 0;char szerrormsg256 = 0;/ 查詢代發(fā)工資的可經(jīng)辦業(yè)務(wù)模式listmode(buscod=n03010, szdata, &ilength, szerrormsg); setaliveint _stdcallsetalive(c

47、har *szerrormsg);public sdkresultsetalive();說明：設(shè)置客戶端和銀行端保持連接。參數(shù)：outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本備注：1、的版本可以通過定時（如每隔10分鐘）調(diào)用該接口和銀行端保持連接，否則如果30分鐘內(nèi)沒有進行任何業(yè)務(wù)請求，將會自動退出登錄。2、、及以后的版本，系統(tǒng)內(nèi)部已經(jīng)實現(xiàn)了和銀行端一直保持連接，不會自動退出登錄。3、可用于測試和銀行端的連接是否正常（返回成功表示正常；其它情況表示不正常，需要重新登錄）。因此當(dāng)業(yè)務(wù)請

48、求失敗時，可以通過該方法判斷是否由于和銀行端連接出現(xiàn)異常。范例：int ilength = 0;char szdata64*1024 = 0;char szerrormsg256 = 0;int iret = getaccinfo(深圳, 1280095810099, szdata, &ilength, szerrormsg);if (0 != iret) iret = setalive(szerrormsg); / 業(yè)務(wù)請求失敗，判斷和銀行端連接是否異常 if (0 != iret) login(lgntyp=-1, 0, szerrormsg); / 和銀行端連接異常，重登錄 freebufferint _stdcallfreebuffer(const char *szbuf, char *szerrormsg);無java接口說明：用于釋放在本dll創(chuàng)建的數(shù)據(jù)緩沖區(qū)?？梢栽谖吹卿浀那闆r下調(diào)用參數(shù)：inszbuf：數(shù)據(jù)緩沖區(qū)指針。outszerrormsg：錯誤信息。緩沖區(qū)必須不小于256個字節(jié)。返回值：接口返回值要求：及之后版本備注：建議對于需要本dll創(chuàng)建的數(shù)據(jù)都先初始化為null，調(diào)用相關(guān)接口后，不論成