跳到主要内容

合同相关回调

一. 合同状态变动通知

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

签署人状态

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

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位字符串
RecipientIdString对应签署人的参与角色ID, 为32位字符串
OperateString具体动作:
start:发起
sign:签署
reject:拒签
cancel:取消
finish:结束
deadline:过期
fill:填写
UserDataString用PDF文件创建签署流程用模板创建签署流程创建签署流程时候传递的UserData参数
ApproversArray of Approver合同(流程)签署人信息列表, 结构体的定义可以参考下面的Approver
CcInfoArray of CcInfo合同(流程)关注方信息列表, 结构体定义可以查看开发者中的CcInfo
OccurTimeInteger此回调触发的时间,格式为Unix标准时间戳(秒)

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:人脸识别

5. 示例

{
"MsgId": "yDwgKUUckp1jouutUymITAlB0ZirQWfm",
"MsgType": "FlowStatusChange",
"MsgVersion": "CustomApp",
"MsgData": {
"FlowId": "yDRtrAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"DocumentId": "yDRtrBBBBBBBBBBBBBBBBBBBBBBBBBB",
"CallbackType": "sign",
"FlowName": "测试流程",
"FlowDescription": "",
"FlowType": "",
"FlowCallbackStatus": 4,
"Unordered": true,
"CreateOn": 1658892449,
"UpdatedOn": 1659604019,
"DeadLine": 1661615999,
"UserId": "",
"RecipientId": "yDRtrCCCCCCCCCCCCCCCCCCCCCCCCCCC",
"Operate": "sign",
"UserData": "",
"OccurTime": 1563968167,
"CcInfos":[
{
"CcPermission":1,
"CcType":0,
"Mobile":"15912345678",
"Name":"张三"
}
],
"Approvers": [
{
"UserId": "yDRtrDDDDDDDDDDDDDDDDDDDDDDDDDDD",
"RecipientId": "yDRtrCCCCCCCCCCCCCCCCCCCCCCCCCCC",
"ApproverType": 1,
"OrganizationName": "",
"Required": true,
"ApproverName": "张三",
"ApproverMobile": "15912345678",
"ApproverIdCardType": "ID_CARD",
"ApproverIdCardNumber": "440300200101010001",
"ApproveCallbackStatus": 3,
"ApproveMessage": "",
"ApproveTime": 1659604019,
"VerifyChannel": "WEIXINAPP"
}
],
"CallbackUrl": "https://www.esstest.com"
}
}

二. 合同发起扣费通知

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
}
}