合同相关回调

一. 合同状态变动通知

1. 回调触发时机

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

2. 回调消息类型

FlowStatusChange

3. 其他说明

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

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

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

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

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

会出现回调的合同状态

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

签署人状态

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

4. 回调结构体

MsgData结构体定义

参数名称	参数类型	参数描述
FlowId	String	触发回调的合同流程ID, 为32位字符串
DocumentId	String	触发回调的合同文档ID，为32位字符串
CallbackType	String	回调的类型： sign：签署回调 review：审核回调 fill：填写回调
FlowName	String	触发回调的合同流程的名称
FlowDescription	String	触发回调的合同流程的描述
FlowType	String	触发回调的合同流程的类别分类
FlowCallbackStatus	String	合同状态, 具体含义可以参考上述其他说明中的会出现回调的合同状态
Unordered	bool	流程类型顺序： true：为无序 false：为有序
CreateOn	Integer	合同流程的创建时间戳, 格式为Unix标准时间戳（秒）
UpdatedOn	Integer	合同流程的更新时间戳, 格式为Unix标准时间戳（秒）
DeadLine	Integer	签署流程的签署截止时间, 格式为Unix标准时间戳（秒）
UserId	String	触发回调的合同创建用户ID, 为32位字符串
RecipientId	String	对应签署人的参与角色ID, 为32位字符串
Operate	String	具体动作： start：发起 sign：签署 reject：拒签 cancel：取消 finish：结束 deadline：过期 fill：填写
UserData	String	用PDF文件创建签署流程和用模板创建签署流程创建签署流程时候传递的UserData参数
Approvers	Array of Approver	合同(流程)签署人信息列表, 结构体的定义可以参考下面的Approver
CcInfo	Array of CcInfo	合同(流程)关注方信息列表, 结构体定义可以查看开发者中的CcInfo
OccurTime	Integer	此回调触发的时间,格式为Unix标准时间戳（秒）

Approver结构体定义

参数名称	参数类型	参数描述
UserId	String	签署人的用户ID, 为32位字符串
RecipientId	String	对应签署人的参与角色ID
ApproverType	Integer	参与者类型, 0：企业 1：个人 3：企业静默签署
OrganizationName	String	参与者企业名
Required	Bool	是否需要签名
ApproverName	String	对应签署人的名字
ApproverMobile	String	对应签署人的手机号
ApproverIdCardType	String	签署人证件类型： ID_CARD：身份证 HONGKONG_AND_MACAO：港澳居民来往内地通行证 HONGKONG_MACAO_AND_TAIWAN：港澳台居民居住证（格式同居民身份证）
ApproverIdCardNumber	String	签署人证件号码
ApproveCallbackStatus	Integer	对应签署人的状态, 具体含义可以参考上述其他说明中的签署人状态
ApproveMessage	String	对应签署人状态的简单描述, 如: 已签署或者拒签的原因等
ApproveTime	String	对应签署人签署此合同的时间，格式为Unix标准时间戳（秒）
VerifyChannel	String	签署意愿方式，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结构体定义

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

5. 示例

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

三. 合同转交通知

1. 回调触发时机

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

2. 回调消息类型

ForwardFLow

3. 其他说明

无

4. 回调结构体

MsgData结构体定义

参数名称	参数类型	参数描述
FlowId	String	转交的合同流程ID, 为32位字符串
ForwardedUserId	String	接收此合同的自建企业员工的唯一标识, 为转发动作的目的方
OperatorUserId	String	发起转交操作的用户ID, 为32位字符串
OrganizationId	String	发起转交操作的机构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结构体定义

参数名称	参数类型	参数描述
FlowId	String	审核的合同流程ID，为32位字符串
DocumentId	String	审核的合同流程的PDF文档的编号ID，为32位字符串
FlowName	String	审核的合同流程的名称
Operate	String	审核动作, 具体的含义参考下面的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结构体定义

参数名称	参数类型	参数描述
FlowId	String	合同流程ID，为32位字符串
CallbackType	String	回调的类型： OrSign：领取或签合同回调
RecipientId	String	对应签署人的参与角色ID, 为32位字符串
CustomUserId	String	领取人的企业微信UserId
Name	String	领取人的姓名
Mobile	String	领取人的手机号码
IdCardType	String	领取人的证件类型
IdCardNumber	String	领取人的证件号码
ApproverTag	String	参与或签的人员标识，对应文件发起合同、模板发起合同中对应签署人指定的入参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结构体定义

参数名称	参数类型	参数描述
FlowId	String	合同流程ID，为32位字符串
CallbackType	String	回调的类型： Dynamic：动态签署人领取合同回调
ApproverType	Integer	参与者类型, 0：企业 1：个人 3：企业自动签署 7：个人自动签署
RecipientId	String	对应签署人的参与角色ID, 为32位字符串
OrganizationName	String	领取人的企业名称，签署人类型为企业时有值
Name	String	领取人的姓名
Mobile	String	领取人的手机号码
ReceiveTime	Integer	领取时间

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. 回调消息类型​

3. 其他说明​

4. 回调结构体​

5. 示例​

二. 合同发起扣费通知​

1. 回调触发时机​

2. 回调消息类型​

3. 其他说明​

4. 回调结构体​

5. 示例​

三. 合同转交通知​

1. 回调触发时机​

2. 回调消息类型​

3. 其他说明​

4. 回调结构体​

5. 示例​

四. 发起合同审核通知​

1. 回调触发时机​

2. 回调消息类型​

3. 其他说明​

4. 回调结构体​

5. 示例​

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

1. 回调触发时机​

2. 回调消息类型​

3. 其他说明​

4. 回调结构体​

5. 示例​

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

1. 回调触发时机​

2. 回调消息类型​

3. 其他说明​

4. 回调结构体​

5. 示例​

一. 合同状态变动通知

1. 回调触发时机

2. 回调消息类型

3. 其他说明

4. 回调结构体

5. 示例

二. 合同发起扣费通知

1. 回调触发时机

2. 回调消息类型

3. 其他说明

4. 回调结构体

5. 示例

三. 合同转交通知

1. 回调触发时机

2. 回调消息类型

3. 其他说明

4. 回调结构体

5. 示例

四. 发起合同审核通知

1. 回调触发时机

2. 回调消息类型

3. 其他说明

4. 回调结构体

5. 示例

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

1. 回调触发时机

2. 回调消息类型

3. 其他说明

4. 回调结构体

5. 示例

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

1. 回调触发时机

2. 回调消息类型

3. 其他说明

4. 回调结构体

5. 示例