Docusign REST API -复合模板错误

Docusign REST API 复合模板错误解析

基础概念

DocuSign REST API 的复合模板(Composite Templates)功能允许开发者将多个模板组合在一起形成一个完整的文档包。这种功能特别适用于需要动态组合多个模板或文档的场景。

常见复合模板错误类型及原因

1. 模板ID无效错误

原因：提供的模板ID不存在或没有访问权限
解决方案：
- 确认模板ID是否正确
- 确保API调用账户有访问该模板的权限

2. 服务器模板与内联模板冲突

原因：同时提供了服务器模板和内联模板，但配置不正确
解决方案：
- 确保每个复合模板部分只使用一种模板类型(服务器模板或内联模板)
- 检查文档顺序是否正确

3. 角色映射错误

原因：模板中的角色与API调用中提供的收件人不匹配
解决方案：
- 确保所有模板角色都被正确映射到收件人
- 检查角色名称是否完全匹配(包括大小写)

4. 文档顺序问题

原因：多个模板的文档顺序冲突
解决方案：
- 明确指定每个文档的documentId和顺序
- 使用sequence参数控制文档顺序

5. 签名位置冲突

原因：多个模板中的签名标签(tabs)位置重叠
解决方案：
- 检查并调整签名标签的坐标位置
- 使用不同的documentId和pageNumber来避免重叠

正确使用复合模板的示例代码

{
  "compositeTemplates": [
    {
      "serverTemplates": [
        {
          "sequence": "1",
          "templateId": "模板ID1"
        }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "email": "signer1@example.com",
                "name": "Signer One",
                "recipientId": "1",
                "roleName": "Signer"
              }
            ]
          }
        }
      ]
    },
    {
      "serverTemplates": [
        {
          "sequence": "3",
          "templateId": "模板ID2"
        }
      ],
      "inlineTemplates": [
        {
          "sequence": "4",
          "recipients": {
            "signers": [
              {
                "email": "signer1@example.com",
                "name": "Signer One",
                "recipientId": "1",
                "roleName": "Signer",
                "tabs": {
                  "signHereTabs": [
                    {
                      "documentId": "2",
                      "pageNumber": "1",
                      "xPosition": "100",
                      "yPosition": "200"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "status": "sent"
}