微簽電子簽名-SaaS互簽接口文檔v1.0.0

FORWAVE復園 微簽SaaSWebAPI接口說明 微簽SaaS互簽WebAPI接口說明forwave上海復園電子科技有限公司目錄TOC\o"1-2"\h\u24671.簡介 1279062.開發(fā)前準備 1177142.1.接口請求說明 1133562.2.請求簽名Sign生成方法 2177442.3.請求簽名鑒權(quán)示例代碼 3270333.API文檔 4245283.1.接口調(diào)用流程說明: 4218633.2.上傳簽章文件接口 4101443.3.微簽創(chuàng)建互簽任務(wù)接口 594513.4.發(fā)起人簽章接口或者公共簽章接口 7272283.5.下載文件 8221453.6.刪除文件 8162134.API返回碼 953704.1.常見HTTP狀態(tài)碼及處理方式 9235164.2.公共錯誤碼 918464.3.業(yè)務(wù)錯誤碼-鑒權(quán) 10160814.4.業(yè)務(wù)錯誤碼-用戶管理 10322504.5.業(yè)務(wù)錯誤碼-部門管理 1155734.6.業(yè)務(wù)錯誤碼-文件上傳 11309724.7.業(yè)務(wù)錯誤碼-審批任務(wù) 1241585.技術(shù)支持 12TOC\o"1-3"\h\uTOC\o"1-3"\h\uPAGE14

