使用DocuSign Composite Template API添加见证人创建信封时出错

错误码WITNESS_FOR_SIGNER_ID_INVALID的核心原因是见证人的关联签署人ID配置无效。从错误信息来看，DocuSign识别到的见证者内部ID为4，但关键问题出在请求体中witnesses对象的witnessFor字段：你设置了witnessFor: 2，但当前复合模板的signers列表里，没有recipientId为2的签署人——现有签署人的recipientId分别是f51aeab9ab1dfe21fbc45b4c74e6d73b（Customer）和3（Manager）。witnessFor必须指向信封内已存在的某个签署人的recipientId，否则会触发该错误。

1. 修正witnessFor字段值 #

将witnessFor改为你想要关联的签署人的recipientId：

• 如果要让见证人关联Customer，设置witnessFor: "f51aeab9ab1dfe21fbc45b4c74e6d73b"
• 如果关联Manager，设置witnessFor: "3"

2. 清理冗余字段 #

• 移除见证人的status: "created"，该状态由DocuSign自动维护，手动设置会导致冲突
• 简化roleName，无需包含长串数字，比如改为"roleName": "Witness"即可

修正后的witnesses代码示例（关联Manager） #

"witnesses": [
  {
    "email": "witness@sample.com",
    "name": "Witness 1",
    "recipientId": "2",
    "roleName": "Witness",
    "routingOrder": "2",
    "witnessFor": "3",
    "recipientType": "witness",
    "tabs": {
      "signHereTabs": [
        {
          "documentId": "2",
          "pageNumber": "1",
          "anchorXOffset": "50",
          "anchorYOffset": "-15",
          "anchorString": "Witness Signature",
          "anchorUnits": "pixels",
          "required": "true"
        }
      ],
      "textTabs": [
        {
          "documentId": "2",
          "pageNumber": "1",
          "anchorXOffset": "50",
          "anchorYOffset": "-15",
          "anchorString": "Witness Name",
          "anchorUnits": "pixels",
          "required": "true",
          "value": "Akhil"
        }
      ]
    }
  }
]

• recipientId在整个信封内必须唯一，当前见证人recipientId=2符合要求，无需修改
• 见证人不支持clientUserId，不能设置为嵌入式签署人，只能通过邮件邀请完成操作
• 确保锚点字符串（如Witness Signature）在对应文档中存在，否则标签无法正确定位

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