如何通过Docusign API将Salesforce对象字段数据传入模板及创建动态模板

一、先在DocuSign模板中配置可映射的字段标签 #

• 在DocuSign后台创建/编辑模板时，添加文本标签（Text Tab），为每个需要填充Salesforce数据的标签设置唯一的tabLabel（例如Account_Name、Opportunity_Amount）。
• 根据需求设置标签属性：如果不需要签署人修改，将标签设为「只读」或「预填充」模式。

二、通过Envelope API传递Salesforce数据 #

你已经能发送模板，现在只需在创建信封的API请求中，把Salesforce查询到的字段值映射到模板的标签上即可。

核心请求结构（JSON示例） #

调用POST /v2.1/accounts/{accountId}/envelopes接口，请求体中需包含templateRoles下的tabs字段：

{
  "status": "sent",
  "templateId": "你的DocuSign模板ID",
  "templateRoles": [
    {
      "email": "签署人邮箱",
      "name": "签署人姓名",
      "roleName": "模板中定义的角色名",
      "tabs": {
        "textTabs": [
          {
            "tabLabel": "Account_Name",
            "value": "Acme科技有限公司" // 从Salesforce Account.Name查询得到
          },
          {
            "tabLabel": "Account_BillingCity",
            "value": "上海市" // 从Salesforce Account.BillingCity查询得到
          },
          {
            "tabLabel": "Opportunity_Amount",
            "value": "¥12000.00" // 从Salesforce Opportunity.Amount格式化后得到
          }
        ]
      }
    }
  ]
}

Salesforce端代码逻辑（Apex示例片段） #

// 1. 查询Salesforce对象数据
Account acc = [SELECT Name, BillingCity FROM Account WHERE Id = :accountId LIMIT 1];
Opportunity opp = [SELECT Amount FROM Opportunity WHERE Id = :opportunityId LIMIT 1];

// 2. 构造DocuSign API请求体
Map<String, Object> envelopeRequest = new Map<String, Object>{
    'status' => 'sent',
    'templateId' => 'YOUR_TEMPLATE_ID',
    'templateRoles' => new List<Object>{
        new Map<String, Object>{
            'email' => 'signer@example.com',
            'name' => '张三',
            'roleName' => '客户签署人',
            'tabs' => new Map<String, Object>{
                'textTabs' => new List<Object>{
                    new Map<String, Object>{'tabLabel' => 'Account_Name', 'value' => acc.Name},
                    new Map<String, Object>{'tabLabel' => 'Account_BillingCity', 'value' => acc.BillingCity},
                    new Map<String, Object>{'tabLabel' => 'Opportunity_Amount', 'value' => '¥' + String.valueOf(opp.Amount)}
                }
            }
        }
    }
};

// 3. 发送HTTP请求到DocuSign API（此处省略认证和HTTP调用逻辑）

三、关于「动态调用Salesforce数据的模板」的说明 #

DocuSign模板本身无法直接读取Salesforce数据，所有动态数据必须通过API在创建信封时传递。但可以通过以下方式实现类似动态模板的效果：

• 提前创建通用模板，预留所有可能用到的tabLabel，发送时仅填充当前业务需要的字段，未使用的标签可通过API设置"hidden": true隐藏。
• 在Salesforce中封装通用工具类，接收对象ID、字段映射关系（比如{'Account_Name' => 'Name', 'Opportunity_Amount' => 'Amount'}），自动查询数据、格式化并构造DocuSign请求，实现不同场景的快速复用。

四、注意事项 #

• 确保DocuSign API的认证流程（JWT/OAuth）在Salesforce代码中正确实现，避免权限不足导致请求失败。
• 对日期、金额等字段做格式化处理，保证在DocuSign模板中显示符合预期。
• 测试时可先用DocuSign API Explorer构造请求验证数据填充效果，再移植到Salesforce代码中。

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