Laravel中实现DocuSign邮件远程签署代码请求

前置准备 #

• 安装 DocuSign PHP SDK：

  composer require docusign/esign-client
  

• 在项目根目录的 .env 文件中添加 DocuSign 配置：

  DOCUSIGN_CLIENT_ID=你的DocuSign客户端ID
  DOCUSIGN_CLIENT_SECRET=你的DocuSign客户端密钥
  DOCUSIGN_ACCOUNT_ID=你的DocuSign账户ID
  DOCUSIGN_BASE_URL=https://demo.docusign.net/restapi # 测试环境，正式环境替换为https://www.docusign.net/restapi
  

• 从 DocuSign 后台生成 RSA 私钥，保存到项目 storage/app/docusign_private_key.txt，确保文件权限安全（仅服务器可读）。

核心实现代码 #

创建控制器 app/Http/Controllers/DocuSignController.php：

<?php

namespace App\Http\Controllers;

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\Document;
use DocuSign\eSign\Model\Recipients;
use Illuminate\Http\Request;

class DocuSignController extends Controller
{
    protected $apiClient;

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

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

    // 通过JWT获取访问令牌
    private function getAccessToken()
    {
        $integratorKey = env('DOCUSIGN_CLIENT_ID');
        $accountId = env('DOCUSIGN_ACCOUNT_ID');
        $privateKey = file_get_contents(storage_path('app/docusign_private_key.txt'));

        $response = $this->apiClient->requestJWTUserToken(
            $integratorKey,
            $accountId,
            'https://account-d.docusign.com/oauth/token',
            $privateKey,
            3600
        );

        return $response->getBody()->access_token;
    }

    // 发送签署请求接口
    public function sendSigningRequest(Request $request)
    {
        // 1. 加载待签署文档并转base64
        $documentContent = file_get_contents(storage_path('app/documents/contract.pdf'));
        $documentBase64 = base64_encode($documentContent);

        $document = new Document([
            'document_base64' => $documentBase64,
            'name' => '服务合同.pdf',
            'document_id' => '1'
        ]);

        // 2. 设置签署人信息
        $signer = new Signer([
            'email' => $request->input('signer_email'),
            'name' => $request->input('signer_name'),
            'recipient_id' => '1',
            'routing_order' => '1'
        ]);

        // 3. 指定签署位置（第一页坐标100,100处）
        $signHere = new SignHere([
            'document_id' => '1',
            'page_number' => '1',
            'x_position' => '100',
            'y_position' => '100'
        ]);

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

        // 4. 构建信封定义
        $recipients = new Recipients(['signers' => [$signer]]);
        $envelopeDefinition = new EnvelopeDefinition([
            'email_subject' => '请签署服务合同',
            'email_blurb' => '您好，请查看并签署附件中的服务合同。',
            'documents' => [$document],
            'recipients' => $recipients,
            'status' => 'sent' // 直接发送信封
        ]);

        // 5. 发送签署请求
        $envelopeApi = new \DocuSign\eSign\Api\EnvelopesApi($this->apiClient);
        $results = $envelopeApi->createEnvelope(env('DOCUSIGN_ACCOUNT_ID'), $envelopeDefinition);

        return response()->json([
            'success' => true,
            'envelope_id' => $results->getEnvelopeId(),
            'message' => '签署请求已发送至指定邮箱'
        ]);
    }
}

路由配置 #

在 routes/api.php 中添加接口路由：

Route::post('docusign/send-sign-request', [App\Http\Controllers\DocuSignController::class, 'sendSigningRequest']);

注意事项 #

• 如果需要使用 DocuSign 模板创建信封，可以替换 Document 部分为模板 ID 相关配置，减少重复设置签署位置的工作。
• 正式环境部署时，务必确保私钥文件不被公开访问，且令牌有效期根据业务需求调整。
• 可以根据需求添加信封状态查询、签署回调接收等功能。

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