如何通过DocuSign API生成合同与电子签名？求PHP集成方案

核心依赖安装 #

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

composer require docusign/esign-client

基础配置与授权 #

创建配置文件（如docusign_config.php），填入你的账号信息：

<?php
$config = [
    'client_id' => '你的集成密钥',
    'client_secret' => '你的客户端密钥',
    'account_id' => '你的DocuSign账号ID',
    'base_path' => 'https://demo.docusign.net/restapi', // 测试环境，生产环境替换为https://www.docusign.net/restapi
    'redirect_uri' => '你的回调URL'
];
?>

授权流程（获取访问令牌） #

<?php
require 'vendor/autoload.php';
require 'docusign_config.php';

$apiClient = new DocuSign\eSign\ApiClient($config['base_path']);
$oauth = $apiClient->getOAuth();

// 生成授权URL
$authUrl = $oauth->getAuthorizationUri(
    $config['client_id'],
    ['signature'],
    $config['redirect_uri'],
    'code'
);

// 实际项目中用header跳转至授权页面
echo '<a href="' . $authUrl . '">授权DocuSign访问</a>';

// 回调页面获取并保存令牌
if (isset($_GET['code'])) {
    $tokenInfo = $oauth->generateAccessToken(
        $config['client_id'],
        $config['client_secret'],
        'authorization_code',
        $_GET['code'],
        $config['redirect_uri']
    );
    $_SESSION['access_token'] = $tokenInfo[0]['access_token'];
}
?>

创建并发送签名请求示例 #

以下是生成合同并发送给签署人的完整代码：

<?php
require 'vendor/autoload.php';
require 'docusign_config.php';

$apiClient = new DocuSign\eSign\ApiClient($config['base_path']);
$apiClient->setAccessToken($_SESSION['access_token']);

// 定义信封
$envelopeDefinition = new DocuSign\eSign\Model\EnvelopeDefinition();
$envelopeDefinition->setEmailSubject('请签署这份合同');

// 添加本地PDF文档
$document = new DocuSign\eSign\Model\Document();
$document->setDocumentBase64(base64_encode(file_get_contents('合同文件.pdf')));
$document->setName('合同文件.pdf');
$document->setDocumentId('1');
$envelopeDefinition->setDocuments([$document]);

// 添加签署人
$signer = new DocuSign\eSign\Model\Signer();
$signer->setEmail('签署人邮箱@example.com');
$signer->setName('签署人姓名');
$signer->setRecipientId('1');
$signer->setClientUserId('123'); // 嵌入式签署必填参数

// 设置签署位置标签
$signHere = new DocuSign\eSign\Model\SignHere();
$signHere->setDocumentId('1');
$signHere->setPageNumber('1');
$signHere->setRecipientId('1');
$signHere->setXPosition('100');
$signHere->setYPosition('100');

$tabs = new DocuSign\eSign\Model\Tabs();
$tabs->setSignHereTabs([$signHere]);
$signer->setTabs($tabs);

// 绑定收件人到信封
$recipients = new DocuSign\eSign\Model\Recipients();
$recipients->setSigners([$signer]);
$envelopeDefinition->setRecipients($recipients);

// 设置信封状态为发送
$envelopeDefinition->setStatus('sent');

// 调用API发送信封
$envelopesApi = new DocuSign\eSign\Api\EnvelopesApi($apiClient);
$envelopeSummary = $envelopesApi->createEnvelope($config['account_id'], $envelopeDefinition);

echo '信封已发送，ID：' . $envelopeSummary->getEnvelopeId();
?>

嵌入式签署页面生成 #

若需在自有网站内展示签署页面，而非跳转至DocuSign：

<?php
// 基于上面的代码，获取envelopeId后执行
$recipientViewRequest = new DocuSign\eSign\Model\RecipientViewRequest();
$recipientViewRequest->setReturnUrl('签署完成后的回调URL');
$recipientViewRequest->setAuthenticationMethod('email');
$recipientViewRequest->setEmail('签署人邮箱@example.com');
$recipientViewRequest->setUserName('签署人姓名');
$recipientViewRequest->setClientUserId('123'); // 需与之前signer的clientUserId一致

$viewUrl = $envelopesApi->createRecipientView($config['account_id'], $envelopeSummary->getEnvelopeId(), $recipientViewRequest);

// 跳转至嵌入式签署页面
header('Location: ' . $viewUrl->getUrl());
exit;
?>

常见问题排查 #

• 令牌过期：使用刷新令牌重新获取访问令牌，参考SDK中generateAccessToken方法的refresh_token参数
• 文档上传失败：确保PDF文件已转base64编码，且文件大小未超出平台限制
• 签署位置错误：调整X/Y坐标和页码，可先在DocuSign测试环境的模板编辑器中确认位置

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