跳到主要内容

合同相关回调

一. 合同状态变动通知​

1. 回调触发时机​

在合同的发起，个人签署，企业签署等各个状态变化时

2. 回调消息类型​

FlowStatusChange

3. 其他说明​

回调地址的优先级 企业应用管理中创建第三方应用时需要设置回调地址，用PDF文件创建签署流程和用模板创建签署流程也可以指定回调地址，在此合同状态变动通知这个回调中优先使用用PDF文件创建签署流程和用模板创建签署流程指定的回调地址, 如果创建签署流程接口没有传回调地址的情况下才会使用创建第三方应用时指定的回调地址

会出现回调的合同状态

合同状态对应FlowStatus备注
合同创建INIT-
合同签署中PART-
合同签署完成ALL合同终态
合同拒签REJECT合同终态
合同撤回CANCEL合同终态
合同即将过期WILLEXPIRE-
合同流签(合同过期)DEADLINE合同终态
解除协议（已解除）RELIEVED合同终态
合同已失效INVALID合同终态
合同异常EXCEPTION合同终态

签署人状态

签署人状态对应ApproveStatus
待签署PENDING
已签署ACCEPT
拒绝REJECT
过期没人处理DEADLINE
流程已撤回CANCEL
流程已终止STOP
待领取WAITPICKUP
待填写FILLPENDING
填写完成FILLACCEPT
已转他人处理FORWARD
解除协议（已解除）RELIEVED
拒绝填写FILLREJECT
异常EXCEPTION

合同组状态

合同组状态对应FlowGroupStatus
待我处理TOSIGN
待他人处理WAITSIGN
部分合同已失效PART
已完成ALL
已失效INVALID
合同处理中PROCESSING
未定义UNDEFINED

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号
ProxyOrganizationOpenIdString第三方平台子客企业的唯一标识，定义Agent中的ProxyOrganizationOpenId一样, 可以参考Agent结构体
ProxyOperatorOpenIdString第三方平台子客企业员工的唯一标识，定义和Agent.ProxyOperator.OpenId一样, 可以参考Agent结构体
CustomerDataString用PDF文件创建签署流程和用模板创建签署流程创建签署流程时候传递的CustomerData参数
FlowIdString触发回调的合同流程ID，为32位字符串
FlowNameString触发回调的合同流程的名称
FlowTypeString触发回调的合同流程的类别分类
FlowStatusString合同状态，具体含义可以参考上述其他说明中的 会出现回调的合同状态
FlowMessageString当合同流程状态为合同拒签, 合同撤回等状态时，此字段为拒签或撤销原因，其他状态时此字段为空值
CreateOnInteger合同流程的创建时间戳，格式为Unix标准时间戳（秒）
DeadlineInteger签署流程的签署截止时间，格式为Unix标准时间戳（秒）
CcInfoArray of CcInfo合同(流程)关注方信息列表, 结构体定义可以查看开发者中的CcInfo
FlowApproverInfoArray of FlowApproverDetail合同(流程)签署人信息列表, 结构体的定义可以参考下面的FlowApproverDetail
FlowGroupMessageFlowGroupMessageDetail如果合同归属合同组, 此结构体为合同组的信息, 结构体的定义可以参考下面的FlowGroupMessageDetail
OccurTimeInteger此回调触发的时间,格式为Unix标准时间戳（秒）

FlowApproverDetail结构体定义

参数名称参数类型参数描述
ProxyOperatorOpenIdString如果第三方子企业员工签署, 此字段为第三方子企业员工的唯一标识
ProxyOrganizationNameString如果第三方子企业员工签署, 此字段为第三方子企业的名称
OrganizationNameString如果saas企业员工签署, 此字段为saas企业的名称
ProxyOrganizationOpenIdString如果第三方子企业员工签署, 此字段为第三方子企业的唯一标识
PhoneNumberString对应签署人的手机号
SignOrderInteger如果合同是顺序签署, SignOrder对应签署人的签署顺序
RecipientIdString对应签署人的参与角色ID
ApproveNameString对应签署人的名字
ApproveStatusString对应签署人的状态, 具体含义可以参考上述其他说明中的 签署人状态
ApproveMessageString对应签署人状态的简单描述, 如: 已签署或者拒签的原因等
ApproveTimeString对应签署人签署此合同的时间，格式为Unix标准时间戳（秒）
CaSignString对应签署人签署此合同的证书信息, 此功能为白名单功能, 使用前请联系对接的客户经理沟通。
ApproverDeadlineint64对应签署人的签署截止时间，格式为Unix标准时间戳（秒）

