如何通过API暂停从Docusign模板创建的信封？新增workflow_step报错

问题原因 #

你遇到的报错核心是两个配置冲突：

• 通过模板生成信封时，API默认会复用模板内置的工作流规则，你在信封定义中额外追加的workflow配置会被判定为非法修改，无法生效
• 你将信封status直接设置为sent，工作流的暂停规则需要在信封发送前完成配置确认，直接发送时API无法及时校验追加的工作流步骤，也会触发错误

可行解决方案 #

方案1：先创建草稿信封，再更新工作流后发送 #

不要在初始化EnvelopeDefinition时直接设置status为sent，也不要直接在信封定义里加workflow，按以下步骤调整：

1. 初始化信封定义时将status设为created，先调用API生成草稿信封
2. 调用Envelopes:update接口为草稿信封添加你定义的暂停工作流配置
3. 再次调用更新接口把信封status改为sent触发发送

对应代码调整示例：

# 第一步：创建草稿信封
envelope_definition = DocuSign_eSign::EnvelopeDefinition.new({
    status: 'created', # 修改为草稿状态，不要直接发送
    templateId: template_id
})
# 模板角色部分的代码保持不变
signer1 = DocuSign_eSign::TemplateRole.new({
    email: signer1_email,
    name: signer1_name,
    roleName: 'signer1',
    clientUserId: signer_client_id,
    recipientId: 1,
    routingOrder: 1
})                                              
signer2 = DocuSign_eSign::TemplateRole.new({
    email: signer2_email,
    name: signer2_name,
    roleName: 'signer2',
    recipientId: 2,
    routingOrder: 2
})
envelope_definition.template_roles = [signer1, signer2]  

# 调用创建信封接口拿到信封ID
envelope = envelopes_api.create_envelope(account_id, envelope_definition)
envelope_id = envelope.envelope_id

# 第二步：给草稿信封追加工作流配置
workflow_step = DocuSign_eSign::WorkflowStep.new(
  action: 'pause_before',
  triggerOnItem: 'routing_order',
  itemId: 2
)
workflow = DocuSign_eSign::Workflow.new(workflowSteps: [workflow_step])
update_envelope_def = DocuSign_eSign::EnvelopeDefinition.new(workflow: workflow)
envelopes_api.update_envelope(account_id, envelope_id, update_envelope_def)

# 第三步：发送信封
send_envelope_def = DocuSign_eSign::EnvelopeDefinition.new(status: 'sent')
envelopes_api.update_envelope(account_id, envelope_id, send_envelope_def)

方案2：直接在模板中预配置暂停工作流 #

你可以直接通过API给UI创建的模板添加工作流步骤，之后从该模板生成的所有信封都会自动复用这个暂停规则，不需要每次生成信封时单独配置：

# 给指定模板添加固定暂停工作流
workflow_step = DocuSign_eSign::WorkflowStep.new(
  action: 'pause_before',
  triggerOnItem: 'routing_order',
  itemId: 2
)
template_workflow = DocuSign_eSign::Workflow.new(workflowSteps: [workflow_step])
template_def = DocuSign_eSign::EnvelopeTemplate.new(workflow: template_workflow)
templates_api.update_template(account_id, template_id, template_def)

暂停恢复操作说明 #

工作流触发暂停后，你可以调用Envelopes:update_workflow_step接口，把对应步骤的action改为resume即可恢复信封流转到第二位签署人。

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