为Word文档添加DocuSign锚点标签失败及权限问题排查

一、签名标签不显示的原因及修复 #

你的代码存在两个核心错误，直接导致锚点签名标签无法生成：

1. Tabs层级错误
   DocuSign API要求签名标签必须嵌套在对应签署人的对象内部，而你把tabs放在了信封的根节点，这部分配置会被API直接忽略，标签自然不会生成。

2. 参数拼写错误
   代码里的anchorXOffest和anchorYOffest拼写有误，正确的参数名是anchorXOffset和anchorYOffset（注意是Offset，多一个t），拼写错误会让锚点定位规则失效。

另外还有两个需要排查的潜在问题：

• 确认Word文档里的//SIGN_HERE//是纯文本，没有隐藏格式、额外空格或特殊字符，否则DocuSign无法识别锚点。
• 对于Word文档，建议把anchorUnits设为"inches"或"mms"，而非"pixels"——Word的排版逻辑更适配物理单位，像素容易导致定位偏差。

修复后的完整代码：

payload = json.dumps({
    'documents': [
        {
            'documentBase64': f'{encodedFile}',
            'documentId': '123',
            'fileExtension': 'docx',
            'name': 'test document'
        }
    ],
    'emailSubject': 'email subject',
    'recipients': {
        'signers': [
            {
                'email': 'example@example.com',
                'name': 'John Doe',
                'recipientId': '1',
                'routingOrder': '1',
                # 将tabs移到签署人对象内部
                'tabs': {
                    'signHereTabs': [
                        {
                            'accessibility': 'None',
                            'anchorString': '//SIGN_HERE//',
                            'anchorUnits': 'inches',
                            'anchorXOffset': '0',  # 修正拼写
                            'anchorYOffset': '0',  # 修正拼写
                            'name': 'Please Sign Here',
                            'recipientId': '1',
                            'tabLabel': 'signHere'
                        }
                    ]
                }
            }
        ]
    },
    'status': 'sent'
})

二、关闭收件人拖拽添加字段的功能 #

要禁用收件人在签署界面拖拽添加字段的权限，只需在签署人对象中添加canEditTabs: false参数：

{
    'email': 'example@example.com',
    'name': 'John Doe',
    'recipientId': '1',
    'routingOrder': '1',
    'canEditTabs': False,  # 关闭拖拽添加字段功能
    'tabs': {
        # 签名标签配置...
    }
}

如果要对整个信封的所有收件人统一禁用该功能，也可以在信封根节点添加全局设置：

'settings': {
    'allowRecipientsToAddTabs': False
}

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