开放文档API

第 1 步：(关键前提) 在云银签后台进行精细化配置

此方案的自动化能力高度依赖于您在云银签管理后台的预先配置：

• 模板管理配置:
  • 创建或编辑用于此场景的合同模板。
  • **获取模板编码 (`templateCode`)**: 登录云银签系统平台，点击左侧菜单栏的"模板管理"，您可以在模板列表中看到每个模板对应的"模板编码"。在调用API时，您可以使用此编码。
  • **定义签署方一 (您的企业或代表):** 明确其在此模板中是仅需 "签署"，还是需要先 "填写" 再 "签署"。
  • **定义签署方二 (买家/最终用户):** 明确其角色、是否需要 "填写" 和/或 "签署"。配置默认的收款金额（如果需要支付）。设置支付顺序（"先付后签" 或 "先签后付"）。
  • **配置组件和位置:** 如果设置了需要填写，需配置相应的表单组件。定义好签署方一、签署方二的签名/盖章区域，以及可能的骑缝章位置。
• 印章管理与授权 (实现签署方一自动盖章的关键):
  • 确保相关的企业印章（如公章、合同章、财务章）已创建（企业认证后会自动创建）。
  • 在印章管理中，**设置精确的印章授权规则**以实现自动盖章。操作路径一般为：登录云银签平台 -> 管理中心/企业管理 -> 印章管理 -> 选择需要授权的印章，点击"详情"或"授权管理" -> 新增授权。
  • 在新增授权时，你需要配置（通常如下图所示）：
    • **授权对象**: 可以是企业下的特定成员，或者全部成员（在API调用场景下，通常是指API调用者所代表的身份）。
    • **授权角色**: 选择"印章使用员"。
    • **授权范围**: 选择"指定模板"，然后选择本业务场景中使用的合同模板。
    • **有效期**: 设置一个合理的授权有效期。
    • **开启"自动落章"**: 开启此开关。开启后，当通过API使用此模板发起签署，并且轮到配置的签署方一（通常是您的企业）操作时，系统将根据授权规则自动完成盖章，无需人工手动操作。
  • 请参照您云银签后台的实际界面进行操作，上图仅为典型配置示例。关键是确保授权给正确的操作者、正确的模板，并启用了自动落章。
• 自动填写规则 (针对签署方一需要先填后签的场景):
  • 如果在模板中，签署方一（例如，您的企业代表）被设置为需要先"填写"再"签署"。
  • 在设计模板、配置填写控件（如文本框、日期选择器等）时，请注意每个控件都可以设置一个**控件编码 (componentKey)**。这个编码在模板设计界面的右下角属性配置区通常可以找到并自定义（例如，您可以将其设置为 "productName", "orderId", "buyerAddress" 等有意义的标识）。
  • 记录下这些 `componentKey`。在后续调用"模板发起"API时，如果将请求参数中的 autoFill 设置为 1，就可以通过 fillComponents 字段，传入这些 `componentKey` 和对应的预填值，从而实现自动填充签署方一需要填写的内容。
• 获取并记录配置好的模板 `templateId` 或 `templateCode`。

只有正确配置了印章的自动授权规则（并开启自动落章），且模板中签署方一被设置为无需手动填写（或通过API自动填写完成），系统才能在调用API后尽可能自动完成签署方一的盖章环节。

第 2 步：(核心) 调用"模板发起"专用 API

• 当您的后端收到前端购买请求后，首先调用云银签的"模板发起合同"接口。
• API 概览 (模板发起):

  • Endpoint: POST /signTask/startSignFlow
  • 描述: 基于预设模板创建合同流程。此API会根据模板配置和传入参数，尽可能自动处理内部环节（如发起方填写、盖章等，依赖于第1步的配置）。通过引入 flowType 参数，可以支持不同的签署方信息处理模式。
  • 重要 Header: appId, accessToken, userId (此 `userId` 通常是代表您系统操作的固定账号或管理员账号)
  • 详细API文档: 模板发起合同 API (如需查看错误码等更完整信息)
