當(dāng)前位置：首頁 > 编程资源 > 综合教程 >内容正文

综合教程

PHP e签宝电子签名Saas API 对接流程

發(fā)布時(shí)間：2023/12/4 综合教程 86 生活家

生活随笔收集整理的這篇文章主要介紹了 PHP e签宝电子签名Saas API 对接流程小編覺得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

一、流程
二、我們再熟悉下接口中這幾個(gè)字段的意思
- 1、accountId
- 2、orgId
- 3、fileId
- 4、templateId
- 5、flowId
- 6、回調(diào)通知接收說明
三、Demo文檔
- 1、官網(wǎng)提供的官網(wǎng)文檔
- 2、Demo下載
- 3、Demo中的調(diào)用Demo
- 4、根據(jù)Demo自己封裝簽署方法
- 5、sdk使用
四、最簡單的接口調(diào)用順序
五、需要注意的點(diǎn)
- 1、創(chuàng)建個(gè)人簽署賬號接口，證件包含小寫的 x
- 2、文件上傳接口，文件名格式
- 3、業(yè)務(wù)碼字段并不都是 code，也可能是 errCode
- 4、方法不存在
- 5、簽署章子位置的設(shè)置
- 6、接口請求統(tǒng)一處理，封裝一個(gè)方法統(tǒng)一請求
六、寫在最后

一、流程

寫在前面：希望大家通過這篇文章，對e簽寶電子簽名有一個(gè)比較全面的認(rèn)識，不至于拿到API文檔就蒙圈了，開發(fā)語言這里以 PHP為例，其他語言的可以在 Demo 鏈接中去下載。接口封裝沒問題，官方已經(jīng)給了sdk，就是需要捋一下流程。

大致的流程：把合同上傳到e簽寶，e簽寶會返回給我們 fileId，用戶或者企業(yè)簽名或者蓋章（簽名蓋章的位置可以設(shè)置：頁碼；x軸坐標(biāo)，左下角為原點(diǎn)；y軸坐標(biāo)，左下角為原點(diǎn)），會生成一個(gè)簽名的地址，用戶/企業(yè)打開就能夠簽名，里面有拒簽操作。用戶觸發(fā)了不同的狀態(tài)就會有不同的回調(diào) action。

開發(fā)前必讀

環(huán)境	域名	公網(wǎng)IP	端口
正式生產(chǎn)環(huán)境	https://openapi.esign.cn	118.31.181.75	443
沙箱模擬環(huán)境	https://smlopenapi.esign.cn	114.55.17.44	443

e簽寶.文檔中心-公有云文檔-電子簽名SaaS API標(biāo)準(zhǔn)版-電子簽名 SaaS API 標(biāo)準(zhǔn)版產(chǎn)品介紹
e簽寶.文檔中心-公有云文檔-電子簽名SaaS API標(biāo)準(zhǔn)版-接口交互時(shí)序圖

二、我們再熟悉下接口中這幾個(gè)字段的意思

1、accountId

個(gè)人賬號id，合同簽署的時(shí)候可以選擇你的名字的這個(gè)簽名或者自己手動寫。

2、orgId

機(jī)構(gòu)賬號id，合同簽署的時(shí)候簽名要用到。

3、fileId

文件ID，用于簽署的PDF文件
來源：可以自己直接上傳，根據(jù)文件的后綴判斷是否需要轉(zhuǎn)pdf文件，再上傳，注意接口的這2個(gè)參數(shù)：contentType，convert2Pdf。e簽寶.文檔中心-公有云文檔-電子簽名SaaS API標(biāo)準(zhǔn)版-API文檔-文件上傳
也可以自己生成模板文件之后再上傳。PDF模板文件3種制作說明文檔
查詢文件上傳狀態(tài)：查看所上傳文件的當(dāng)前狀態(tài)，本接口支持輪詢。當(dāng)接口返回的文件狀態(tài) status 值為 2 或 5 時(shí)，此文件才可以被正常添加到簽署流程中。
查詢PDF文件詳情：查看所上傳文件的當(dāng)前狀態(tài)、文件名稱、文件大小和下載鏈接，本接口不支持輪詢。當(dāng)接口返回的文件狀態(tài) status 值為 2 或 5 時(shí)，此文件才可以被正常添加到簽署流程中或下載PDF文件。

