如何通过Python设置DocuSign预填充字段值并修复400接口报错

报错根因 #

• 标签挂载位置错误：使用模板发送信封时，tabs配置不能直接放在EnvelopeDefinition对象下，该层级仅支持无模板、直传文档的自定义标签场景。所有模板内标签的赋值（包括预填充标签）必须绑定到具体的TemplateRole对象上，否则API无法识别传入的字段值，会将模板中标记为必填的未赋值字段判定为不完整，抛出REQUIRED_TAB_INCOMPLETE错误。
• SDK参数名错误：docusign_esign包的Python接口使用小写下划线命名规范，实例化Tabs对象时传入预填充标签的参数名应为prefill_tabs，原代码使用大驼峰格式的PrefillTabs会导致参数解析失败，传入的字段值直接丢失。
• 传参遗漏：原代码create_and_send_envelope方法调用make_envelope_definition时未透传CC相关参数，会导致抄送人配置失效。

修正后可运行代码 #

from docusign_esign import Text, PrefillTabs, Tabs, EnvelopeDefinition, TemplateRole

def create_and_send_envelope(
        self, template_id, signer_email, signer_name, cc_email=None, cc_name=None):
    envelope_definition = self.make_envelope_definition(
        template_id, signer_email, signer_name, cc_email, cc_name
    )

    result = self.envelope_api.create_envelope(
        self.account_id, envelope_definition=envelope_definition
    )
    return result


def make_envelope_definition(
        self, template_id, signer_email, signer_name, cc_email=None, cc_name=None):
    """
    创建信封定义
    """
    # 定义预填充字段，tab_label必须和模板中配置的Data Label完全一致，大小写敏感
    text_tab1 = Text(tab_label="serviceAddress", value="testValue")
    prefill_tabs = PrefillTabs(text_tabs=[text_tab1])
    tabs = Tabs(prefill_tabs=prefill_tabs)

    # 初始化签名人角色，预填充标签直接绑定到任意已定义的角色即可，不会开放编辑权限给该角色
    signer = TemplateRole(
        email=signer_email,
        name=signer_name,
        role_name='Customer',
        tabs=tabs
    )

    roles = [signer]
    # 初始化抄送人角色
    if cc_email and cc_name:
        cc = TemplateRole(
            email=cc_email,
            name=cc_name,
            role_name='cc'
        )
        roles.append(cc)

    # 构建信封定义，不需要在EnvelopeDefinition层级传入tabs参数
    envelope_definition = EnvelopeDefinition(
        status="sent",
        template_id=template_id,
        template_roles=roles
    )
    return envelope_definition

关键说明 #

• 预填充字段（Prefill Tabs）本身默认对所有签名人只读，绑定到签名人角色下仅为了满足API传值的格式要求，不会改变字段的只读属性，完全符合预填充字段不可编辑的业务要求。
• 每次发信需要动态修改字段值时，只需要修改对应Text对象的value参数即可，不需要调整模板配置。
• 若后续新增其他预填充文本字段，直接在PrefillTabs的text_tabs列表中追加对应Text对象即可，需保证tab_label和模板内配置的字段标签完全匹配。

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