• 关于 flowType 参数的重要说明:

  此接口引入了 flowType 参数，用于定义合同流程的类型，特别是针对买家（签署方二）信息的处理方式：

  • flowType = 0 (正常签署流程):
    • 在此模式下，API调用方（您的后端服务）必须在 participantList 中为所有参与方（包括代表您系统的签署方一和最终买家签署方二）提供准确、最终的信息（如手机号、姓名）。
    • 云银签系统将使用这些信息直接生成合同。买家进入小程序后，信息不可更改，直接进行后续的查看、签署、支付等操作。
    • 适用于您的平台能够明确获取到买家信息的场景。
  • flowType = 2 (临时签署流程 / 买家信息后补):
    • 此模式专为优化用户体验和支持"匿名/未登录购买"等场景设计。
    • API 调用方在 participantList 中，仍需提供签署方一（例如，代表您系统的销售方）的准确信息。
    • 对于签署方二（最终买家），您可以传入临时的、占位的手机号和姓名（例如："张三", "18111111111"）。请注意：即使是占位信息，这两个字段也必须提供。
    • 云银签系统会将此合同标记为"临时状态"。当最终买家通过小程序链接进入并完成微信手机号授权后，云银签系统将自动使用授权获取到的真实手机号替换掉之前传入的临时买家手机号。在进行签署操作前，系统会引导买家完成实名认证，实名认证成功后，其认证的真实姓名将替换掉之前传入的临时买家姓名，并完善合同。
    • 这样可以避免用户在小程序授权后长时间等待合同生成，并允许用户在未登录状态下发起购买流程。

  请根据您的业务场景选择合适的 flowType 值。

• 请求参数 (Body) 详解:

  参数名	类型	必填	描述
  templateId	integer (int64)	是	模板ID (模板ID和模板编码二选一)
  templateCode	string	是	模板编码 (模板ID和模板编码二选一)
  templateName	string	否	模板名称 (用于最终流程标题，建议填写)
  flowType	integer (int32)	是	流程类型： 0 - 正常签署流程 (签署方信息需准确完整)。 2 - 临时签署流程 (签署方二信息可为占位符，将在小程序端授权和实名后自动更新)。
  privaryFlag	integer (int32)	否	模板是否保密 (0: 不保密, 1: 保密)
  encryptFlag	integer (int32)	否	是否加密合同 (0: 普通合同, 1: 加密合同)
  autoFill	integer (int32)	否	是否自动填写（0：否；1：是）。如果为1，且模板配置了发起方控件（签署方一），可以使用 fillComponents 预填内容。请参考第1步中关于"自动填写规则"的说明。
  +participantList	array of object	是	设置签署方。其中应至少包含代表您系统方（卖家）和最终用户（买家）两方的信息。参考 参与方实体类_1
  participantId	integer (int64)	是	参与方ID（参与方ID和参与方标识二选一）
  participantFlag	string	是	参与方标识，同一个模板中不可重复，例如甲方、乙方（参与方ID和参与方标识二选一）
  psnAccount	string	是	经办人手机
  psnName	string	是	经办人名称
  participantCorpName	string	否	参与方企业名称（个人类型时为空）
  payeeContractFlag	integer (int32)	否	是否需要收款（0：否；1：是）
  +payee	object	否	收款信息。参考 合同模板收款信息实体类_1
  id	integer (int64)	否	收款信息ID (修改时填写)
  amount	number	是	收款金额
  priority	integer (int32)	否	签署付款顺序(0：先付后签；1：先签后付)
  remark	string	否	收款备注说明
  +attachmentList	array of object	否	选填项设置.合同附件。参考 模板附件实体类
  attachmentId	integer (int64)	否	附件ID
  templateId	integer (int64)	否	模板ID (此附件关联的模板)
  fileName	string	否	文件名称
  fileUrl	string	否	文件地址 (上传后的URL)
  +fillComponents	array of object	否	控件填充信息 (当 autoFill 为1时使用)。参考 控件实体类
  componentId	integer (int64)	是	控件ID
  componentKey	string	是	控件key（控件ID和控件key二选一）
  componentValue	string	否	要填充的值
  sourceOrderCode	string	否	外部单号 (例如，您自己业务系统中的订单号)。如果提供，云银签系统会记录此单号，并在发起成功后的响应中原样返回。