FlowGroupMessageDetail结构体定义

参数名称参数类型参数描述
FlowGroupIdString合同组的ID，为32位字符串
FlowGroupNameString合同组的名称
CreateOnInteger合同组的创建时间戳，格式为Unix标准时间戳（秒）
FlowsInfoArray of GroupFlowsInfoDetail合同组中每个合同流程的信息, 结构体的定义可以参数下面的 GroupFlowsInfoDetail
FlowGroupStatusString合同组状态，具体含义可以参考上述其他说明中的 合同组状态

GroupFlowsInfoDetail结构体定义

参数名称参数类型参数描述
FlowIdString合同组里边流程的ID，为32位字符串

5. 示例​

{
  "MsgId": "yDwFdUUckpswdrniUuzcbXw8N43W6Kcz",
  "MsgType": "FlowStatusChange",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "ApplicationId": "yDwFkUUckpstzjhfUugNAWf1KibXqS26",
    "ProxyOrganizationOpenId": "org_dianziqian",
    "ProxyOperatorOpenId": "user_openid",
    "CustomerData": "data",
    "FlowId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI",
    "FlowName": "2023年采购西红柿50吨合同",
    "FlowType": "采购合同",
    "FlowStatus": "REJECT",
    "FlowMessage": "张三因为合同中的价格问题不满意而拒绝合同",
    "CreateOn": 1563968167,
    "Deadline": 1573968167,
    "CcInfo": [],
    "FlowApproverInfo": [
      {
        "ProxyOperatorOpenId": "n9527",
        "PhoneNumber": "13200000000",
        "ProxyOrganizationName": "典子谦示例企业",
        "ProxyOrganizationOpenId": "org_dianziqian",
        "OrganizationName": "",
        "SignOrder": 1,
        "recipientId": "yDwFkUUckpstzjhfUugNAWf1KibXqS26",
        "ApproveName": "典子谦",
        "ApproveStatus": "ACCEPT",
        "ApproveMessage": "已签署",
        "ApproveTime": 1563968000,
        "CaSign": "",
        "ApproverDeadline": 1563968167
      },
      {
        "ProxyOperatorOpenId": "",
        "PhoneNumber": "18888888888",
        "ProxyOrganizationName": "",
        "ProxyOrganizationOpenId": "",
        "OrganizationName": "",
        "SignOrder": 2,
        "recipientId": "yDRS4UUgygqdcj56UuO4zjExBQcOiB68",
        "ApproveName": "张三",
        "ApproveStatus": "PENDING",
        "ApproveMessage": "待签署",
        "ApproveTime": 1563968100,
        "CaSign": "",
        "ApproverDeadline": 1563968167
      }
    ],
    "FlowGroupMessage": {
      "FlowGroupId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
      "FlowGroupName": "2023年蔬菜采购合作组",
      "FlowGroupStatus": "WAITSIGN",
      "FlowsInfo": [
        {
          "FlowId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI"
        },
        {
          "FlowId": "yDRSRUUgygj6qnwfUuO4zjEwc193c2hH"
        }
      ],
      "CreateOn": 1562968167
    },
    "OccurTime": 1563968167
  }
}

二. 转交签署任务​

1. 回调触发时机​

合同经办人将合同转交给同企业其他经办人时触发

2. 回调消息类型​

ForwardFLow

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号
ProxyOrganizationOpenIdString第三方平台子客企业的唯一标识，定义Agent中的ProxyOrganizationOpenId一样, 可以参考Agent结构体
ProxyOperatorOpenIdString转交此合同的第三方平台子客企业员工的唯一标识, 为转发动作的发起方
FlowIdString转交的合同流程ID，为32位字符串
ForwardedOpenIdString接收此合同的第三方平台子客企业员工的唯一标识, 为转发动作的目的方

触发场景：；

5. 示例​

{
  "MsgId": "yDRIGUUgygs8aey1UuO4zjEuM18ffkaK",
  "MsgType": "ForwardFLow",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "ApplicationId": "yDwFkUUckpstzjhfUugNAWf1KibXqS26",
    "ProxyOrganizationOpenId": "org_dianziqian",
    "ProxyOperatorOpenId": "n9527",
    "FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
    "ForwardedOpenId": "n13579"
  }
}

三. 合同发起扣费通知​

1. 回调触发时机​

合同发起成功并扣费成功后触发

2. 回调消息类型​

