DocuSign集成：如何根据签署结果调用success/failure函数

核心逻辑说明 #

DocuSign完成签署流程后，会将用户重定向到你指定的return_url，并通过URL参数携带签署状态信息。我们需要通过这些参数判断签署是否成功，再分别调用success或failure函数。

具体实现步骤 #

1. 调整返回URL与路由配置 #

首先新增专门处理DocuSign回调的路由，替换原有的返回地址：

// 保留原有测试路由，新增回调处理路由
Route::get('/contract',[docusign::class,'index']);
Route::post('/contract',[docusign::class,'send']);
Route::get('/docusign/callback',[docusign::class,'handleCallback']);

然后修改getTemplateArgs中的返回URL为新的回调地址：

private function getTemplateArgs()
{   
    $apiClient = new ApiClient();
    $apiClient->getOAuth()->setOAuthBasePath(config('app.auth_server')); 
    $accessToken = $this->getToken($apiClient);

    $args = [
        'account_id' => config('app.client'),
        'base_path' => "https://demo.docusign.net/restapi",
        'ds_access_token' => $this->getToken($apiClient),
        'envelope_args' => [
                'signer_client_id' => $this->signer_client_id,
                // 修改为回调路由地址
                'ds_return_url' => "http://127.0.0.1:8000/docusign/callback"
            ]
            
    ];
       
    return $args;
}

2. 编写回调处理函数 #

新增handleCallback函数，通过DocuSign返回的event参数判断签署状态：

public function handleCallback(Request $request)
{
    $event = $request->query('event');
    $envelopeId = $request->query('envelopeId');
    
    // 常见状态值：
    // *signing_complete*: 签署成功完成
    // *cancel*: 用户取消签署流程
    // *decline*: 用户拒绝签署
    // *session_timeout*: 会话超时
    
    if ($event === 'signing_complete') {
        // 可选：调用EnvelopesApi查询信封详细状态，确保签署完成
        $this->success($request);
        return redirect()->to('/success-page'); // 可根据业务跳转对应页面
    } else {
        // 取消、拒绝、超时等情况均视为失败
        $this->failure($request);
        return redirect()->to('/failure-page'); // 可根据业务跳转对应页面
    }
}

3. 完善业务函数逻辑 #

根据实际需求补充success和failure函数的业务处理：

public function success(Request $request){
    // 签署成功后的业务逻辑：更新数据库状态、发送通知等
    $envelopeId = $request->query('envelopeId');
    // 示例：记录签署成功日志
    Log::info("DocuSign签署成功，信封ID: {$envelopeId}");
}

public function failure (Request $request){
    // 签署失败后的业务逻辑：记录失败原因、提醒用户重新签署等
    $event = $request->query('event');
    $envelopeId = $request->query('envelopeId');
    Log::info("DocuSign签署失败，事件类型: {$event}，信封ID: {$envelopeId}");
}

4. 测试方案 #

• 成功场景测试：在Demo环境完成完整签署流程，确认回调后success函数触发，业务状态正确更新。
• 失败场景测试：
  • 签署过程中点击「取消」按钮，验证failure函数执行
  • 模拟会话超时（长时间不操作），确认状态判断逻辑生效
  • 测试用户拒绝签署的情况，确保失败逻辑正常运行
• 手动参数验证：构造回调URL（如http://127.0.0.1:8000/docusign/callback?event=signing_complete&envelopeId=xxx）直接访问，验证函数调用是否正确。

内容的提问来源于stack exchange，提问作者Rubyjane