如何使用PHP及Laravel API为DocuSign签署模板设置自动提醒

1. 安装DocuSign PHP SDK #

通过Composer安装官方SDK：

composer require docusign/esign-client

2. 配置Laravel环境变量 #

在.env文件中添加DocuSign认证及账户信息：

DOCUSIGN_INTEGRATION_KEY=你的集成密钥
DOCUSIGN_ACCOUNT_ID=你的账户ID
DOCUSIGN_BASE_PATH=https://demo.docusign.net/restapi # 生产环境替换为https://www.docusign.net/restapi
DOCUSIGN_USER_ID=你的用户ID
DOCUSIGN_OAUTH_CLIENT_ID=你的OAuth客户端ID
DOCUSIGN_OAUTH_CLIENT_SECRET=你的OAuth客户端密钥
DOCUSIGN_REDIRECT_URI=http://你的应用域名/docusign/callback

3. 封装DocuSign服务类 #

创建app/Services/DocuSignService.php，封装API调用逻辑，重点实现基于模板创建带自动提醒的信封：

<?php

namespace App\Services;

use DocuSign\eSign\Api\EnvelopesApi;
use DocuSign\eSign\Client\ApiClient;
use DocuSign\eSign\Configuration;
use DocuSign\eSign\Model\EnvelopeDefinition;
use DocuSign\eSign\Model\TemplateRole;
use DocuSign\eSign\Model\Reminders;

class DocuSignService
{
    protected $apiClient;

    public function __construct()
    {
        $config = new Configuration();
        $config->setHost(env('DOCUSIGN_BASE_PATH'));
        $this->apiClient = new ApiClient($config);
        
        // 获取OAuth访问令牌（JWT方式，适合服务端自动操作）
        $token = $this->getAccessToken();
        $this->apiClient->setAccessToken($token);
    }

    private function getAccessToken()
    {
        $response = $this->apiClient->requestJWTUserToken(
            env('DOCUSIGN_OAUTH_CLIENT_ID'),
            env('DOCUSIGN_USER_ID'),
            'https://account-d.docusign.com/oauth/token',
            file_get_contents(storage_path('docusign_private_key.txt')),
            3600
        );
        
        return $response[0]['access_token'];
    }

    /**
     * 基于模板创建带自动提醒的签署信封
     * @param string $templateId DocuSign模板ID
     * @param array $signers 签署人信息，格式：[['email' => 'xxx', 'name' => 'xxx', 'role_name' => '模板角色名']]
     * @param int $reminderDelay 首次提醒延迟天数（签署请求发送后X天）
     * @param int $reminderFrequency 后续提醒间隔天数
     * @param int $maxReminders 最大提醒次数
     * @return string 信封ID
     */
    public function createEnvelopeWithReminders(string $templateId, array $signers, int $reminderDelay = 3, int $reminderFrequency = 2, int $maxReminders = 5): string
    {
        // 构建模板角色
        $templateRoles = [];
        foreach ($signers as $signer) {
            $role = new TemplateRole();
            $role->setEmail($signer['email']);
            $role->setName($signer['name']);
            $role->setRoleName($signer['role_name']);
            $templateRoles[] = $role;
        }

        // 配置自动提醒
        $reminders = new Reminders();
        $reminders->setReminderEnabled(true);
        $reminders->setReminderDelay($reminderDelay);
        $reminders->setReminderFrequency($reminderFrequency);
        $reminders->setMaxReminders($maxReminders);

        // 构建信封定义
        $envelopeDefinition = new EnvelopeDefinition();
        $envelopeDefinition->setTemplateId($templateId);
        $envelopeDefinition->setTemplateRoles($templateRoles);
        $envelopeDefinition->setStatus('sent'); // 立即发送签署请求
        $envelopeDefinition->setReminders($reminders);

        // 调用API创建信封
        $envelopesApi = new EnvelopesApi($this->apiClient);
        $result = $envelopesApi->createEnvelope(env('DOCUSIGN_ACCOUNT_ID'), $envelopeDefinition);

        return $result->getEnvelopeId();
    }
}

4. 在控制器中调用服务 #

创建控制器方法处理业务逻辑：

<?php

namespace App\Http\Controllers;

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

class DocuSignController extends Controller
{
    public function sendSignRequest(Request $request)
    {
        $docusignService = new DocuSignService();
        
        // 示例：基于模板创建带提醒的信封
        $envelopeId = $docusignService->createEnvelopeWithReminders(
            '你的模板ID',
            [
                ['email' => 'signer@example.com', 'name' => '张三', 'role_name' => '签署人']
            ],
            3, // 发送后3天首次提醒
            2, // 每2天提醒一次
            5  // 最多提醒5次
        );

        return response()->json(['envelope_id' => $envelopeId, 'message' => '签署请求已发送，自动提醒已配置']);
    }
}

关键说明 #

• 提醒参数：reminderDelay是签署请求发送后首次提醒的天数，reminderFrequency是后续每次提醒的间隔天数，maxReminders控制最多提醒次数。
• OAuth授权：示例采用JWT授权，适合服务端自动发起签署的场景；若需用户主动授权，需替换为授权码流程。
• 模板角色：签署人role_name必须与DocuSign模板中定义的角色名完全匹配，否则无法关联模板字段。

内容的提问来源于stack exchange，提问作者Manish Kumar Pathak