跳到主要内容

合同相关回调

一. 合同状态变动通知

1. 回调触发时机

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

2. 回调消息类型

FlowStatusChange

3. 其他说明

注意,回调 V1、V2 版本此类型的回调相差较大

回调 V2 版本,是标准结构,解密后为

{
"MsgId": "xxx",
"MsgType": "FlowStatusChange",
"MsgVersion": "CustomApp",
"MsgData": {
"FlowId": "xxxx",
...
}
}

回调 V1 版本,此类型的回调消息体是此 MsgData 结构,解密后为

{
"FlowId": "xxxx",
...
}

会出现回调的合同状态

合同状态对应FlowCallbackStatus对应FlowCallbackShowStatus备注
合同创建1INIT-
合同签署中2PART-
合同拒签3REJECT合同终态
合同签署完成4ALL合同终态
合同流签(合同过期)5DEADLINE合同终态
合同撤回6CANCEL合同终态
合同待填写8INIT-
解除协议(已解除)21RELIEVED合同终态
合同已失效16INVALID合同终态

签署人状态

签署人状态对应ApproveCallbackStatus对应ApproveCallbackShowStatus
待签署2,7PENDING
已签署3ACCEPT
拒绝4REJECT
过期没人处理5DEADLINE
流程已撤回6CANCEL
合同待填写8FILLPENDING
流程已终止9STOP
填写完成10FILLACCEPT
解除协议(已解除)15RELIEVED
已转他人处理19FORWARD

合同组状态

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

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString触发回调的合同流程ID, 为32位字符串
DocumentIdString触发回调的合同文档ID,为32位字符串
CallbackTypeString回调的类型:
sign:签署回调
review:审核回调
fill:填写回调
FlowNameString触发回调的合同流程的名称
FlowDescriptionString触发回调的合同流程的描述
FlowTypeString触发回调的合同流程的类别分类
FlowCallbackStatusString合同状态, 具体含义可以参考上述其他说明中的 会出现回调的合同状态
Unorderedbool流程类型顺序:
true:为无序
false:为有序
CreateOnInteger合同流程的创建时间戳, 格式为Unix标准时间戳(秒)
UpdatedOnInteger合同流程的更新时间戳, 格式为Unix标准时间戳(秒)
DeadLineInteger签署流程的签署截止时间, 格式为Unix标准时间戳(秒)
UserIdString触发回调的合同创建用户ID, 为32位字符串
OrganizationIdString触发回调的合同创建企业ID, 为32位字符串
RecipientIdString签署等环节触发本次回调的参与角色ID, 为32位字符串
OperateString具体动作:
start:发起
sign:签署
reject:拒签
cancel:取消
finish:结束
deadline:过期
invalid:失效
fill:填写
UserDataString用PDF文件创建签署流程用模板创建签署流程创建签署流程时候传递的UserData参数
ApproversArray of Approver合同(流程)签署人信息列表, 结构体的定义可以参考下面的Approver
CcInfoArray of CcInfo合同(流程)关注方信息列表, 结构体定义可以查看开发者中的CcInfo
OccurTimeInteger此回调触发的时间,格式为Unix标准时间戳(秒)
FlowGroupMessageFlowGroupMessageDetail如果合同归属合同组, 此结构体为合同组的信息, 结构体的定义可以参考下面的FlowGroupMessageDetail

Approver结构体定义

参数名称参数类型参数描述
UserIdString签署人的用户ID, 为32位字符串
RecipientIdString对应签署人的参与角色ID
ApproverTypeInteger参与者类型, 0:企业
1:个人
3:企业静默签署
OrganizationNameString参与者企业名
RequiredBool是否需要签名
ApproverNameString对应签署人的名字
ApproverMobileString对应签署人的手机号
ApproverIdCardTypeString签署人证件类型:
ID_CARD:身份证
HONGKONG_AND_MACAO:港澳居民来往内地通行证
HONGKONG_MACAO_AND_TAIWAN:港澳台居民居住证(格式同居民身份证)
ApproverIdCardNumberString签署人证件号码
ApproveCallbackStatusInteger对应签署人的状态, 具体含义可以参考上述其他说明中的 签署人状态
ApproveMessageString对应签署人状态的简单描述, 如: 已签署或者拒签的原因等
ApproveTimeString对应签署人签署此合同的时间,格式为Unix标准时间戳(秒)
VerifyChannelString签署意愿方式,WEIXINAPP:人脸识别
CaSignString对应签署人签署此合同的证书信息, 此功能为白名单功能, 使用前请联系对接的客户经理沟通。
ApproverDeadlineint64对应签署人的签署截止时间,格式为Unix标准时间戳(秒)