FlowCost

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号
ProxyOrganizationOpenIdString第三方平台子客企业的唯一标识，定义Agent中的ProxyOrganizationOpenId一样, 可以参考Agent结构体
ProxyOperatorOpenIdString发起此合同的第三方平台子客企业员工的唯一标识
FlowIdString转交的合同流程ID，为32位字符串
CostInteger此合同流程消耗的合同份额, 固定为1
CostChannelString此合同流程消耗对应计费版本, 现在的计费版本有企业版,在线签约,战略签约,群闪签,单方签章等, 一般为企业版
IsResellBoolean此合同流程消耗是否是分销场景下的消费

5. 示例​

{
  "MsgId": "yDRspUUgyg17u3j8Ux9XTPkBnnXZyvdT",
  "MsgType": "FlowCost",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "ApplicationId": "yDwFkUUckpstzjhfUugNAWf1KibXqS26",
    "ProxyOrganizationOpenId": "org_dianziqian",
    "ProxyOperatorOpenId": "n9527",
    "Cost": 1,
    "CostChannel": "企业版",
    "FlowId": "yDRspUUgyg17u3jwUx9XTPkysXSTG8jO",
    "IsResell": false
  }
}

四. 合同撤销扣费返还通知​

1. 回调触发时机​

合同撤销时触发合同消费额度的返还

2. 回调消息类型​

FLowCost

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号
ProxyOrganizationOpenIdString第三方平台子客企业的唯一标识，定义Agent中的ProxyOrganizationOpenId一样, 可以参考Agent结构体
FlowIdString转交的合同流程ID，为32位字符串
CostInteger此合同流程返还的合同份额, 注意: 此字段为负数表示返回额度
CostChannelString此合同流程消耗对应计费版本, 现在的计费版本有企业版,在线签约,战略签约,群闪签,单方签章等, 一般为企业版
IsResellBoolean此合同流程消耗是否是分销场景下的消费

5. 示例​

{
  "MsgId": "yDRspUUgyg17u3j8Ux9XTPkBnnXZyvdT",
  "MsgType": "FlowCost",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "ApplicationId": "yDwFkUUckpstzjhfUugNAWf1KibXqS26",
    "ProxyOrganizationOpenId": "org_dianziqian",
    "Cost": -1,
    "CostChannel": "企业版",
    "FlowId": "yDRspUUgyg17u3jwUx9XTPkysXSTG8jO",
    "IsResell": false
  }
}

五. 发起合同审核通知​

1. 回调触发时机​

在嵌入式页面场景下,若调用创建发起流程web页面接口时设置了NeedCreateReview 参数进行发起操作的审批控制，则在审批发起、通过或者拒绝时会进行回调。

2. 回调消息类型​

CreateFlowReview

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号
ProxyOrganizationOpenIdString第三方平台子客企业的唯一标识，定义Agent中的ProxyOrganizationOpenId一样, 可以参考Agent结构体
ProxyOperatorOpenIdString执行对应审核动作的第三方平台子客企业员工的唯一标识
FlowIdString审核的合同流程ID，为32位字符串
DocumentIdString审核的合同流程的PDF文档的编号ID，为32位字符串
FlowNameString审核的合同流程的名称
OperateString审核动作, 具体的含义参考下面的Operate说明
CustomerDataString用PDF文件创建签署流程和用模板创建签署流程创建签署流程时候传递的CustomerData参数

Operate含义

  • CreateFlowReviewStart：提交发起审核
  • CreateFlowReviewPass：发起审核通过
  • CreateFlowReviewReject：发起审核拒绝

5. 示例​

{
  "MsgId": "yDwFhUUckps95bm2UElNO1L1rQ8x9p0Q",
  "MsgType": "CreateFlowReview",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "ApplicationId": "yDwFUckpstzjhfUugNAWf1KibXqS96",
    "ProxyOrganizationOpenId": "org_dianziqian",
    "ProxyOperatorOpenId": "n9527",
    "DocumentId": "yDRS4UUgygqdcjjhUuO4zjEBpXdcsHWX",
    "Operate": "CreateFlowReviewStart",
    "FlowId": "yDwFdUUckpsveo27UEQPEVo14KnASuGI",
    "CustomerData": "data",
    "FlowName": "2023年采购西红柿50吨合同"
  }
}

六. 动态签署人领取合同通知​

1. 回调触发时机​

在合同含有动态签署人时，即通过接口文件发起合同、模板发起合同发起合同指定了动态签署人签署人设置后，则可以通过接口补充签署流程签署人信息指定具体签署人或者获取跳转至腾讯电子签小程序的签署链接生成动态签署人链接前往页面进行领取，领取完成后进行回调。

2. 回调消息类型​