簡介微簽SaaSWebAPI互簽接口通過調(diào)用微簽SaaS云端接口實現(xiàn)。此接口適用于企業(yè)方與個人的線上簽署場景，如人事合同、確認單、旅游/教培/法律服務(wù)行業(yè)的合同協(xié)議等?；ズ灲涌诳梢耘cWeb、APP、小程序等業(yè)務(wù)系統(tǒng)或平臺對接。業(yè)務(wù)系統(tǒng)平臺準備好簽署的文件后，只需調(diào)用互簽接口，甲方雙方即可在線簽署同一份合同。開發(fā)前準備接口請求說明字符編碼均使用UTF-8編碼時間戳說明所有參數(shù)中使用的時間戳簽都使用“Unix標準時間戳”?！癠nix標準時間戳”是指從1970年1月1日(UTC/GMT的午夜)開始所經(jīng)過的毫秒數(shù)。請求方法如果無特殊說明，總是使用POST方法。POST請求支持的Content-Type類型：application/x-www-form-urlencodedmultipart/form-data(僅涉及文件流操作接口支持)公共請求參數(shù)參數(shù)名稱參數(shù)類型數(shù)據(jù)類型必選參數(shù)說明AppIdheaderstring是應(yīng)用AppIdTimestampheaderstring是API調(diào)用者傳遞時間戳，值為當前時間的毫秒數(shù)，也就是從1970年1月1日起至今的時間轉(zhuǎn)換為毫秒，時間戳有效時間為15分鐘，為了防重放攻擊。Signheaderstring是簽名字符串，具體生成方法見下面1.2節(jié)說明。AuthModeheaderstring是鑒權(quán)方式，固定值為SignatureDatabodystring是業(yè)務(wù)參數(shù)，所有業(yè)務(wù)參數(shù)都必須放在這個參數(shù)中傳遞(除文件流，字節(jié)流等)。內(nèi)部用json格式編碼。注:在具體的業(yè)務(wù)接口參數(shù)描述中，除非特殊說明，都是Data內(nèi)的參數(shù)。公共響應(yīng)參數(shù)參數(shù)名稱參數(shù)類型數(shù)據(jù)類型必選參數(shù)說明codebodystring是返回碼，10000表示成功，其余表示失敗。msgbodystring是返回碼描述信息。databodyobject否返回的業(yè)務(wù)數(shù)據(jù)，內(nèi)容為json格式。請求簽名Sign生成方法為保證API調(diào)用過程的安全可靠，微簽平臺webapi接口在調(diào)用前首先進行鑒權(quán)，采用對請求數(shù)據(jù)進行簽名的方式實現(xiàn)安全接入，防止請求過程數(shù)據(jù)被篡改或盜用。請求簽名鑒權(quán)前準備第三方請先向復園商務(wù)人員獲取APPID和APPSECRET。參數(shù)篩選并排序?qū)舱埱髤?shù)（不包括Sign字段），不包括字節(jié)流型參數(shù)(如文件流、字節(jié)流)，并按照參數(shù)鍵值A(chǔ)SCII碼遞增排序(字母升序排序)。參數(shù)拼接將上述篩選和排序后的參數(shù)與其對應(yīng)值，組合成“參數(shù)名=參數(shù)值(Key=Value)”的格式，并且把這些參數(shù)用&字符連接起來，此時生成的字符串為待簽名字符串。計算簽名使用APPSECRET對第三步拼接后的字符串采用HMAC-SHA256算法進行簽名運算，最后經(jīng)過Base64編碼從而得到簽名字符串。請求簽名鑒權(quán)示例代碼//AppId,AppSecret請聯(lián)系微簽商務(wù)人員獲取//AppSecret屬于機密信息，請勿泄露，妥善保管StringappId="100000";StringappSecret="ead6c5bceae14ea7a92090d1bb245ee2";//Unix標準時間戳Stringtimestamp=Long.toString(System.currentTimeMillis());//data參數(shù)中的json字符串，不包括字節(jié)流型參數(shù)，如文件流、字節(jié)流Stringdata="json字符串";Stringsign;//參與簽名計算的Key-Value列表Map<String,String>paramMap=newHashMap<>();paramMap.put("AppId",appId);paramMap.put("Timestamp",timestamp);paramMap.put("AuthMode","Signature");paramMap.put("Data",data);//排序后的參數(shù)字符串，WeiQianSignUtil為微簽提供的簽名工具類StringparamToSignStr=WeiQianSignUtil.sortParameters(paramMap);//計算之后得到簽名字符串，該簽名字符串需放到請求頭中的Sign字段sign=WeiQianSignUtil.doSignBase64(paramToSignStr,appSecret);paramMap.put("Sign",sign);API文檔接口調(diào)用流程說明:首先調(diào)用互簽文件上傳接口獲取文件的bId如果需要指定發(fā)起人和接收人的指定蓋章位置坐標，可調(diào)用接口3路徑，獲取蓋章位置，其位置參數(shù)需要添加到步驟3中。創(chuàng)建互簽的接口，傳遞相應(yīng)的參數(shù)，獲取返回參數(shù)。返回參數(shù)有兩種互簽發(fā)給一個人:則返回bId(互簽業(yè)務(wù)id)和shortCode(互簽短鏈碼)互簽發(fā)給多個人：則返回shortCode(互簽短鏈碼)childShortUrl(多人互簽相關(guān)數(shù)據(jù)，其中包含多個不同的bId)互簽發(fā)給一個人，則發(fā)起人可通過bId進行簽章，接收人通過shortCode進行簽章?；ズ灠l(fā)給多個人，發(fā)起人可通過返回多人互簽相關(guān)數(shù)據(jù)，其中包含多個bId.中的其中一個bId進行簽章，接收人通過shortCode進行簽章。發(fā)起人調(diào)用接口為eachSign/getSignPage進行簽章接收人調(diào)用接口為(接收人簽章接口和其他接口有些許不同)q/{shortCode}進行簽章如::8888/q/{shortCode}接收者簽章完成，根據(jù)配置可跳轉(zhuǎn)默認頁面或跳轉(zhuǎn)配置后的路徑。以下接口都有具體java的調(diào)用demo,具體demo可查看提供的demo程序。步驟3參數(shù)補充說明:簽章id可在PC端的系統(tǒng)管理的簽章管理里面查詢，公司id可在系統(tǒng)管理的應(yīng)用管理里面查詢接口前綴說明:測試環(huán)境的apiUrl為:8888/openapi/v1/正式環(huán)境的apiURL為:8887/openapi/v1/系統(tǒng)簡稱為微簽(其測試接口前綴為::8888/openapi/v1/)接口如下：序號方法名稱方法描述備注1eachSign/upload互簽文件上傳2eachSign/create創(chuàng)建互簽任務(wù)創(chuàng)建互簽任務(wù)3:8089/views/common/seal_position.html獲取指定發(fā)起人自動蓋章或者接收者固定位置蓋章路徑4eachSign/getSignPage發(fā)起人獲取互簽蓋章頁面。5eachSign/download下載簽章文件6eachSign/deleteFile刪除簽章文件上傳簽章文件接口接口描述：上傳互簽的簽章文件1.請求接口A. 上傳文件eachSign/upload2.上傳文件請求信息POST：RequestBody：{"file":"文件的數(shù)據(jù)流",}ResponseBody：{code:10000,msg:"返回消息varchar(200)",data:"響應(yīng)數(shù)據(jù),可能沒有值(文件的業(yè)務(wù)idbId)",timestamp:時間戳}參數(shù)名稱參數(shù)類型數(shù)據(jù)類型必選參數(shù)說明filebodybinary非空文件的二進制流2.關(guān)鍵數(shù)據(jù)類型微簽創(chuàng)建互簽任務(wù)接口接口描述：其他系統(tǒng)調(diào)用此接口后，將在微簽創(chuàng)建一個互簽任務(wù)，如果需要此任務(wù)，需要先調(diào)用上傳文件接口，再調(diào)用此接口。1.請求信息POST：RequestBody：{"launchAccount":"發(fā)起者賬號", "cId":"發(fā)起者公司ID", "fBIds":"發(fā)起者文件業(yè)務(wù)ID列表", "rType":"接收者類型1:個人2:公司", "authType":"授權(quán)類型1:手機驗證碼2:實名認證", "expiresTime":"互簽過期時間", "finishSignJumpPage":"接收者簽章完成跳轉(zhuǎn)頁面", "parm":"跳轉(zhuǎn)頁面攜帶的額外參數(shù)", "receiverDTOS":[{ "account":"接收者賬號","rName":"接收者名字", "idCard":"接收者身份證號", "rCName":"接收者公司名" }], "positionDTOS":[{ "x":"接收人指定位置x坐標", "y":"接收人指定位置y坐標", "pageNum":"接收人指定蓋章頁數(shù)" }], "launcherSignRule":[{ "autosealType":"自動蓋章類型1單頁蓋章、2多頁蓋章", "sealId":"發(fā)起者自動固定蓋章的章id", "x":"發(fā)起者自動蓋章的x坐標","y":"發(fā)起者自動蓋章的y坐標","autosealPage":"發(fā)起者自動蓋章頁數(shù)" }]}ResponseBody：{code:10000,msg:"返回消息varchar(200)",data:"響應(yīng)數(shù)據(jù),可能沒有值",timestamp:時間戳}2.關(guān)鍵數(shù)據(jù)類型參數(shù)名稱參數(shù)類型數(shù)據(jù)類型必選參數(shù)說明launchAccountbodyvarchar(50)非空發(fā)起者賬號cIdbodybigint非空發(fā)起者公司IDfBIdsbodyRecipient[]非空發(fā)起者文件業(yè)務(wù)ID列表∟fBIdbodyvarchar(50)非空上傳文件接口返回值fBIdfileNamebodyvarchar(50)非空文件名rTypebodytinyint(1)非空接收者類型1:個人2:公司authTypebodytinyint(1)非空授權(quán)類型1:手機驗證碼2:實名認證isSendSmsToReceiverbodyBoolean可空互簽鏈接是否發(fā)送短信給接收人,默認不通過短信發(fā)送expiresTimebodybigint可空互簽過期時間長度13位數(shù)的時間戳finishSignJumpPagebodyvarchar(100)可空接收者簽章完成跳轉(zhuǎn)頁面parmbodyvarchar(20)可空跳轉(zhuǎn)頁面攜帶的額外參數(shù)receiverDTOSbodyRecipient[]非空接收人列表∟accountbodyvarchar(20)非空接收者賬號∟idCardbodyvarchar(10)可空接收者身份證號∟rCNamebodyvarchar(20)可空接收者公司名∟rNamebodyvarchar(20)可空接收者名字positionDTOSbodyRecipient[]可空位置列表∟xbodyInt非空接收人指定位置x坐標(0-1000)∟ybodyInt非空接收人指定位置y坐標(0-1000)∟pageNumbodyInt非空接收人指定蓋章頁數(shù)launcherSignRulebodyRecipient[]可空發(fā)起人蓋章位置列表∟autosealTypebodytinyint(1)非空自動蓋章類型1單頁蓋章、2多頁蓋章、3首次關(guān)鍵字蓋章∟sealIdbodybigint非空用戶發(fā)起者自動固定蓋章的章id號∟xbodyInt非空用戶發(fā)起者自動蓋章的x坐標號(0-1000)∟ybodyInt非空發(fā)起者自動蓋章的y坐標(0-1000)∟autosealPagebodyInt非空發(fā)起者自動蓋章頁數(shù)發(fā)起人簽章接口或者公共簽章接口接口描述：其他系統(tǒng)調(diào)用此接口后，將返回一個互簽鏈接，手機打開此鏈接后可正常簽署。1.請求信息POST：RequestBody：{"signType":"簽署類型basicFileType,eachSignType", "fBId":"發(fā)起者文件業(yè)務(wù)ID", "bBId":"互簽的業(yè)務(wù)ID", "account":"簽署人賬號", "password":"簽署人密碼"}ResponseBody：{code:10000,msg:"返回消息varchar(200)",data:"響應(yīng)數(shù)據(jù),可能沒有值",timestamp:時間戳}2.關(guān)鍵數(shù)據(jù)類型參數(shù)名稱參數(shù)類型數(shù)據(jù)類型必選參數(shù)說明signTypebodyvarchar(50)非空簽署類型basicFileType:簽署普通文件,eachSignType：簽署互簽文件fBIdbodyvarchar(50)可空發(fā)起者文件業(yè)務(wù)ID：簽署類型為basicFileTypebBIdbodyvarchar(50)可空互簽的業(yè)務(wù)ID：此時簽署類型為eachSignTypeaccountbodyvarchar(20)非空簽署人賬號passwordbodyvarchar(20)非空簽署人密碼下載文件接口描述：其他系統(tǒng)調(diào)用此接口后，可獲取互簽的文件字節(jié)流1.請求信息POST：RequestBody：{ "bId":"互簽的業(yè)務(wù)ID"}ResponseBody：{code:10000,msg:"返回消息varchar(200)",data:"響應(yīng)數(shù)據(jù),可能沒有值",timestamp:時間戳}2.關(guān)鍵數(shù)據(jù)類型參數(shù)名稱參數(shù)類型數(shù)據(jù)類型必選參數(shù)說明bIdbodyvarchar(50)可空互簽的業(yè)務(wù)ID：此時簽署類型為eachSignType刪除文件接口描述：其他系統(tǒng)調(diào)用此接口后，將刪除互簽文件1.請求信息POST：RequestBody：{ "bId":"互簽的業(yè)務(wù)ID"}ResponseBody：{code:10000,msg:"返回消息varchar(200)",data:"響應(yīng)數(shù)據(jù),可能沒有值",timestamp:時間戳}2.關(guān)鍵數(shù)據(jù)類型參數(shù)名稱參數(shù)類型數(shù)據(jù)類型必選參數(shù)說明bIdbodyvarchar(50)可空互簽的業(yè)務(wù)IDAPI返回碼常見HTTP狀態(tài)碼及處理方式HTTP狀態(tài)碼狀態(tài)碼描述建議處理方式200處理成功/401未授權(quán)Unauthorized/403異常得請求，或者請求過于頻繁請檢查請求參數(shù)，或者檢查請求是否過于頻繁404請求的資源不存在請檢查請求的URL是否正確500系統(tǒng)錯誤按具體接口的錯誤指引進行重試502服務(wù)下線，暫時不可用請求無法處理，請稍后重試503服務(wù)不可用，過載保護請求無法處理，請稍后重試公共錯誤碼錯誤碼描述解決方案10000請求成功10001系統(tǒng)異常，請稍后重試。請稍后重試，若重試后仍然無法解決請聯(lián)系微簽技術(shù)支持。10002簽名錯誤請檢查簽名是否正確10003請求頻繁，請稍后再試請求過于頻繁，超過最大限制。10004請求長度超過限制請檢查相應(yīng)參數(shù)是否超出限制。100