• **请求 Body (JSON 示例):**

  {
  										"templateCode": "TP1374333375002752000", // (必填) 步骤1中获取的模板编码
  										"templateName": "测试自动落章12121", // (建议) 合同流程的标题
  										"flowType": 2, // (必填) 流程类型: 0-正常签署, 2-临时签署(买家信息后补)
  										"autoFill": 1, // (可选) 对于签署方一: 0-不自动填写, 1-自动填写 (需配合fillComponents)
  										"sourceOrderCode": "987654321", // (可选) 对接方系统内部的订单号
  										"participantList": [
  										{
  										"participantFlag": "签署方1", // 甲方/卖家 (信息需准确)
  										"psnAccount": "18675718757", // 签署方一经办人手机号
  										"psnName": "董新峰", // 签署方一经办人姓名
  										"participantCorpName": "云银签测试用租户" // (可选) 签署方一企业名称 (如果签署方一是企业)
  										// ... 其他甲方(卖家)信息，根据模板定义
  										},
  										{
  										"participantFlag": "签署方2", // 乙方/买家
  										// 当 flowType = 0 时, psnAccount 和 psnName 必须是买家真实准确的信息。
  										// 当 flowType = 2 时, psnAccount 和 psnName 必须提供，但可以是临时占位信息。
  										// 例如: "18111111111", "王麻子"。
  										// 后续会在小程序授权(更新手机号)和实名认证(更新姓名)后被系统自动更新。
  										"psnAccount": "18111111111", // 买家手机号 (flowType=2时可为占位)
  										"psnName": "王麻子", // 买家姓名 (flowType=2时可为占位)
  										"payeeContractFlag": 1, // (可选) 是否需要收款: 0-否, 1-是
  										"payee": { // (可选) 若 payeeContractFlag = 1, 则此项为收款信息
  										"amount": 100.00 // 收款金额
  										// ... 其他收款相关参数，如 priority, remark
  										}
  										// ... 其他买家信息
  										}
  										],
  										"fillComponents": [ // (可选) 当 autoFill = 1 且模板中签署方一有待填控件时使用
  										{
  										"componentKey": "name", // 对应模板中配置的控件编码
  										"componentValue": "刘浩" // 要填充的值
  										},
  										{
  										"componentKey": "code",
  										"componentValue": "a978050789"
  										}
  										]
  										// ... 其他参数如 privaryFlag, encryptFlag, attachmentList 等
  										}

• **处理 API 响应:**
  • API成功调用后，您将收到包含 flowId (新创建的合同流程ID) 以及完整的参与方列表 participantList 的响应。如果您的请求中包含了 sourceOrderCode，响应的 data 中通常也会包含此字段。
  • 您需要从响应的 data.participantList 中，根据您传入的买家信息（例如手机号或 `participantFlag`，即使是临时的），找到代表**买家**的那一项，并获取其 participantId。这个 `participantId` 在下一步至关重要。
  • 特别注意 (针对 flowType = 2): 即便买家信息是临时的，此步骤仍会返回一个有效的 participantId 给该买家。后续买家在小程序授权更新信息后，其身份信息会与此 participantId 关联更新。
• 响应参数 (data 部分) 详解:

  参数名	类型	描述
  flowId	integer (int64)	创建成功的签署流程ID。
  sourceOrderCode	string	如果您在请求中传入了外部单号，这里会原样返回。
  flowStatus	integer (int32)	流程状态: 0-草稿; 1-签署中; 2-完成; 3-撤销; 5-过期; 6-拒签。
  flowDesc	string	签署流程描述。
  flowTitle	string	流程标题。
  nextStatus	integer (int32)	当前用户下步骤可以操作的状态:(0:查看; 1:填写; 2:签署)。
  +participantList	array of object	签署方信息列表。您需要从此列表中找到买家的 participantId。参考 签署人信息_1
  participantId	integer (int64)	签署人信息ID
  participantFlag	string	参与方标识
  signStatus	integer (int32)	当前签署状态: 1-填写中; 2-签署中; 3-已签署; 4-等待审批; 5-已拒签
  participantCorpId	integer (int64)	企业id（个人类型时为空）
  participantCorpName	string	企业名称（个人类型时为空）
  participantType	integer (int32)	参与方类型 1-企业 0-个人
  participateBizType	array of string	参与方式：1-填写 2-签署；用英文逗号分隔
  psnId	integer (int64)	企业经办人账号ID
  psnName	string	经办人名称
  payeeContractFlag	integer (int32)	是否需要收款（0：否；1：是）
  +payee	object	签署人支付信息。参考 签署人支付信息
  id	integer (int64)	收款信息ID
  amount	number	收款金额
  payeeStatus	integer (int32)	收款支付状态（0：未支付；1：已支付）
  auditStatus	integer (int32)	收款审批状态（0：未审批；1：已审批）
  priority	integer (int32)	签署付款顺序(0：先付后签；1：先签后付)
  remark	string	收款备注说明