ReceiveFlow

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString合同流程ID，为32位字符串
CallbackTypeString回调的类型：
Dynamic：动态签署人领取合同回调
ApproverTypeInteger参与者类型,
0：企业
1：个人
3：企业自动签署
7：个人自动签署
RecipientIdString对应签署人的参与角色ID, 为32位字符串
OrganizationNameString领取人的企业名称，签署人类型为企业时有值
NameString领取人的姓名
MobileString领取人的手机号码
OrganizationOpenIdString领取人的企业OpenId，签署人类型为第三方应用企业时有值
OpenIdString领取人的OpenId，签署人类型为第三方应用企业时有值
ReceiveTimeInteger领取时间

5. 示例​

{
  "MsgId": "yDSLgUUckp**************gvRRiu2QzL9",
  "MsgType": "ReceiveFlow",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "FlowId": "yDSLaUUck**************OqxaEcHip4W",
    "CallbackType": "Dynamic",
    "ApproverType": 0,
    "RecipientId": "yDSLaUUckp**************ROqBRg91hfFA",
    "OrganizationName": "**科技有限公司",
    "Name": "张三",
    "Mobile": "1591***5678",
    "OrganizationOpenId": "",
    "OpenId": "",
    "ReceiveTime": 1701313404
  }
}

七. 领取未归属合同通知​

1. 回调触发时机​

通过接口文件发起合同、模板发起合同发起合同时未指定具体签署人，则可以通过接口领取未归属的合同或者生成子客登录链接登陆控制台查看并领取合同。

2. 回调消息类型​

ReceiveFlow

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString合同流程ID，为32位字符串
CallbackTypeString回调的类型：
Bound：未归属合同领取回调
ApproverTypeInteger参与者类型,
0：企业
1：个人
3：企业自动签署
7：个人自动签署
RecipientIdString对应签署人的参与角色ID, 为32位字符串
OrganizationNameString领取人的企业名称，签署人类型为企业时有值
NameString领取人的姓名
MobileString领取人的手机号码
OrganizationOpenIdString领取人的企业OpenId
OpenIdString领取人的OpenId
ReceiveTimeInteger领取时间

5. 示例​

{
  "MsgId": "yDSLaUUckp********jukyHDpgLMZF",
  "MsgType": "ReceiveFlow",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "FlowId": "yDSLgUUckpt********8nkx64wWVjfv",
    "CallbackType": "Bound",
    "ApproverType": 0,
    "RecipientId": "yDSLgUUckp********8nkumOxreQuC",
    "OrganizationName": "**科技有限公司",
    "Name": "张三",
    "Mobile": "1591***5678",
    "OrganizationOpenId": "d7c13a8b***********68c0ee248f04",
    "OpenId": "00498cc***********3aff766cac",
    "ReceiveTime": 1701313404
  }
}

八. 签署人签署截止时间过期通知​

1. 回调触发时机​

在通过接口文件发起合同、模板发起合同发起合同时指定了签署人的签署截止时间，若合同状态正常，且签署人在签署截止时间前未完成签署操作，会触发此回调。 若还需要签署人继续签署，可通过接口 管理签署流程截止时间延长签署人截止时间以便继续签署。

2. 回调消息类型​

ApproverDeadlineExpired

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号，为32位字符串
ProxyOrganizationOpenIdString发起方企业在第三方平台子客企业的唯一标识，可以参考Agent结构体
FlowIdString合同流程ID，为32位字符串
FlowNameString合同名称
FlowStatusstring合同状态 见上方合同状态变动通知中FlowStatus定义
FlowDeadlineint64合同的签署截止时间
FlowUnorderedBoolean合同是否有序
OrganizationIdString发起方企业ID
ApproverInfoApproverInfo过期签署人的信息

ApproverInfo结构体定义

参数名称参数类型参数描述
SignOrderint64当前签署人的顺序，如果是有序合同的话需要关注，有序从1开始
RecipientIdString签署人编号
ApproverTypeint64参与者类型,
0：企业
1：个人
3：企业自动签署
7：个人自动签署
ApproverNameint64签署人姓名
ApproverMobilestring签署人手机号
OrganizationNameString签署人企业名称
ProxyOrganizationOpenIdString签署人企业OpenId,签署人类型为第三方应用企业时有值
ProxyOperatorOpenIdString签署人OpenId,签署人类型为第三方应用企业时有值
ApproverDeadlineint64对应签署人的签署截止时间，格式为Unix标准时间戳（秒）

5. 示例​