FlowGroupMessageDetail结构体定义

参数名称参数类型参数描述
FlowGroupIdString合同组的ID,为32位字符串
FlowGroupNameString合同组的名称
FlowGroupStatusString合同组状态,具体含义可以参考上述其他说明中的 合同组状态

5. 示例

{
"MsgId": "yDCVjUUckpw709mwUE2d86xxe48eZehT",
"MsgType": "FlowStatusChange",
"MsgVersion": "CustomApp",
"MsgData": {
"Approvers": [{
"ApproveCallbackShowStatus": "ACCEPT",
"ApproveCallbackStatus": 3,
"ApproveMessage": "",
"ApproveTime": 1711625666,
"ApproverDeadline": 1714319999,
"ApproverIdCardNumber": "17072411000204263X",
"ApproverIdCardType": "ID_CARD",
"ApproverIdCardTypeDesc": "居民身份证",
"ApproverMobile": "18500000000",
"ApproverName": "刘波",
"ApproverSource": "",
"ApproverType": 0,
"CaSign": "",
"CustomApproverTag": "",
"CustomUserId": "",
"OrganizationName": "呱呱叫测试企业",
"RecipientId": "yDCVjUUckpw7hdznUyigyC6El96dC2Yo",
"Required": true,
"UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn",
"VerifyChannel": ""
}, {
"ApproveCallbackShowStatus": "ACCEPT",
"ApproveCallbackStatus": 3,
"ApproveMessage": "",
"ApproveTime": 1711625721,
"ApproverDeadline": 1714319999,
"ApproverIdCardNumber": "37072410000724000X",
"ApproverIdCardType": "ID_CARD",
"ApproverIdCardTypeDesc": "居民身份证",
"ApproverMobile": "17300000000",
"ApproverName": "猪猪侠",
"ApproverSource": "",
"ApproverType": 1,
"CaSign": "",
"CustomApproverTag": "",
"CustomUserId": "",
"OrganizationName": "",
"RecipientId": "yDCVjUUckpw7hdzgUyigyC6u6gEPlMfy",
"Required": true,
"UserId": "yDSLgUUckpt0wwgwUEdI8nkSP9RzXc6y",
"VerifyChannel": ""
}, {
"ApproveCallbackShowStatus": "PENDING",
"ApproveCallbackStatus": 2,
"ApproveMessage": "",
"ApproveTime": 0,
"ApproverDeadline": 1714319999,
"ApproverIdCardNumber": "390724100002042638",
"ApproverIdCardType": "ID_CARD",
"ApproverIdCardTypeDesc": "居民身份证",
"ApproverMobile": "18500000000",
"ApproverName": "段誉",
"ApproverSource": "",
"ApproverType": 0,
"CaSign": "",
"CustomApproverTag": "",
"CustomUserId": "",
"OrganizationName": "段誉测试企业",
"RecipientId": "yDCVjUUckpw7hdzdUyigyC6uW1KpB4CA",
"Required": true,
"UserId": "yDw6yUUgyg3caowzUx4GQptRKfMnJqX8",
"VerifyChannel": ""
}
],
"CallbackType": "sign",
"CallbackUrl": "http://www.qq.com:8000/callback",
"CcInfos": [],
"CreateOn": 1711625257,
"DeadLine": 1714319999,
"DocumentId": "yDCVjUUckpw7hdm9UyigyC6zyvnLYgMv",
"FlowCallbackShowStatus": "PART",
"FlowCallbackStatus": 2,
"FlowDescription": "20240328西红柿购买",
"FlowId": "yDCVjUUckpw7hdmeUyigyC6ybpKSjQee",
"FlowName": "蔬菜购买合同",
"FlowType": "购买合同",
"OccurTime": 1711625721,
"FlowGroupMessage": {
"FlowGroupId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"FlowGroupName": "合作组",
"FlowGroupStatus": "WAITSIGN"
},
"Operate": "sign",
"OrganizationId": "yDw6yUUgyg3c47e6Uyh4KQ5SPpKT0ch9",
"RecipientId": "yDCVjUUckpw7hdzgUyigyC6u6gEPlMfy",
"Unordered": true,
"UpdatedOn": 1711625721,
"UserData": "VXNlckRhdGFVc2VyRGF0YVVzZXJEYXRhVXNlckRhdGE=",
"UserId": "yDw6yUUgyg3c753gUx4GQptwsiPEXZNn"
}
}

二. 合同发起扣费通知