4、templateId

模板ID，可執(zhí)行添加控件、刪除控件操作，模板內(nèi)容確定后可調(diào) 填充內(nèi)容生成PDF 接口生成合同文件。

5、flowId

流程id，發(fā)起一個(gè)簽署流程生成的id
可根據(jù)該id 查詢流程的進(jìn)度簽署流程查詢，查詢流程簽署人列表
流程結(jié)束后執(zhí)行流程文檔下載，生成了最終的流程數(shù)據(jù)。

6、回調(diào)通知接收說明

還有我們最關(guān)心的，流程回調(diào) 回調(diào)通知接收說明，回調(diào)地址在一步發(fā)起簽署接口中的 flowConfigInfo[‘noticeDeveloperUrl’]
響應(yīng)e簽寶回調(diào)通知：當(dāng)收到e簽寶的回調(diào)通知后，開發(fā)者返回介于200~299的HTTP狀態(tài)碼給e簽寶，e簽寶均認(rèn)為推送成功。建議返回給e簽寶的響應(yīng)Body數(shù)據(jù)格式如下：{"code":"200","msg":"success"}
我們根據(jù)回調(diào)路徑中的 action參數(shù)來判斷事件類型，如下：

Action事件類型	Action事件名稱（點(diǎn)擊查看具體描述）對應(yīng)的業(yè)務(wù)操作（點(diǎn)擊查看具體描述）
SIGN_FLOW_UPDATE	簽署人簽署完成
SIGN_FLOW_FINISH	流程結(jié)束
SIGN_DOC_EXPIRE_REMIND	流程文件過期前提醒
SIGN_DOC_EXPIRE	流程文件過期
BATCH _ ADD _ WATERMARK _ REMIND	文件添加數(shù)字水印完成
FEEDBACK_SIGNERINFO	簽署人申請修改身份信息
PROCESS_HANDOVER	經(jīng)辦人轉(zhuǎn)交簽署任務(wù)
WILL_FINISH	意愿認(rèn)證完成
PARTICIPANT_MARKREAD	簽署人已讀
FILE_ABNORMAL_REMIND	文件已加密/已損壞通知

php回調(diào)中接收參數(shù)并響應(yīng)Demo

    //數(shù)據(jù)回調(diào)業(yè)務(wù)處理public function callback() {
//        $data = '{"action":"SIGN_FLOW_UPDATE","flowId":"11111113a466442abbce094c9368ac7c","accountId":"22XXXe2a","authorizedAccountId":"33XXXe3a","signTime":"2019-07-24 19:33:06","order":1,"signResult":2,"thirdOrderNo":"cust0001","resultDescription":"簽署完成","timestamp":1563967986960,"thirdPartyUserId":"A34006"}';$data = file_get_contents('php://input'); // php://input 是個(gè)可以訪問請求的原始數(shù)據(jù)的只讀流。當(dāng)請求方式是post，并且Content-Type不等于”multipart/form-data”時(shí)，可以使用php://input來獲取原始請求的數(shù)據(jù)。return self::callbackService($data);}/*** 務(wù)處理：實(shí)際使用中把該函數(shù)放到service中* @param $data* @return array 結(jié)果數(shù)組*/public function callbackService($data){$result = false;$data = json_decode($data, true);$action = isset($data['action']) ? $data['action'] : ''; //標(biāo)記該通知的業(yè)務(wù)類型if ($action) {switch ($action) {case 'SIGN_DOC_EXPIRE': //流程文件過期 回調(diào)通知$flowId = $data['flowId']; //流程id$fileId = $data['fileId']; //文件ID,多文檔已逗號分隔$timestamp = $data['timestamp']; //時(shí)間戳/*** TODO 在這里處理我們的業(yè)務(wù)，操作我們的數(shù)據(jù)表，視情況是否加上數(shù)據(jù)表回滾操作*/$result = true;break;case 'SIGN_FLOW_UPDATE': //簽署人簽署完成回調(diào)通知$result = true;break;case "SIGN_FLOW_FINISH": //簽署流程結(jié)束 回調(diào)通知$flowId = $data['flowId']; //流程ID$flowStatus = $data['flowStatus']; //流程狀態(tài)： 2 - 已完成: 所有簽署人完成簽署；3 - 已撤銷: 發(fā)起方撤銷簽署任務(wù)；5 - 已過期: 簽署截止日到期后觸發(fā)；7 - 已拒簽。/*** 在我們的數(shù)據(jù)表處理該邏輯，改變我們數(shù)據(jù)表的狀態(tài)，備注，更新時(shí)間 等字段~* TODO 業(yè)務(wù)... 在這里處理我們的業(yè)務(wù)，操作我們的數(shù)據(jù)表，視情況是否加上數(shù)據(jù)表回滾操作*/$result = true;break;}}//開發(fā)者返回介于200~299的HTTP狀態(tài)碼給e簽寶，e簽寶均認(rèn)為推送成功。//建議返回給e簽寶的響應(yīng)Body數(shù)據(jù)格式如下：{"code":"200","msg":"success"}if ($result) {$ret = ['code' => '200',  'msg' => 'success'];} else {$ret = ['code' => '0', 'msg' => 'error'];}return json_encode($ret, JSON_UNESCAPED_UNICODE); //數(shù)組轉(zhuǎn)json字符串}