{
  "MsgId": "yDCNsUUckpvqfrz7UuGjzgvBW2KDYTh9",
  "MsgType": "ApproverDeadlineExpired",
  "MsgVersion": "ThirdPartyApp",
  "MsgData": {
    "ApplicationId": "yDCNGUUckpvjp7xfUuj6rPu4Bnbumbbb",
    "ProxyOrganizationOpenId": "example-proxy-organization-open-id",
    "FlowId": "yDCNsUUckpvqzv1zUxu0h4ax87hzcag7",
    "FlowName": "示例合同",
    "FlowStatus": "INIT",
    "FlowDeadline": 1706085980,
    "FlowUnordered": true,
    "ApproverInfo": {
      "SignOrder": 0,
      "RecipientId": "yDCNsUUckpvqzv2eUxu0h3a1W9TswxMn",
      "ApproverType": 0,
      "ApproverName": "典子谦",
      "ApproverMobile": "18200000000",
      "ProxyOrganizationOpenId": "example-proxy-organization-open-id",
      "ProxyOperatorOpenId": "example-proxy-operator-open-id",
      "ApproverStatus": "PENDING",
      "OrganizationName": "电子签示例企业",
      "ApproverDeadline": 1706083980
    }
  }
}

九. 批量撤销结果回调​

1. 回调触发时机​

在通过接口批量撤销合同流程或者 获取批量撤销合同流程的腾讯电子签小程序链接进行批量撤销操作后，若批量撤销任务完成，则会触发此回调。

2. 回调消息类型​

CancelFlows

3. 其他说明​

无

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号，为32位字符串
ProxyOrganizationOpenIdString发起方企业在第三方平台子客企业的唯一标识，可以参考Agent结构体
TaskIdString批量撤销任务编号，为32位字符串
SuccessFlowIdsArray of String撤销成功的合同流程ID列表
FailureFlowsArray of FailureFlow撤销失败的合同流程列表

FailureFlow结构体定义

参数名称参数类型参数描述
FlowIdString签署流程编号，为32位字符串
ReasonString撤销失败的原因

5. 示例​

{
    "MsgId": "yDCVWUUckpwkg3d4UxFDY7lRXuH9tIjX",
    "MsgType": "CancelFlows",
    "MsgVersion": "ThirdPartyApp",
    "MsgData": {
        "ApplicationId": "yDCNGUUckpvjp7xfUuj6rPu4Bnbumbbb",
        "ProxyOrganizationOpenId": "example-proxy-organization-open-id",
        "TaskId": "yDCVWUUckpwk3b05UyEZnO0xOn4snWWY",
        "SuccessFlowIds": [
            "yDwFQUUckpswz8sbUywdl3m11huHBekH"
        ],
        "FailureFlows": [
            {
                "FlowId": "yDCNGUUckpvjdelbUuyImI8pY8I5Mep7",
                "Reason": "合同当前状态不支持撤销"
            },
            {
                "FlowId": "yDw9jUUgyg34g2mdUxawbT71HrwMQ2gF",
                "Reason": "合同信息不存在或非本企业发起的合同"
            }
        ]
    }
}

十. 合同组状态变动回调​

1. 回调触发时机​

当合同组状态（参考上述其他说明中的 合同组状态 ）处于终态：部分合同已失效，已完成，已失效 时 ，则会触发此回调。

2. 回调消息类型​

FlowGroupStatusChange

3. 其他说明​

每个合同组仅会回调一次

4. 回调结构体​

MsgData结构体定义

参数名称参数类型参数描述
ApplicationIdString第三方应用的应用编号，为32位字符串
ProxyOrganizationOpenIdString发起方企业在第三方平台子客企业的唯一标识，可以参考Agent结构体
ProxyOperatorOpenIdString第三方平台子客企业员工的唯一标识，定义和Agent.ProxyOperator.OpenId一样, 可以参考Agent结构体
FlowGroupIdString合同组编号，为32位字符串
FlowGroupNameString合同组名称
FlowGroupStatusString合同组状态，具体含义可以参考上述其他说明中的 合同组状态

5. 示例​

{
    "MsgId": "yDCVWUUckpwkg3d4UxFDY7lRXuH9tIjX",
    "MsgType": "FlowGroupStatusChange",
    "MsgVersion": "ThirdPartyApp",
    "MsgData": {
        "ApplicationId": "yDCNGUUckpvjp7xfUuj6rPu4Bnbumbbb",
        "ProxyOrganizationOpenId": "example-proxy-organization-open-id",
        "ProxyOperatorOpenId": "user_openid",
        "FlowGroupId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
        "FlowGroupName": "2023年蔬菜采购合作组",
        "FlowGroupStatus": "ALL"
    }
}
购买咨询
4006-808-062
4006-808-062