票據(jù)信息披露平臺(tái)專線查詢接口接入手冊(cè)

票據(jù)信息披露平臺(tái)專線查詢接口接入手冊(cè)上海票據(jù)交易所版本：V1.2.0修改時(shí)間：2021/09/13

版本記錄版本編號(hào)版本日期作者說明目錄TOC\o"1-3"\h\u7443開始前必讀 429757概述 419567開發(fā)者規(guī)范 425337業(yè)務(wù)產(chǎn)品權(quán)限說明 522893全局應(yīng)答碼說明 516777接入注意事項(xiàng) 531166開始開發(fā) 518102接入指南 526999專線查詢接口概覽 625833功能接口調(diào)用 71376接口說明 1129129常見問題 1328823附件 14開始前必讀概述上海票據(jù)交易所票據(jù)信息披露平臺(tái)專線查詢接口對(duì)外提供統(tǒng)一規(guī)范業(yè)務(wù)產(chǎn)品接口，為接入機(jī)構(gòu)提供統(tǒng)一標(biāo)準(zhǔn)、統(tǒng)一流程的專線查詢接口調(diào)用服務(wù)。接入機(jī)構(gòu)在信息披露平臺(tái)創(chuàng)建賬號(hào)信息、獲取產(chǎn)品專線查詢接口調(diào)用權(quán)限后，可以通過閱讀本技術(shù)文檔來幫助開發(fā)，將其內(nèi)部系統(tǒng)與信息披露平臺(tái)直連，在內(nèi)部系統(tǒng)中調(diào)用本系統(tǒng)開放的專線查詢接口。請(qǐng)接入機(jī)構(gòu)注意：1、在接入信息披露互聯(lián)網(wǎng)專線查詢接口接口前，需要在信息披露平臺(tái)注冊(cè)，配置訪問白名單。機(jī)構(gòu)可以在本系統(tǒng)申請(qǐng)標(biāo)識(shí)用戶身份的SecretId企業(yè)編號(hào),SecretKey密鑰，它們是訪問本系統(tǒng)的安全憑證，注意保密，切勿泄漏。2、每個(gè)服務(wù)接口調(diào)用頻率有限制且可能不同，機(jī)構(gòu)調(diào)用頻率高時(shí)會(huì)被暫時(shí)封禁IP，請(qǐng)嚴(yán)格按照調(diào)用頻率要求接入。3、在開發(fā)出現(xiàn)問題時(shí)，可以通過接口調(diào)用的返回碼，以及報(bào)警排查指引，來發(fā)現(xiàn)和解決問題；開發(fā)者規(guī)范機(jī)構(gòu)進(jìn)行接入專線查詢接口開發(fā)時(shí)，除了需要滿足每個(gè)接口的規(guī)范限制、調(diào)用頻率限制外，還需特別注意以下使用規(guī)范：涉及用戶敏感數(shù)據(jù)時(shí)：您收集用戶的數(shù)據(jù)后，必須采取必要的保護(hù)措施，防止用戶數(shù)據(jù)被盜、泄漏等。如果票交所認(rèn)為您收集、使用用戶數(shù)據(jù)的方式，可能損害用戶體驗(yàn)，票交所有權(quán)要求您刪除相關(guān)數(shù)據(jù)并不得再以該方式收集、使用用戶數(shù)據(jù)。一旦您停止使用本服務(wù)，或票交所基于任何原因終止您使用本服務(wù)，您必須立即刪除全部因使用本服務(wù)而獲得的數(shù)據(jù)（包括各種備份），且不得再以任何方式進(jìn)行使用。其他規(guī)范：請(qǐng)勿為任何機(jī)構(gòu)自動(dòng)登錄到信息披露平臺(tái)提供代理身份驗(yàn)證憑據(jù)。業(yè)務(wù)產(chǎn)品權(quán)限說明專線查詢接口調(diào)用權(quán)限說明1、機(jī)構(gòu)通過在票交所票據(jù)信息披露平臺(tái)以財(cái)務(wù)公司、銀行或其他金融機(jī)構(gòu)類型用戶注冊(cè)成功后即獲得相關(guān)接入權(quán)限；2、企業(yè)類型用戶沒有接入專線查詢接口接口的權(quán)限；全局應(yīng)答碼說明狀態(tài)碼狀態(tài)碼描述9901您的IP沒有登記，請(qǐng)?jiān)谛畔⑴镀脚_(tái)進(jìn)行白名單登記9902您的訪問太頻繁，請(qǐng)稍后操作9903SecretId（企業(yè)編號(hào)）或SecretKey（密鑰）驗(yàn)證失敗9904請(qǐng)求參數(shù)值有誤，請(qǐng)確認(rèn)請(qǐng)求參數(shù)信息9905您的報(bào)文格式有誤，要求報(bào)文符合JSON數(shù)據(jù)格式9906你的報(bào)文數(shù)據(jù)有誤，未通過數(shù)據(jù)信息校驗(yàn)9907批量查詢最多同時(shí)支持查詢500條票據(jù)信息9908系統(tǒng)內(nèi)部未知錯(cuò)誤9909簽名驗(yàn)證失敗9910無效票據(jù)號(hào)碼接入注意事項(xiàng)序號(hào)產(chǎn)品名稱建議用戶超時(shí)時(shí)間流量控制請(qǐng)求頻率1承兌信息查詢21s無1秒/次2承兌信息批量查詢21s無10秒/次開始開發(fā)接入指南首先機(jī)構(gòu)在票據(jù)信息披露平臺(tái)創(chuàng)建賬號(hào)后，系統(tǒng)將為機(jī)構(gòu)自動(dòng)分配標(biāo)識(shí)機(jī)構(gòu)身份的SecretId企業(yè)編號(hào),SecretKey密鑰，然后機(jī)構(gòu)在票據(jù)信息披露平臺(tái)的用戶管理模塊中配置IP白名單（可多個(gè)）信息，重置SecretKey?！窘尤胄畔⒉榭础俊綢P白名單配置】然后在設(shè)置完成后，機(jī)構(gòu)根據(jù)本手冊(cè)，調(diào)用票據(jù)信息披露平臺(tái)提供的專線查詢接口。專線查詢接口概覽票據(jù)信息披露平臺(tái)向注冊(cè)機(jī)構(gòu)提供統(tǒng)一的專線查詢接口接口，機(jī)構(gòu)可以直接通過專線查詢接口接口，將其內(nèi)部系統(tǒng)與信息披露平臺(tái)直連。票交所票據(jù)信息披露平臺(tái)信息：生產(chǎn)環(huán)境：測(cè)試環(huán)境：接入方式見附件《上海票據(jù)交易所接入測(cè)試及接入驗(yàn)收環(huán)境系統(tǒng)參與者VPN接入流程.docx》相關(guān)服務(wù)接口接口代碼接口功能接口地址0A001單張票查詢承兌信息/api/findAcptInfo0A002多張票查詢承兌信息/api/findBatchAcptInfo功能接口調(diào)用請(qǐng)求參數(shù)請(qǐng)求參數(shù)是用于標(biāo)識(shí)結(jié)構(gòu)和接口簽名的參數(shù)，如非必要，在每個(gè)接口單獨(dú)的接口文檔中不再對(duì)這些參數(shù)進(jìn)行說明，但每次請(qǐng)求均需要攜帶這些參數(shù)，才能正常發(fā)起請(qǐng)求。參數(shù)類型必選描述secretIdString是信息披露平臺(tái)

