如何通过DocuSign模板与docusign_esign Python SDK实现带见证人的嵌入式签署

我之前在使用DocuSign Python SDK开发嵌入式签署功能时，也碰到过一模一样的见证人配置问题，折腾了好一阵才搞清楚正确的姿势，给你详细梳理下：

首先明确核心逻辑 #

见证人在DocuSign里是被动角色，不需要预先指定身份，而是由主签署者在签署过程中现场指定（输入姓名、邮箱）。这和普通签署者的配置逻辑完全不同，所以不能用TemplateRole来预先添加见证人。

正确实现步骤 #

1. 先确认模板的见证人配置 #

在DocuSign模板编辑界面，务必确保：

• 添加的角色类型是见证人（不是普通签署者）
• 给见证人角色关联了对应的标签（比如姓名、邮箱输入框），这些标签会在签署时让主签署者填写

2. 创建信封时的关键配置 #

创建EnvelopeDefinition时，必须开启allow_witnessing参数，同时不要把见证人加入template_roles列表，只添加主签署者的角色即可：

from docusign_esign import EnvelopeDefinition, TemplateRole, ApiClient

# 初始化API客户端
api_client = ApiClient()
api_client.set_default_header("Authorization", "Bearer YOUR_ACCESS_TOKEN")

# 构建信封定义
envelope_def = EnvelopeDefinition(
    template_id="YOUR_TEMPLATE_ID",
    status="sent",
    allow_witnessing=True  # 必须开启这个参数，否则见证人功能不生效
)

# 仅添加主签署者的TemplateRole
main_signer = TemplateRole(
    email="signer_email@example.com",
    name="Main Signer Name",
    role_name="YOUR_TEMPLATE_SIGNER_ROLE_NAME"  # 对应模板里的主签署者角色名
)
envelope_def.template_roles = [main_signer]

# 创建信封
envelopes_api = api_client.api_client.EnvelopesApi()
envelope_summary = envelopes_api.create_envelope(
    account_id="YOUR_ACCOUNT_ID",
    envelope_definition=envelope_def
)

3. 生成嵌入式签署URL #

这一步和普通嵌入式签署的流程一致，确保主签署者的信息和TemplateRole匹配即可：

from docusign_esign import RecipientViewRequest

recipient_view_req = RecipientViewRequest(
    authentication_method="email",
    email="signer_email@example.com",
    name="Main Signer Name",
    return_url="https://your-app-domain.com/sign-complete",
    client_user_id="YOUR_UNIQUE_CLIENT_ID"  # 嵌入式签署必填的客户端标识
)

# 获取签署URL
signing_url = envelopes_api.create_recipient_view(
    account_id="YOUR_ACCOUNT_ID",
    envelope_id=envelope_summary.envelope_id,
    recipient_view_request=recipient_view_req
)

常见错误排查 #

• 模板角色类型错误：如果把见证人设成了普通签署者，系统会要求你预先指定该角色的收件人，而不是让主签署者现场指定
• 未开启allow_witnessing：这个参数是触发见证人流程的开关，默认是关闭状态，必须显式设为True
• 信封状态错误：确保信封状态是sent，而不是created，否则嵌入式签署界面可能不会加载完整的流程

按照这个配置，主签署者进入签署界面完成自己的签署步骤后，系统会自动弹出界面让他们输入见证人的姓名和邮箱，之后见证人会收到签署邀请（如果是现场见证，也可以直接在同一设备上完成见证流程）。

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