DocuSign API：为嵌入式收件人（Captive Recipient）指定已有签名图片

刚好做过类似的DocuSign集成场景，给你梳理下具体的实现步骤，核心是先清理默认生成的Captive Recipient签名，再在信封创建时绑定已有signatureId：

步骤1：删除Captive Recipient的默认签名图片 #

因为嵌入式签署者属于Captive Recipient范畴，DocuSign会自动为其生成默认签名，所以第一步要先删除这个默认签名，避免后续冲突。

你需要先通过Accounts: listCaptiveRecipients接口，根据clientUserId找到对应的captiveRecipientId（这个ID是DocuSign为该嵌入式签署者生成的唯一标识）。然后调用Accounts: deleteCaptiveRecipient接口删除默认签名：

DELETE /v2.1/accounts/{accountId}/captive_recipients/{captiveRecipientId}

注意：这个操作会清除该Captive Recipient的所有默认签名和初始化信息，确保后续可以绑定自定义签名。

步骤2：创建信封时指定已有signatureId #

在创建信封的请求体中，定义签署者（signer）对象时，直接添加signatureId字段，将其值设置为用户已有的签名ID。同时确保clientUserId正确配置（和之前关联的一致）。

示例签署者配置片段：

{
  "email": "signer@example.com",
  "name": "John Doe",
  "clientUserId": "your_unique_client_user_id",
  "recipientId": "1",
  "signatureId": "your_existing_signature_id",
  "tabs": {
    "signHereTabs": [
      {
        "documentId": "1",
        "pageNumber": "1",
        "xPosition": "100",
        "yPosition": "100"
      }
    ]
  }
}

这里的signatureId必须是该用户在DocuSign账号下已存在的有效签名ID，你可以通过Accounts: listSignatures或Accounts: getSignatureImage接口获取用户的已有签名列表及对应的ID。

步骤3：生成嵌入式签署URL #

正常调用Envelopes: createRecipientView接口生成签署链接，当用户通过该链接进入签署页面时，系统会自动加载你指定的signatureId对应的签名图片，而不会再生成新的默认签名。

关键注意事项 #

• 确保signatureId属于当前签署者的DocuSign账号，不能跨用户使用。
• 删除Captive Recipient的操作必须在创建信封之前完成，否则新生成的默认签名会覆盖你指定的签名。
• 如果之前已经为该clientUserId创建过嵌入式签署信封，一定要先通过listCaptiveRecipients找到对应的captiveRecipientId再执行删除，避免误删其他用户的信息。

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