• 示例响应 (来自 `/signTask/startSignFlow`):

  {
  										"code": "200",
  										"msg": "成功",
  										"data": {
  										"flowId": 12001,
  										"flowStatus": 0, // 或 1，取决于流程配置
  										"flowTitle": "在线课程购买合同",
  										// ...其他流程信息...
  										"participantList": [
  										{
  										"participantId": 20101, // 卖家/甲方的 participantId
  										"participantFlag": "甲方",
  										"psnName": "系统销售代表",
  										// ...
  										},
  										{
  										"participantId": 20102, // 这是您需要提取的买家的 participantId
  										"participantFlag": "乙方",
  										"psnName": "买家姓名",
  										// ...
  										}
  										]
  										}
  										}

第 3 步：调用"获取小程序跳转链接" API

• 拿到上一步返回的 `flowId` 和买家的 `participantId` 后，您的后端服务紧接着调用 `/signTask/contract/appletForParticipant` 接口来获取小程序跳转链接。
• API 概览 (获取小程序链接):

  • Endpoint: POST /signTask/contract/appletForParticipant
  • 描述: 根据合同参与方ID，获取其进行下一步操作（通常是签署或支付）的小程序跳转链接。
  • 重要 Header: appId, accessToken, userId (代表您系统操作的账号)
• 请求参数 (Body) 详解:

  参数名	类型	必填	描述
  participantId	integer (int64)	是	买家的参与方ID (从上一步 /signTask/startSignFlow 响应的 data.participantList 中获取)。
  type	integer (int32)	是	小程序类型：0-微信小程序，1-支付宝小程序。

• **请求 Body (JSON 示例):**

  {
  										"participantId": 20102, // (必填) 从上一步获取的买家的 participantId
  										"type": 0 // (必填) 类型：0-微信小程序，1-支付宝小程序
  										}

• 此API会返回一个直接指向微信或支付宝小程序的链接。

第 4 步：处理 API 响应，获取小程序链接

• 如果 `/signTask/contract/appletForParticipant` API 调用成功，您将收到类似以下的响应：
• 关键响应参数 (来自 /appletForParticipant):

  • data: 小程序链接。
• 响应参数 (data 部分) 详解:

  参数名 (Map中的Key)	类型	描述
  data	string	直接给买家使用的小程序跳转链接。

• 成功响应 Body 示例 (JSON):

  {
  										"code": "200",
  										"msg": "成功",
  										"data": "weixin://dl/business/"
  										//或者"https://ds.alipay.com/?scheme=alipays%3A%2F%2Fplatformapi%2Fstartapp%"
  										}

• 您需要从 `data` 中提取小程序跳转链接。

第 5 步：前端引导用户跳转小程序

• 您的后端将获取到的 `miniProgramUrl` 返回给前端 App 或 H5 页面。
• 前端通过按钮点击、链接跳转或平台能力（如 App SDK）引导用户打开此小程序链接。

第 6 步：用户在小程序操作 & 处理回调

• 用户在云银签小程序中完成合同查看、签名、支付等操作。
• 操作完成后，小程序会携带结果参数跳转回您在第 2 步指定的 `redirectUrl`。
• 请参考 标准集成模式 - 处理回调 部分的说明，在您的回调页面解析参数，向用户展示结果，并**强烈建议您的后端再次调用合同查询 API 确认最终状态**。
• 建议后端确认状态 API:

  • Endpoint: POST /signTask/detail (查看详情)
  • 描述: 查询合同流程的详细信息和各方状态。
  • 重要 Header: appId, accessToken, userId (系统操作员/管理员)
  • 关键请求参数: signFlowId (从回调参数或第3步响应获取)