1. 回调触发时机

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

2. 回调消息类型

FlowCost

3. 其他说明

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString转交的合同流程ID,为32位字符串
CostInteger此合同流程消耗的合同份额, 如果为负值则为份额退还
CostChannelString此合同流程消耗对应计费版本, 现在的计费版本有企业版,在线签约,战略签约,群闪签,单方签章等, 一般为企业版
OrganizationIdString企业 ID,为32位字符串
IsResellBoolean此合同流程消耗是否是分销场景下的消费

5. 示例

{
"MsgId": "yDRspUUgygxxxxxxxxxx9XTPkBnnXZyvdT",
"MsgType": "FlowCost",
"MsgVersion": "CustomApp",
"MsgData": {
"FlowId": "yDRspUUgxxxxxxxxxxxsXSTG8jO",
"Cost": 1,
"CostChannel": "企业版",
"OrganizationId": "yDxbWUyKQxxxxxxxxxxEB8mxCcDjAyF",
"IsResell": false
}
}

三. 合同转交通知

1. 回调触发时机

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

2. 回调消息类型

ForwardFLow

3. 其他说明

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString转交的合同流程ID, 为32位字符串
ForwardedUserIdString接收此合同的自建企业员工的唯一标识, 为转发动作的目的方
OperatorUserIdString发起转交操作的用户ID, 为32位字符串
OrganizationIdString发起转交操作的机构ID, 为32位字符串

5. 示例

{
"MsgId": "yDRIGUUgygs8aey1UuO4zjEuM18ffkaK",
"MsgType": "ForwardFLow",
"MsgVersion": "CustomApp",
"MsgData": {
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"ForwardedUserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj",
"OperatorUserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy",
"OrganizationId": "yDxbWUyKQDxgXVUuO4zjEB8mxCcDjAyF"
}
}

四. 发起合同审核通知

1. 回调触发时机

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

2. 回调消息类型

CreateFlowReview

3. 其他说明

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString审核的合同流程ID,为32位字符串
DocumentIdString审核的合同流程的PDF文档的编号ID,为32位字符串
FlowNameString审核的合同流程的名称
OperateString审核动作, 具体的含义参考下面的Operate说明

Operate含义

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

5. 示例

{
"MsgId": "yDSLfUUckptgxc0wUuePjuk99Pm6q9mj",
"MsgType": "CreateFlowReview",
"MsgVersion": "CustomApp",
"MsgData": {
"DocumentId": "yDALfUUckptgirpiUu55s2CCd7Nmg9a2",
"FlowId": "yDSLfUUckptgir50Uu16s3CCbicAoz4j",
"FlowName": "对账申请单",
"Operate": "CreateFlowReviewStart"
}
}

五. 或签候选人领取合同通知

1. 回调触发时机

在或签合同场景下,若调用了补充签署流程签署人信息 接口补充了签署方候选人后,在候选人领取合同后会进行回调。

2. 回调消息类型

ReceiveFlow

3. 其他说明

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString合同流程ID,为32位字符串
CallbackTypeString回调的类型:
OrSign:领取或签合同回调
RecipientIdString对应签署人的参与角色ID, 为32位字符串
CustomUserIdString领取人的企业微信UserId
NameString领取人的姓名
MobileString领取人的手机号码
IdCardTypeString领取人的证件类型
IdCardNumberString领取人的证件号码
ApproverTagString参与或签的人员标识,对应文件发起合同模板发起合同中对应签署人指定的入参CustomApproverTag

5. 示例

{
"MsgId": "yDSLaUUc**********BKw54S3XA",
"MsgType": "ReceiveFlow",
"MsgVersion": "CustomApp",
"MsgData": {
"FlowId": "yDSLaUUck**********bW1srERk275",
"CallbackType": "OrSign",
"RecipientId": "yDRIZUUg**********q35keHT6izZ",
"CustomUserId": "amber",
"Name": "张三",
"Mobile": "1591***5678",
"IdCardType": "ID_CARD",
"IdCardNumber": "4****************1",
"ApproverTag": "430000********3237498"
}
}

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

1. 回调触发时机

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

2. 回调消息类型

ReceiveFlow

3. 其他说明

4. 回调结构体

MsgData结构体定义

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

5. 示例

{
"MsgId": "yDSLFUUck**************k8DCus0DoH",
"MsgType": "ReceiveFlow",
"MsgVersion": "CustomApp",
"MsgData": {
"FlowId": "yDSLYUUck**************egERaDZMWuO",
"CallbackType": "Dynamic",
"ApproverType": 0,
"RecipientId": "yDSLYUUc**************yPeB0GwG5",
"OrganizationName": "**科技有限公司",
"Name": "张三",
"Mobile": "1591***5678",
"ReceiveTime": 1701160764
}
}

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

