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

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

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