上分配的標(biāo)識(shí)身份的secretId（企業(yè)編號(hào)）timestampInteger是當(dāng)前UNIX時(shí)間戳，可記錄發(fā)起專線查詢接口請(qǐng)求的時(shí)間dataString是查詢的參數(shù)信息(JSON字符串)signatureString是請(qǐng)求簽名，用來驗(yàn)證此次請(qǐng)求的合法性，需要機(jī)構(gòu)根據(jù)實(shí)際的輸入?yún)?shù)計(jì)算得出。具體計(jì)算方法參見下面的簽名方法以查詢承兌信息為例，其請(qǐng)求結(jié)構(gòu)按照請(qǐng)求URL、請(qǐng)求頭部、請(qǐng)求體示例如下：/api/findAcptInfoHost:Content-Type:application/json;charset=UTF-8請(qǐng)求體示例：{"data":”{"billNo":"77770000********00000000000002"}”,"secretId":'AKID********EXAMPLE',"signature":'37ac2f4fde00b0ac9bd9****e224158d66e7ae5fcadb70b2d181d02'，"timestamp":1527672334}簽名方法信息披露專線查詢接口會(huì)對(duì)每個(gè)訪問請(qǐng)求進(jìn)行身份驗(yàn)證，即每個(gè)請(qǐng)求都需要在公共請(qǐng)求參數(shù)中包含簽名信息（signature）以驗(yàn)證請(qǐng)求合法性。生成簽名串：假設(shè)用戶的SecretId和SecretKey是：SecretId:

AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******SecretKey:

Gu5t9xGARNpq86cd98joQYCN3*******以查詢承兌信息請(qǐng)求為例，當(dāng)開發(fā)者調(diào)用這一接口時(shí)，其請(qǐng)求參數(shù)可能如下:參數(shù)類型必選描述secretIdString是在

平臺(tái)

上申請(qǐng)的標(biāo)識(shí)身份的SecretId(企業(yè)編號(hào))timestampInteger是當(dāng)前UNIX時(shí)間戳，可記錄發(fā)起API請(qǐng)求的時(shí)間dataString是查詢的參數(shù)信息(JSON字符串)signatureString是請(qǐng)求簽名，用來驗(yàn)證此次請(qǐng)求的合法性，需要用戶根據(jù)實(shí)際的輸入?yún)?shù)計(jì)算得出。具體計(jì)算方法參見下面的簽名生成方法1、對(duì)參數(shù)排序首先對(duì)上述請(qǐng)求參數(shù)(除signature參數(shù))和secretKey密鑰參數(shù)按照參數(shù)名的字典序（ASCII碼）升序排序。注意：1）只按參數(shù)名進(jìn)行排序，參數(shù)值保持對(duì)應(yīng)即可，不參與比大?。?）按ASCII碼比大小，如InstanceIds.2要排在InstanceIds.12后面，不是按字母表，也不是按數(shù)值。用戶可以借助編程語(yǔ)言中的相關(guān)排序函數(shù)來實(shí)現(xiàn)這一功能，如PHP中的ksort函數(shù)。上述示例參數(shù)的排序結(jié)果如下：{"data":”{"billNo":"77770000********00000000000002"}”,"secretId":'AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******',“secretKey”:

’Gu5t9xGARNpq86cd98joQYCN3*******’,"timestamp":1527672334}2、拼接待簽名字符串，參數(shù)之間使用|分隔Stringsign=”{"billNo":"77770000********00000000000002"}”+”|”+“'AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******”+”|”+”Gu5t9xGARNpq86cd98joQYCN3*******”+”|”+”1527672334”3、計(jì)算簽名：使用國(guó)密SM3生成簽名Stringsignature=SmUtil.sm3(sign);返回結(jié)果正確返回結(jié)果以調(diào)用承兌信息查詢接口為例，若調(diào)用成功，其返回值示例如下為：{"code":

200,"success":

true,"data":

{timestamp：時(shí)間戳signature：簽名secretId：企業(yè)編號(hào)data：查詢數(shù)據(jù)},"message":

"操作成功！"}錯(cuò)誤返回結(jié)果以調(diào)用承兌信息查詢接口為例，若調(diào)用失敗，其返回值示例如下為：{

"code":

9904,

"success":

false,

"data":

null,

"message":

"無效票據(jù)號(hào)碼！"}字段說明：code:返回信息的狀態(tài)碼succes:用于判斷接口是否成功調(diào)用data:成功調(diào)用系統(tǒng)返回的數(shù)據(jù)message:狀態(tài)碼說明信息驗(yàn)簽返回的data對(duì)象數(shù)據(jù)類型參數(shù)類型必選描述secretIdString是在