三、Demo文檔

1、官網(wǎng)提供的官網(wǎng)文檔

Demo下載
Demo下載-請點(diǎn)擊進(jìn)入此鏈接后按需下載。

2、Demo下載

我選擇 PHP語言DEMO - 請求簽名鑒權(quán)方式 81KB 下載
我下載后放到了百度網(wǎng)盤，有需要的可前往下載鏈接：https://pan.baidu.com/s/1i42ruPO4wR9MJmf7DUrV2g 提取碼：ty79

3、Demo中的調(diào)用Demo

b2cDemo.php 文件詳情

<?phpuse factory\base\Account;
use factory\base\FileTemplate;
use factory\base\Seals;
use factory\base\SignFile;
use factory\bean\Doc;
use factory\bean\FlowInfo;
use factory\bean\PosBean;
use factory\bean\Signer;
use factory\bean\SignerAccount;
use factory\bean\Signfield;
use factory\Factory;header("Content-type:text/html;charset=utf-8");
include("../eSignOpenAPI.php");
//此示例為企業(yè)和個(gè)人場景的簽署示例代碼，簽署方式為一步發(fā)起簽署，如果需要分步簽署，簽署部分代碼示例可參考b2bDemo
var_dump("--------------------------初始化 start----------------------------");
$host="https://smlopenapi.esign.cn";//請求網(wǎng)關(guān)host
$project_id="";//應(yīng)用id
$project_scert="";//密鑰
Factory::init($host,$project_id,$project_scert);
Factory::setDebug(true);//是否開啟日志記錄，傳true或false,日志存放在根目錄的phplog.txt文件
//-----------------基礎(chǔ)信息初始化 end--------------------------
var_dump("--------------------------初始化 end----------------------------");$filePath="D:\\IDEAproject\\PdfFile\\dstPdf\\qianshu.pdf";//文件地址if(!is_file($filePath)){echo '文件不存在';exit;}//-----------------------個(gè)人賬號信息用于創(chuàng)建個(gè)人賬號接口傳入-----------------------------$thirdPartyUserIdPsn="1232133232";//thirdPartyUserId參數(shù)，用戶唯一標(biāo)識，自定義保持唯一即可$namePsn="";//name參數(shù)，姓名$idTypePsn="CRED_PSN_CH_IDCARD";//idType參數(shù)，證件類型$idNumberPsn="";//idNumber參數(shù)，證件號$mobilePsn="";//mobile參數(shù)，手機(jī)號//------------------------企業(yè)賬號信息用于創(chuàng)建機(jī)構(gòu)賬號接口傳入----------------$thirdPartyUserIdOrg="1212312312312";//thirdPartyUserId參數(shù)，用戶唯一標(biāo)識，自定義保持唯一即可$nameOrg="杭州天谷";//name參數(shù)，機(jī)構(gòu)名稱$idTypeOrg="CRED_ORG_USCC";//idType參數(shù)，證件類型$idNumberOrg="";//idNumber參數(shù),機(jī)構(gòu)證件號var_dump("------------------ 創(chuàng)建個(gè)人賬號 start -----------------");
$createPsn = Account::createPersonByThirdPartyUserId($thirdPartyUserIdPsn,$namePsn,$idTypePsn,$idNumberPsn);
$createPsn->setMobile($mobilePsn);
$createPsnResp = $createPsn->execute();//execute方法發(fā)起請求
$createPsnJson = json_decode($createPsnResp->getBody());
$accountId = $createPsnJson->data->accountId;//生成的個(gè)人賬號保存好，后續(xù)接口調(diào)用需要使用
var_dump("------------------ 創(chuàng)建個(gè)人賬號 end ---------------");var_dump("------------------ 創(chuàng)建企業(yè)賬號 start ---------------");
$createOrg = Account::createOrganizationsByThirdPartyUserId($thirdPartyUserIdOrg,$accountId,$nameOrg,$idTypeOrg,$idNumberOrg
);
$createOrgResp = $createOrg->execute();
$createOrgJson=json_decode($createOrgResp->getBody());
$orgId=$createOrgJson->data->orgId;
var_dump("------------------ 創(chuàng)建企業(yè)賬號 end ---------------");var_dump("------------------ 通過上傳方式創(chuàng)建文件 start -----------------");
$contentBase64Md5 = UtilHelper::getContentBase64Md5($filePath);
$filesize = filesize($filePath);
$fileContent = file_get_contents($filePath);
$getFileUploadUrl = FileTemplate::getFileUploadUrl($contentBase64Md5, "application/pdf", false, "測試合同.pdf", $filesize);
$getFileUploadUrlResp = $getFileUploadUrl->execute();
$getFileUploadUrlJson = json_decode($getFileUploadUrlResp->getBody());
$fileId = $getFileUploadUrlJson->data->fileId;//文件id保存好，后續(xù)使用
$uploadUrl = $getFileUploadUrlJson->data->uploadUrl;//上傳url保存好，后續(xù)使用
var_dump("------------------ 通過上傳方式創(chuàng)建文件 end -----------------");var_dump("------------------ 文件流上傳方法 start -----------------");
$uploadFile = FileTemplate::uploadFile($filePath, "application/pdf", $uploadUrl);
$uploadFileResp = $uploadFile->execute();
var_dump($uploadFileResp->getBody());
var_dump("------------------ 文件流上傳方法 end -----------------");var_dump("------------------ 一步發(fā)起簽署 start -----------------");
$doc = new Doc();
$doc->setFileId($fileId);
$docs = array($doc);
$flowInfo = new FlowInfo();
$flowInfo->setBusinessScene("b2c合同簽署測試")->setAutoArchive(true)//自動歸檔->setAutoInitiate(true);//自動開啟流程
$psnSignfield = new Signfield();
$posBean = new PosBean();
$psnSignfield->setFileId($fileId)->setPosBean($posBean->setPosPage(1)->setPosX(113)->setPosY(225));
$psnSignfields = array($psnSignfield);//構(gòu)造個(gè)人signfields參數(shù)對象$orgSignfield = new Signfield();
$posBean = new PosBean();
$orgSignfield->setFileId($fileId)->setPosBean($posBean->setPosPage(1)->setPosX(224)->setPosY(334))->setActorIndentityType(2);//機(jī)構(gòu)簽署必傳
$orgSignfields = array($orgSignfield);//構(gòu)造個(gè)人signfields參數(shù)對象$signerpsn = new Signer();
$signerAccount1 = new SignerAccount();
$signerAccount1->setSignerAccountId($accountId);
$signerpsn->setSignerAccount($signerAccount1)->setSignfields($psnSignfields);;//傳入個(gè)人signer信息$signerorg = new Signer();
$signerA1ccount2 = new SignerAccount();
$signerA1ccount2->setSignerAccountId($accountId)->setAuthorizedAccountId($orgId);
$signerorg->setSignerAccount($signerA1ccount2)->setSignfields($orgSignfields);//傳入企業(yè)signer信息$signers = array($signerpsn, $signerorg);//$createFlowOneStep = SignFile::createFlowOneStep($docs, $flowInfo, $signers);
$flowOneStepResp = $createFlowOneStep->execute();
$flowOneStepJson = json_decode($flowOneStepResp->getBody());
$flowId = $flowOneStepJson->data->flowId;//流程id保存好
var_dump("------------------ 一步發(fā)起簽署 end -----------------");var_dump("------------------ 獲取簽署地址 start -----------------");
$getFileSignUrl = SignFile::getFileSignUrl($flowId, $accountId);
$getFileSignUrl->setOrganizeId($orgId);
$getFileSignUrlResp = $getFileSignUrl->execute();
$getFileSignUrlJson = json_decode($getFileSignUrlResp->getBody());
$shortUrl = $getFileSignUrlJson->data -> shortUrl;
var_dump("簽署短連接,復(fù)制到瀏覽器打開\n".$shortUrl);
var_dump("------------------ 獲取簽署地址 end -----------------");

