PHP调用DocuSign API：实现签署后跳转至信封专属付款URL

嘿，我来帮你搞定这个需求！你要让签署人完成签署后跳转到对应信封的专属付款URL，其实利用DocuSign的签署后重定向功能就能轻松实现，结合你正在用的sign-client PHP API，具体步骤如下：

1. 创建信封时给每个签署人单独配置重定向URL #

这是最直接的方案——在构建Signer模型的时候，直接给每个签署人设置recipientRedirectUrl属性，这个URL就是你网站对应该信封的专属付款链接。等这个签署人完成签署后，DocuSign会自动把他们跳转到你指定的地址。

PHP代码示例 #

use DocuSign\eSign\Model\Signer;
use DocuSign\eSign\Model\EnvelopeDefinition;
use DocuSign\eSign\Model\Recipients;

// 假设你已经完成了API客户端的初始化（配置OAuth令牌、账户ID这些）
$apiClient = /* 你的初始化逻辑 */;

// 构建签署人对象
$signer = new Signer();
$signer->setEmail('signer@example.com');
$signer->setName('John Doe');
$signer->setRecipientId('1'); // 每个签署人唯一ID
$signer->setRoutingOrder('1'); // 签署顺序

// 生成对应信封的专属付款URL（这里用信封ID做标识，你可以根据业务调整参数）
// 注意：如果是先创建信封再获取ID，你可以在创建信封后再更新签署人的重定向URL；不过更高效的是提前规划参数
$paymentUrl = "https://your-website.com/payment?envelope_id={$yourEnvelopeId}&recipient_id=1";
$signer->setRecipientRedirectUrl($paymentUrl);

// 把签署人加入收件人集合
$recipients = new Recipients();
$recipients->setSigners([$signer]);

// 构建信封定义，别忘了添加文档、设置邮件主题等必要配置
$envelopeDefinition = new EnvelopeDefinition();
$envelopeDefinition->setEmailSubject('请签署这份文档');
$envelopeDefinition->setRecipients($recipients);
// $envelopeDefinition->setDocuments([/* 你的文档对象 */]);

// 调用API创建信封
$envelopesApi = new DocuSign\eSign\Api\EnvelopesApi($apiClient);
$envelopeSummary = $envelopesApi->createEnvelope($yourAccountId, $envelopeDefinition);

2. 重定向后的参数验证（非常推荐） #

为了防止恶意请求直接访问你的付款页面，你最好在付款页面的后端做一下验证——DocuSign在跳转时会自动携带event、envelopeId、recipientId这些参数，你可以用这些参数调用DocuSign API确认签署状态。

验证逻辑示例（付款页面后端） #

// 从请求中获取DocuSign传递的参数
$envelopeId = $_GET['envelope_id'] ?? '';
$recipientId = $_GET['recipientId'] ?? '';
$event = $_GET['event'] ?? '';

// 初始化API客户端（和创建信封时的配置一致）
$apiClient = /* 你的初始化逻辑 */;

$envelopesApi = new DocuSign\eSign\Api\EnvelopesApi($apiClient);
try {
    // 查询该签署人的状态
    $recipient = $envelopesApi->getRecipient($yourAccountId, $envelopeId, $recipientId);
    
    // 验证事件类型和签署状态
    if ($event === 'signing_complete' && $recipient->getStatus() === 'completed') {
        // 验证通过，展示付款页面
        echo "请完成付款...";
    } else {
        // 状态不对，返回错误提示
        echo "无效的签署请求，请联系客服";
    }
} catch (Exception $e) {
    // API调用失败，处理错误
    echo "验证失败：" . $e->getMessage();
}

3. 备选：信封完成后统一跳转（如果需要） #

如果你的需求是所有签署人都完成整个信封后再跳转（而不是单个签署人完成就跳），那可以用信封级的事件通知，设置redirectUrl并指定触发事件为envelope_completed。不过这个和你当前的需求不太匹配，但可以作为备用方案参考：

use DocuSign\eSign\Model\EventNotification;

$eventNotification = new EventNotification();
$eventNotification->setRedirectUrl('https://your-website.com/global-payment?envelope_id=' . $envelopeId);
$eventNotification->setEnvelopeEvents([['envelopeEventStatusCode' => 'completed']]);

$envelopeDefinition->setEventNotification($eventNotification);

几个要注意的点： #

• 确保你的付款URL是公开可访问的，DocuSign服务器需要能正常访问它
• 如果你的网站用HTTPS，一定要确保证书有效，不然可能会跳转失败
• 先用DocuSign的沙箱环境测试整个流程，确认跳转和验证都正常后再切换到生产环境

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