平臺(tái)

上申請(qǐng)的標(biāo)識(shí)身份的SecretIdtimestampInteger是當(dāng)前UNIX時(shí)間戳，可記錄請(qǐng)求返回?cái)?shù)據(jù)的時(shí)間dataString是查詢結(jié)果(JSON字符串)signatureString是響應(yīng)簽名，用來驗(yàn)證此次響應(yīng)的合法性，使用返回data對(duì)象中的數(shù)據(jù)，按照上面生成簽名的方式進(jìn)行驗(yàn)簽。公共錯(cuò)誤碼完整的錯(cuò)誤碼列表請(qǐng)參考本產(chǎn)品“專線查詢接口文檔”目錄下的“全局應(yīng)答碼說明”頁(yè)面。接口說明承兌信息查詢接口的描述請(qǐng)求接口：/api/findAcptInfo請(qǐng)求方式：post功能：此接口用于查詢承兌信息默認(rèn)接口請(qǐng)求頻率限制：1秒/次輸入?yún)?shù)名稱類型描述billNoString票據(jù)號(hào)碼輸出參數(shù)名稱類型描述batchAcptInfoVoListArrayList<BatchAcptInfoVo>承兌信息，見數(shù)據(jù)結(jié)構(gòu)數(shù)據(jù)結(jié)構(gòu)BatchAcptInfoVo名稱類型描述remarkString系統(tǒng)備注acptNameString承兌人名稱dimAcptBranchNameString承兌人開戶行名稱billNoString票據(jù)(包)號(hào)碼dimAcptDayLocalDate承兌日期dimIssueDayLocalDate出票日期issueNameString出票人名稱expirDayLocalDate票價(jià)到期日billAmountBigDecimal票面金額(元)showDateLocalDate披露日期mediaTypeString票據(jù)介質(zhì)ME01紙票ME02電票soccodeString統(tǒng)一社會(huì)信用代碼remarkCodeInteger比對(duì)結(jié)果代碼0其他(異常數(shù)據(jù)時(shí)出現(xiàn))1披露信息與系統(tǒng)信息相符2披露信息與系統(tǒng)信息不符3暫未比對(duì)承兌信息批量查詢接口的描述請(qǐng)求接口：/api/findBatchAcptInfo請(qǐng)求方式：post功能：此接口用于查詢承兌信息，最多一次支持查詢500條票據(jù)的承兌信息默認(rèn)接口請(qǐng)求頻率限制：10秒/次輸入?yún)?shù)名稱類型描述billNoArrayList<String>票據(jù)號(hào)碼輸出參數(shù)名稱類型描述batchAcptInfoVoListArrayList<BatchAcptInfoVo>承兌信息，見數(shù)據(jù)結(jié)構(gòu)數(shù)據(jù)結(jié)構(gòu)BatchAcptInfoVo名稱類型描述remarkString系統(tǒng)備注acptNameString承兌人名稱dimAcptBranchNameString承兌人開戶行名稱billNoString票據(jù)(包)號(hào)碼dimAcptDayLocalDate承兌日期dimIssueDayLocalDate出票日期issueNameString出票人名稱expirDayLocalDate票價(jià)到期日billAmountBigDecimal票面金額(元)showDateLocalDate披露日期mediaTypeString票據(jù)介質(zhì)ME01紙票ME02電票soccodeString統(tǒng)一社會(huì)信用代碼remarkCodeInteger比對(duì)結(jié)果代碼0其他(異常數(shù)據(jù)時(shí)出現(xiàn))1披露信息與系統(tǒng)信息相符2披露信息與系統(tǒng)信息不符3暫未比對(duì)常見問題1：機(jī)構(gòu)申請(qǐng)的SecretId和SecretKey泄漏怎么辦？答：SecretId和SecretKey是訪問本系統(tǒng)的安全憑證，泄漏會(huì)對(duì)訪問造成安全問題，如果發(fā)現(xiàn)泄漏須立即處理，在票據(jù)信息披