4、根據(jù)Demo自己封裝簽署方法

流程發(fā)起簽署API：$flowInfo配置參數(shù)如下：一步發(fā)起簽署

    //簽署：企業(yè)對個(gè)人public function oneStepB2C($data){$accountId = $data['account_id']; //個(gè)人賬號id$orgId = $data['org_id']; //企業(yè)賬號id$fileId = $data['file_id']; //文件id$businessScene = $data['business_scene']; //任務(wù)主題//查詢模板文件詳情$fileInfo = self::filePDFDetail($data);$pdfTotalPages = $fileInfo['pdfTotalPages']; //給最后一頁設(shè)置個(gè)人或者公司的蓋章區(qū)域//設(shè)置簽署區(qū)域的坐標(biāo) x軸坐標(biāo)，左下角為原點(diǎn)；y軸坐標(biāo)，左下角為原點(diǎn)$posPersonX = 470;$posOrganizeX = 130;$posY = 150;$doc = new Doc();$doc->setFileId($fileId);$docs = array($doc);//流程配置$flowConfigInfo = ['noticeDeveloperUrl' => $this->callbackUrl, //回調(diào)地址：https://www.xxxxapi.com/esaas/businessCallback];$flowInfo = new FlowInfo();$flowInfo->setBusinessScene($businessScene)->setAutoArchive(true)//自動歸檔->setAutoInitiate(true)//自動開啟流程->setFlowConfigInfo($flowConfigInfo);$signValidity = 0; //簽署有效截止日期,毫秒，默認(rèn)不失效；注：超過簽署有效截止時(shí)間，則無法繼續(xù)簽署。若該參數(shù)設(shè)置的時(shí)間到期，則會觸發(fā)【流程結(jié)束回調(diào)通知】if ($signValidity > 0) {$flowInfo->setSignValidity($signValidity);}$psnSignfield = new Signfield();$posBean = new PosBean();$psnSignfield->setFileId($fileId)->setPosBean($posBean->setPosPage($pdfTotalPages)->setPosX($posPersonX)->setPosY($posY)); //設(shè)置蓋章區(qū)域：頁碼；x軸坐標(biāo)，左下角為原點(diǎn)；y軸坐標(biāo)，左下角為原點(diǎn)$psnSignfields = array($psnSignfield); //構(gòu)造個(gè)人signfields參數(shù)對象$signerpsn = new Signer();$signerAccount1 = new SignerAccount();$signerAccount1->setSignerAccountId($accountId);$signerpsn->setSignerAccount($signerAccount1)->setSignfields($psnSignfields); //傳入個(gè)人signer信息$orgSignfield = new Signfield();$posBean = new PosBean();$orgSignfield->setFileId($fileId)->setPosBean($posBean->setPosPage($pdfTotalPages)->setPosX($posOrganizeX)->setPosY($posY)) //設(shè)置蓋章區(qū)域：頁碼；x軸坐標(biāo)，左下角為原點(diǎn)；y軸坐標(biāo)，左下角為原點(diǎn)->setActorIndentityType(2); //機(jī)構(gòu)簽署必傳$orgSignfields = array($orgSignfield);//構(gòu)造機(jī)構(gòu)signfields參數(shù)對象$signerorg = new Signer();$signerA1ccount2 = new SignerAccount();$signerA1ccount2->setSignerAccountId($accountId)->setAuthorizedAccountId($orgId);$signerorg->setSignerAccount($signerA1ccount2)->setSignfields($orgSignfields); //傳入企業(yè)signer信息$signers = array($signerpsn, $signerorg);//$createFlowOneStep = SignFile::createFlowOneStep($docs, $flowInfo, $signers);$flowResult = self::execResponse($createFlowOneStep);$flowId = $flowResult['flowId']; //流程id保存好$getFileSignUrl = SignFile::getFileSignUrl($flowId, $accountId);$getFileSignUrl->setOrganizeId($orgId);$result = self::execResponse($getFileSignUrl);/*** TODO 加入自己的邏輯操作：保存到自己的數(shù)據(jù)庫*/return [$flowResult, $result];}//簽署：個(gè)人public function oneStepC($data){$accountId = $data['account_id']; //個(gè)人賬號id$fileId = $data['file_id']; //文件id$businessScene = $data['business_scene']; //任務(wù)主題//查詢模板文件詳情$fileInfo = self::filePDFDetail($data);$pdfTotalPages = $fileInfo['pdfTotalPages']; //給最后一頁設(shè)置個(gè)人或者公司的蓋章區(qū)域//設(shè)置簽署區(qū)域的坐標(biāo) x軸坐標(biāo)，左下角為原點(diǎn)；y軸坐標(biāo)，左下角為原點(diǎn)$posPersonX = 470;$posY = 150;$doc = new Doc();$doc->setFileId($fileId);$docs = array($doc);//流程配置$flowConfigInfo = ['noticeDeveloperUrl' => $this->callbackUrl, //回調(diào)地址：https://www.xxxxapi.com/esaas/businessCallback];$flowInfo = new FlowInfo();$flowInfo->setBusinessScene($businessScene)->setAutoArchive(true)//自動歸檔->setAutoInitiate(true)//自動開啟流程->setFlowConfigInfo($flowConfigInfo);$signValidity = 0; //簽署有效截止日期,毫秒，默認(rèn)不失效；注：超過簽署有效截止時(shí)間，則無法繼續(xù)簽署。若該參數(shù)設(shè)置的時(shí)間到期，則會觸發(fā)【流程結(jié)束回調(diào)通知】if ($signValidity > 0) {$flowInfo->setSignValidity($signValidity);}$psnSignfield = new Signfield();$posBean = new PosBean();$psnSignfield->setFileId($fileId)->setPosBean($posBean->setPosPage($pdfTotalPages)->setPosX($posPersonX)->setPosY($posY)); //設(shè)置蓋章區(qū)域：頁碼；x軸坐標(biāo)，左下角為原點(diǎn)；y軸坐標(biāo)，左下角為原點(diǎn)$psnSignfields = array($psnSignfield); //構(gòu)造個(gè)人signfields參數(shù)對象$signerpsn = new Signer();$signerAccount1 = new SignerAccount();$signerAccount1->setSignerAccountId($accountId);$signerpsn->setSignerAccount($signerAccount1)->setSignfields($psnSignfields); //傳入個(gè)人signer信息$signers = array($signerpsn);//$createFlowOneStep = SignFile::createFlowOneStep($docs, $flowInfo, $signers);$flowResult = self::execResponse($createFlowOneStep);$flowId = $flowResult['flowId']; //流程id保存好$getFileSignUrl = SignFile::getFileSignUrl($flowId, $accountId);$result = self::execResponse($getFileSignUrl);/*** TODO 加入自己的邏輯操作：保存到自己的數(shù)據(jù)庫*/return [$flowResult, $result];}/*** 統(tǒng)一執(zhí)行接口數(shù)據(jù)* @param mixed $requestObject 對象 use Identity\factory\request\EsignRequest;* @param mixed $codeName 業(yè)務(wù)碼字段名* @return array*/public function execResponse(EsignRequest $requestObject, $codeName = 'code'){$executeObject = $requestObject->execute();//execute方法發(fā)起請求$resultJson = $executeObject->getBody(); //獲取結(jié)果json數(shù)據(jù)//記錄日志$log = json_encode($_REQUEST, JSON_UNESCAPED_UNICODE) . PHP_EOL . $resultJson; //記錄REQUEST數(shù)據(jù)，換行，并記錄 響應(yīng)數(shù)據(jù)Log::write($log); //日志記入 use think\facade\Log;$result = json_decode($resultJson, true); //json轉(zhuǎn)arrayif ($result[$codeName] != $this->successCode) { //根據(jù)狀態(tài)碼判斷結(jié)果throw new BaseException($result['message']);}//返回data數(shù)據(jù)$data = isset($result['data']) ? $result['data'] : []; //刪除等操作時(shí)，data為nullreturn $data;}

