如何从DocuSign API响应中获取非空的recipient_signing_uri？

问题 #

尝试从DocuSign API响应中获取recipient_signing_uri，但返回值为null。相关代码如下：

public function send(Request $request): object
{
   
    $apiClient = new ApiClient();
    $apiClient->getOAuth()->setOAuthBasePath(env('DS_AUTH_SERVER'));
    try {
        $accessToken = $this->getToken($apiClient);
    } catch (\Throwable $th) {
        return back()->withError($th->getMessage())->withInput();
    }
   
    $userInfo = $apiClient->getUserInfo($accessToken);
    $accountInfo = $userInfo[0]->getAccounts();
    $apiClient->getConfig()->setHost($accountInfo[0]->getBaseUri() . env('DS_ESIGN_URI_SUFFIX'));
    
    $envelopeDefenition = $this->buildEnvelope($request);
    try {
        $envelopeApi = new EnvelopesApi($apiClient);
        $result = $envelopeApi->createEnvelope($accountInfo[0]->getAccountId(), $envelopeDefenition);
        dd($result);
    } catch (\Throwable $th) {
        return back()->withError($th->getMessage())->withInput();
    }
    return view('backend.response')->with('result', $result);
}

打印$result得到的响应：

container: array:8 [
    "bulk_envelope_status" => null
    "envelope_id" => "b634f8c5-96c5-4a18-947f-59418d8c4e03"
    "error_details" => null
    "recipient_signing_uri" => null
    "recipient_signing_uri_error" => null
    "status" => "sent"
    "status_date_time" => "2023-02-16T07:24:39.1570000Z"
    "uri" => "/envelopes/b634f8c5-96c5-4a18-947f-59418d8c4e03"
  ]

希望获取recipient_signing_uri的有效值，该如何实现？

解决方案 #

1. 校验信封定义中的收件人配置 #

recipient_signing_uri仅在特定场景下返回：

• 信封需配置为嵌入式即时签名，而非邮件发送模式。
• 收件人对象必须包含client_user_id属性，用于标识该收件人支持嵌入式签名。

确保buildEnvelope方法里的收件人配置包含该字段，示例：

$signer = new Signer([
    'email' => 'recipient@example.com',
    'name' => 'Recipient Name',
    'recipient_id' => '1',
    'client_user_id' => 'unique-client-id' // 必填，标识嵌入式收件人
]);

2. 调用createRecipientView接口获取签名链接 #

若信封状态为sent（已通过邮件发送），createEnvelope响应不会返回recipient_signing_uri，此时需调用createRecipientView接口生成专属签名链接。

示例代码：

// 创建信封后，构造RecipientViewRequest
$recipientViewRequest = new RecipientViewRequest([
    'authentication_method' => 'email',
    'client_user_id' => 'unique-client-id', // 需与信封定义中的值一致
    'recipient_id' => '1',
    'return_url' => 'https://your-domain.com/sign-complete', // 签名完成后的跳转地址
    'email' => 'recipient@example.com',
    'user_name' => 'Recipient Name'
]);

// 调用接口获取签名链接
$envelopeApi = new EnvelopesApi($apiClient);
$viewResponse = $envelopeApi->createRecipientView(
    $accountInfo[0]->getAccountId(),
    $result->getEnvelopeId(),
    $recipientViewRequest
);

// 有效签名链接为$viewResponse->getUrl()

3. 匹配信封状态与获取方式 #

• 若信封状态是sent，必须通过createRecipientView获取签名链接，createEnvelope不会返回recipient_signing_uri。
• 仅当信封配置为嵌入式即时签名，且收件人带有client_user_id时，createEnvelope响应才会包含recipient_signing_uri。

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