1. 回调触发时机

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

2. 回调消息类型

ApproverDeadlineExpired

3. 其他说明

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
FlowIdString合同流程ID,为32位字符串
FlowNameString合同名称
FlowStatusstring合同状态 见上方合同状态变动通知中FlowCallbackShowStatus定义
FlowDeadlineint64合同的签署截止时间
FlowUnorderedBoolean合同是否有序
OrganizationIdString发起方企业ID
ApproverInfoApproverInfo过期签署人的信息

ApproverInfo结构体定义

参数名称参数类型参数描述
SignOrderint64当前签署人的顺序,如果是有序合同的话需要关注,有序从0开始
RecipientIdString签署人编号
ApproverTypeint64参与者类型,
0:企业
1:个人
3:企业自动签署
7:个人自动签署
ApproverNameint64签署人姓名
ApproverMobileBoolean签署人手机号
OrganizationNameString签署人企业名称
ApproverDeadlineint64对应签署人的签署截止时间,格式为Unix标准时间戳(秒)

5. 示例

{
"MsgId": "yDCN4UUckpvj9737UuGjzgvRek5gfb8r",
"MsgType": "ApproverDeadlineExpired",
"MsgVersion": "CustomApp",
"MsgData": {
"FlowId": "yDCNGUUckpvjp6xfUuj8rPu4Bnbumbbb",
"FlowName": "示例合同",
"FlowStatus": "INIT",
"FlowDeadline": 1705998880,
"FlowUnordered": false,
"OrganizationId": "yDCN4UUckpvj6688UuGjzgvRek5gfb8r",
"ApproverInfo": {
"SignOrder": 2,
"RecipientId": "yDCAGUUckpvjp6xzUuj8rPuxWhNlj5J7",
"ApproverType": 0,
"ApproverName": "典子谦",
"ApproverMobile": "18700000000",
"ApproverStatus": "PENDING",
"OrganizationName": "电子签示例企业",
"ApproverDeadline": 1705998720
}
}
}

八. 批量撤销结果回调

1. 回调触发时机

若在操作人通过接口获取批量撤销合同流程的腾讯电子签小程序链接获取链接后进行了撤销操作,则会触发此回调。

2. 回调消息类型

CancelFlows

3. 其他说明

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
OrganizationIdString发起方企业ID
TaskIdString批量撤销任务编号,为32位字符串
SuccessFlowIdsArray of String撤销成功的合同流程ID列表
FailureFlowsArray of FailureFlow撤销失败的合同流程列表

FailureFlow结构体定义

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

5. 示例

{
"MsgId": "yDCVbUUckpwth9dqUxFDY7lEYHF5KVKv",
"MsgType": "CancelFlows",
"MsgVersion": "CustomApp",
"MsgData": {
"OrganizationId": "yDCN4UUckpvj6688UuGjzgvRek5gfb6r",
"TaskId": "yDCVWUUckpwkthb5UxWziEO8VvOWlC3m",
"SuccessFlowIds": [
"yDCVbUUckpwtpsmiU4zgYeEWdIlc78BS"
],
"FailureFlows": [
{
"FlowId": "yDCVOUUckpwqqsc8UVBFcywZjuX5PhNZ",
"Reason": "合同当前状态不支持撤销"
}
]
}
}

九. 合同组状态变动回调

1. 回调触发时机

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

2. 回调消息类型

FlowGroupStatusChange

3. 其他说明

每个合同组仅会回调一次

4. 回调结构体

MsgData结构体定义

参数名称参数类型参数描述
OrganizationIdString发起方企业ID
OperatorUserIdString发起方用户ID, 为32位字符串
FlowGroupIdString合同组的ID,为32位字符串
FlowGroupNameString合同组的名称
FlowGroupStatusString合同组状态,具体含义可以参考上述其他说明中的 合同组状态

5. 示例

{
"MsgId": "yDCVbUUckpwth9dqUxFDY7lEYHF5KVKv",
"MsgType": "FlowGroupStatusChange",
"MsgVersion": "CustomApp",
"MsgData": {
"OrganizationId": "yDCN4UUckpvj6688UuGjzgvRek5gfb6r",
"OperatorUserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy",
"FlowGroupId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"FlowGroupName": "合作组",
"FlowGroupStatus": "ALL"
}
}
购买咨询
微信客服
4006-808-062
4006-808-062