5、sdk使用

sdk使用的話，根據(jù)自己的目錄存放位置，來選擇是否需要添加命名空間

四、最簡單的接口調(diào)用順序

我這里說的最簡單是指，我們不通過調(diào)用模板接口操作模板文件數(shù)據(jù)（模板接口里的參數(shù)太復(fù)雜了）
咱們這里就用一個(gè)只需要簽署用戶姓名，企業(yè)姓名的合同，則接口的調(diào)用順序如下：

1、創(chuàng)建個(gè)人簽署賬號對應(yīng)的 修改 查詢 注銷 接口也可以封裝一下（accountId, thirdPartyUserId 二選一）
2、創(chuàng)建機(jī)構(gòu)簽署賬號對應(yīng)的 修改 查詢 注銷 接口也可以封裝一下（orgId, thirdPartyUserId 二選一）
3、文件上傳對應(yīng)的 查詢文件上傳狀態(tài)（當(dāng)接口返回的文件狀態(tài) status 值為 2 或 5 時(shí)，此文件才可以被正常添加到簽署流程中。）、查詢PDF文件詳情（當(dāng)接口返回的文件狀態(tài) status 值為 2 或 5 時(shí)，此文件才可以被正常添加到簽署流程中或下載PDF文件） 也可以封裝一下
4、針對模板的操作，跳過
5、選擇一步發(fā)起簽署，這個(gè)接口里可以配置回調(diào)：具體的代碼請參考 Demo文件中的 b2cDemo.php
6、回調(diào)操作：通過 action 判斷回調(diào)的類型，具體請參考我上面的：回調(diào)通知接收說明
7、PDF文件驗(yàn)簽：這一步看情況
8、回調(diào)如果簽署成功，則流程文檔下載歸檔，會返回文檔地址字段 fileUrl, 有效時(shí)間1小時(shí)；該鏈接建議只用于下載，不要直接預(yù)覽；可以給用戶查看簽署后的文件。
說明：這里面的步驟我們需要設(shè)計(jì)數(shù)據(jù)表存儲e簽寶數(shù)據(jù)，需要有我們的數(shù)據(jù)交互，請根據(jù)接口的請求、返回?cái)?shù)據(jù) 自行設(shè)計(jì)數(shù)據(jù)表。

