寻求Laravel集成DocuSign远程签署的实现参考

以下是Laravel项目中集成DocuSign远程签署的具体实现步骤，完全基于Laravel架构封装，替代纯PHP SDK的零散调用：

1. 安装依赖并配置参数 #

首先通过Composer安装DocuSign官方PHP SDK：

composer require docusign/esign-client

在config/services.php中添加DocuSign的配置项：

'docusign' => [
    'integrator_key' => env('DOCUSIGN_INTEGRATOR_KEY'),
    'account_id' => env('DOCUSIGN_ACCOUNT_ID'),
    'base_path' => env('DOCUSIGN_BASE_PATH', 'https://demo.docusign.net/restapi'),
    'oauth_host_name' => env('DOCUSIGN_OAUTH_HOST', 'account-d.docusign.com'),
    'private_key_path' => storage_path('app/docusign/private.key'),
    'user_id' => env('DOCUSIGN_USER_ID'),
]

在.env文件中补充对应的环境变量（替换为你在DocuSign开发者平台获取的真实值）：

DOCUSIGN_INTEGRATOR_KEY=你的集成密钥
DOCUSIGN_ACCOUNT_ID=你的账户ID
DOCUSIGN_USER_ID=你的用户ID

2. 创建封装DocuSign逻辑的服务类 #

在app/Services目录下创建DocuSignService.php，封装认证、信封创建、签署链接生成等核心逻辑：

<?php

namespace App\Services;

use DocuSign\eSign\Client\ApiClient;
use DocuSign\eSign\Configuration;
use DocuSign\eSign\Model\EnvelopeDefinition;
use DocuSign\eSign\Model\Signer;
use DocuSign\eSign\Model\SignHere;
use DocuSign\eSign\Model\Tabs;
use DocuSign\eSign\Model\Recipients;
use DocuSign\eSign\Model\Document;
use DocuSign\eSign\Model\RecipientViewRequest;

class DocuSignService
{
    protected $apiClient;

    public function __construct()
    {
        $config = new Configuration();
        $config->setHost(config('services.docusign.base_path'));
        $config->addDefaultHeader('Authorization', 'Bearer ' . $this->getAccessToken());

        $this->apiClient = new ApiClient($config);
    }

    // 通过JWT获取访问令牌
    private function getAccessToken()
    {
        $privateKey = file_get_contents(config('services.docusign.private_key_path'));
        $oauthService = $this->apiClient->getOAuth();
        
        $response = $oauthService->requestJWTUserToken(
            config('services.docusign.integrator_key'),
            config('services.docusign.user_id'),
            config('services.docusign.oauth_host_name'),
            $privateKey,
            3600,
            ['signature']
        );

        return $response[0]['access_token'];
    }

    // 创建并发送远程签署信封
    public function createRemoteSignEnvelope(string $documentPath, array $signers)
    {
        // 构建文档对象
        $document = new Document([
            'document_base64' => base64_encode(file_get_contents($documentPath)),
            'name' => '待签署文档',
            'document_id' => '1'
        ]);

        // 处理签署者和签署标签
        $signerModels = [];
        foreach ($signers as $index => $signer) {
            $signHere = new SignHere([
                'document_id' => '1',
                'page_number' => '1',
                'recipient_id' => (string)($index + 1),
                'tab_label' => '签署位置',
                'x_position' => '150',
                'y_position' => '200'
            ]);

            $tabs = new Tabs(['sign_here_tabs' => [$signHere]]);

            $signerModel = new Signer([
                'email' => $signer['email'],
                'name' => $signer['name'],
                'recipient_id' => (string)($index + 1),
                'tabs' => $tabs,
                'client_user_id' => $signer['client_user_id'] // 用于匹配远程签署用户的唯一ID
            ]);

            $signerModels[] = $signerModel;
        }

        $recipients = new Recipients(['signers' => $signerModels]);

        // 定义信封
        $envelopeDefinition = new EnvelopeDefinition([
            'email_subject' => '请完成文档签署',
            'documents' => [$document],
            'recipients' => $recipients,
            'status' => 'sent'
        ]);

        // 发送信封
        $envelopesApi = $this->apiClient->getEnvelopesApi();
        return $envelopesApi->createEnvelope(config('services.docusign.account_id'), $envelopeDefinition);
    }

    // 获取远程签署的跳转链接
    public function getSigningUrl(string $envelopeId, string $clientUserId)
    {
        $viewRequest = new RecipientViewRequest([
            'return_url' => route('sign.completed'),
            'authentication_method' => 'none',
            'client_user_id' => $clientUserId,
            'recipient_id' => '1'
        ]);

        $envelopesApi = $this->apiClient->getEnvelopesApi();
        $viewUrl = $envelopesApi->createRecipientView(config('services.docusign.account_id'), $envelopeId, $viewRequest);

        return $viewUrl->getUrl();
    }
}

3. 创建控制器处理业务流程 #

在app/Http/Controllers下创建DocuSignController.php，处理签署请求的触发和签署完成后的回调：

<?php

namespace App\Http\Controllers;

use App\Services\DocuSignService;
use Illuminate\Http\Request;

class DocuSignController extends Controller
{
    protected $docusignService;

    public function __construct(DocuSignService $docusignService)
    {
        $this->docusignService = $docusignService;
    }

    // 触发签署请求
    public function sendSignRequest()
    {
        // 示例文档路径，替换为你的实际文档位置
        $documentPath = storage_path('app/public/contract.pdf');
        
        // 签署人信息，可根据业务逻辑从数据库或请求中获取
        $signers = [
            [
                'email' => 'signer@example.com',
                'name' => '张三',
                'client_user_id' => 'user_12345' // 系统内用户的唯一标识
            ]
        ];

        // 创建信封并获取签署链接
        $envelope = $this->docusignService->createRemoteSignEnvelope($documentPath, $signers);
        $signingUrl = $this->docusignService->getSigningUrl($envelope->getEnvelopeId(), 'user_12345');

        // 跳转至DocuSign签署页面
        return redirect()->to($signingUrl);
    }

    // 签署完成后的回调处理
    public function signCompleted(Request $request)
    {
        // 这里可以添加业务逻辑，比如更新订单状态、记录签署日志等
        return view('sign.completed');
    }
}

4. 配置路由 #

在routes/web.php中添加对应的路由：

Route::get('docusign/send', [DocuSignController::class, 'sendSignRequest'])->name('docusign.send');
Route::get('sign/completed', [DocuSignController::class, 'signCompleted'])->name('sign.completed');

注意事项 #

• 确保你已在DocuSign开发者平台创建应用，生成RSA私钥（可通过openssl genrsa -out private.key 2048命令生成）并上传至平台
• 首次使用JWT认证时，需要手动完成一次授权流程，之后即可自动获取令牌
• 测试阶段使用DocuSign的沙箱环境（demo.docusign.net），正式上线切换至生产环境

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