五、需要注意的點(diǎn)

1、創(chuàng)建個(gè)人簽署賬號接口，證件包含小寫的 x

1、thirdPartyUserId 創(chuàng)建個(gè)人賬號的唯一標(biāo)識：我們需要保證參數(shù)的唯一性，并且能關(guān)聯(lián)上用戶，否則一個(gè)用戶會一直創(chuàng)建賬戶~
2、idNumber 證件號：身份證中有X字母的，需要傳入大寫的X。需要代碼處理一下：strtoupper($data['id_number']);

2、文件上傳接口，文件名格式

fileName 文件名稱：格式問題文件名稱不支持以下9個(gè)字符：

文件名稱（必須帶上文件擴(kuò)展名，不然會導(dǎo)致后續(xù)發(fā)起流程校驗(yàn)過不去 示例：合同.pdf ）；
注意：
（1）該字段的文件后綴名稱和真實(shí)的文件后綴需要一致。比如上傳的文件類型是word文件，那該參數(shù)需要傳“xxx.docx”，不能是“xxx.pdf”
（2）該字段建議直接傳入pdf文件，其他類型文件建議本地自行轉(zhuǎn)換成pdf，避免通過接口格式轉(zhuǎn)換引起的格式錯(cuò)誤、耗時(shí)久等問題。
（3）文件名稱不支持以下9個(gè)字符：/ \ : * " < > | ？

3、業(yè)務(wù)碼字段并不都是 code，也可能是 errCode

文件上傳步驟二文件流上傳，返回的是 errCode 不是 code，這個(gè)需要注意一下

4、方法不存在

如果有缺失的方法，自己可以按照官方的sdk自行增加php文件，他這里一個(gè)PHP文件是對應(yīng)一個(gè)接口，然后在一個(gè)php文件中調(diào)用這些php文件。SDK封裝方式和京東一樣，很靈活。
注意：我們自定義的文件最好取一個(gè)不會重復(fù)的文件名，加上你的筆名后綴啥的（比如 QryPdfDetailZSF.php），如果更新官方文檔，被覆蓋了就很尷尬了。

5、簽署章子位置的設(shè)置

通過 setPosPage()，setPosX()，setPosY() 設(shè)置：//設(shè)置蓋章區(qū)域：頁碼；x軸坐標(biāo)，左下角為原點(diǎn)；y軸坐標(biāo)，左下角為原點(diǎn)
demo 如下

$orgSignfield = new Signfield();
$posBean = new PosBean();
$orgSignfield->setFileId($fileId)->setPosBean($posBean->setPosPage(1)->setPosX(224)->setPosY(334))->setActorIndentityType(2);//機(jī)構(gòu)簽署必傳
$orgSignfields = array($orgSignfield);//構(gòu)造個(gè)人signfields參數(shù)對象

6、接口請求統(tǒng)一處理，封裝一個(gè)方法統(tǒng)一請求

接口請求都是執(zhí)行execute()，getBody()方法，我們不需要每次都調(diào)用。結(jié)合第三個(gè)問題，封裝一個(gè)方法。

    /*** 通過accountId查詢個(gè)人簽署賬號* @return array*/public function qryPersonByaccountId(){$account = Account::qryPersonByaccountId($_REQUEST['account_id']); //use Identity\factory\base\Account;$result = self::execResponse($account);/*** TODO 與自己的數(shù)據(jù)庫交互*/return $result;}/*** 統(tǒng)一執(zhí)行接口數(shù)據(jù)* @param mixed $requestObject 對象 use Identity\factory\request\EsignRequest;* @param mixed $codeName 業(yè)務(wù)碼字段名* @return array*/public function execResponse(EsignRequest $requestObject, $codeName = 'code'){$executeObject = $requestObject->execute();//execute方法發(fā)起請求$resultJson = $executeObject->getBody(); //獲取結(jié)果json數(shù)據(jù)//記錄日志$log = json_encode($_REQUEST, JSON_UNESCAPED_UNICODE) . PHP_EOL . $resultJson; //記錄REQUEST數(shù)據(jù)，換行，并記錄 響應(yīng)數(shù)據(jù)Log::write($log); //日志記入 use think\facade\Log;$result = json_decode($resultJson, true); //json轉(zhuǎn)arrayif ($result[$codeName] != $this->successCode) { //根據(jù)狀態(tài)碼判斷結(jié)果die($result['message']); //根據(jù)你的實(shí)際情況寫}//返回data數(shù)據(jù)$data = isset($result['data']) ? $result['data'] : []; //刪除等操作時(shí)，data為nullreturn $data;}

六、寫在最后

這篇文章僅供大家參考，歡迎各位大佬指出問題~

總結(jié)

以上是生活随笔為你收集整理的PHP e签宝电子签名Saas API 对接流程的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。

上一篇：怀孕备案表（妊娠备案表）
下一篇： Origin 2018中文版软件下载和安