一、确认接入回调类型

1.1 回调类型

根据自身业务确定需要对接的回调类型，现支持回调类型如下：

回调业务类型（businessType）	描述
1. CONTRACT_STATUS_CHANGED	合同状态变更
2. APP_PSN_AUTHORITY_CONFIRM	个人授权回调
3. APP_CORP_AUTHORITY_CONFIRM	企业授权回调
4. CONTRACT_SIGNED	签署结果回调通知
5. CONTRACT_STARTED	合同发起成功回调通知
6. CONTRACT_SIGNATORY_TRANSFERRED	签署方转交签署任务回调通知
7. CONTRACT_SIGN_TURN_DOWN	用印审批驳回回调通知
8. CONTRACT_APPROVAL_CHANGED	合同审批变更通知
9. SEAL_APPROVAL_CHANGED	申请用印审批变更通知
10. CONTRACT_AUTO_SIGN_SEAL_AUTH	合同静默签印章授权生效通知
11. CONTRACT_AUTO_SIGN_SEAL_AUTH_DISABLED	合同静默签印章授权失效通知
12. SEAL_STATUS_CHANGED	企业印章状态变更通知
13. APP_AUTHORITY_CANCEL	取消应用授权通知

1.2 回调接入时序图

以“CONTRACT_STARTED合同发起成功回调通知”为例：

3.CONTRACT_STARTED通知：根据"企业控制台-应用管理-回调配置"中开启此项，回调内容见3.2内容。
4.获取回调信息接口：根据3中的transactionId 调用获取回调信息
5.回调成功确认：成功处理回调信息后调用此接口回调成功确认（新）

二、回调接入

如需要接收回调信息，请登录签盾平台"企业控制台-应用管理-回调配置"页面中进行回调地址配置

2.1 环境准备

2.1.1 接口准备

2.1.1.1 回调接收接口

协议：https/http
method：Post
contentType： application/json;charset=UTF-8

2.1.1.2 回调连通性测试接口

回调测试接口与回调接收接口地址相同，但请求方法不同，为"GET"请求。

回调测试接口不需要接收任何请求参数，也无需特定的结果返回。

请不要在回调测试接口中处理任何业务逻辑，连通性测试的超时时间较短，需在请求到达时立即返回。

协议：https/http
method：Get
contentType： application/json;charset=UTF-8

2.1.2 配置白名单信息

如果系统采取了IP白名单校验，请根据“回调配置”页面提示引导，配置白名单过滤。

2.2 接入准备

2.2.1 配置应用回调接口

请在“回调配置”页面，初始化相应应用的回调接口配置，并通过接口测试确保服务间可正常调用。

2.2.1 回调接收流程

💡

2023.9.5更新后，需要在“回调配置页面”中的“订阅事件”中订阅相关的回调事件

1. 接口获取到的回调信息只是简单的基础信息，详见“回调基础信息格式”
2. 获取详细信息需要使用回调中的“transactionId”（Long），通过“获取回调信息”（详见获取回调信息接口返回）接口来获取详细信息。
3. 根据回调基础信息中“callbackRequired”(Boolean)，判断此回调信息是否需要确认，“true”则表示需要调用“回调成功确认”(详见回调成功确认返回)接口进行消息确认。否则回调消息会延迟再次发送，详见“回调重试间隔”。

三、回调详细内容

3.1 回调重试间隔

目前回调重试间隔（单位：秒）
10， 30，60，120，180，600，1200，1800，3600，7200，14400，28800

3.2 回调基础内容

回调基础信息格式
{
  "transactionId":1663393434595627008,          ## 流水id
  "businessType":"CONTRACT_STATUS_CHANGED",	## 回调业务类型，详细见最上表格
  "callbackRequired":true,                      ## 是否需要确认
  "ts":1685448086106	                        ## 发送时间戳
}

3.3 回调详细内容

3.3.1回调详细内容需要根据“3.2回调基础内容”中的transactionId 根据获取回调信息接口查询

获取回调信息接口返回
{
    "code": "200",                              ## 状态码
    "msg": "",	                                ## 状态信息
    "result": "string",	                        ## 回调详细内容JSON格式
    "success": true                             ## 是否成功
}

3.3.2回调详细内容JSON格式如下：

result 内容
{
    "transactionId": 1663393434595627008,                ## 流水id
    "businessType": "CONTRACT_STATUS_CHANGED",           ## 业务类型
    "callbackRequired": true,                            ## 是否需要确认
    "data": "XXX"                                        ## json信息
}

*合同状态见：合同状态说明

合同状态变更回调通知（CONTRACT_STATUS_CHANGED）
{
  "contractId": "1537", 	                       ## 合同id
  "statusCode": "revoked", 	                       ## 合同状态码 (wait_sign:签署中; finished:已完成; rejected:已拒签; revoked:已撤回)
  "contractCode": "CM_20230522183728tGPwInDPjSZCDdQ",  ## 合同编码
  "contractName": "API-TEST0522", 	               ## 合同名称
  "statusDescription": "已撤回",	               ## 合同状态码描述
  "ts":"1685448086106"	                               ## 时间戳
  "appId": "99"					       ## 应用id
}

个人授权回调通知（APP_PSN_AUTHORITY_CONFIRM）
{
  "appId": "99", 		                       ## 应用id
  "openPsnId": "1666651398177427456", 		       ## 开放平台个人用户id
  "psnAccount": "18896586351",  		       ## 个人用户账号
  "psnName": "张三", 				       ## 个人姓名
  "ts": "1686285906628",			       ## 时间戳
  "authorityScopeList":[
        "get_psn_ident_info",
        "get_psn_signature_info"
    ],                                                  ## 授权范围
  "accountId":"888888"                                  ##集成方唯一标识  
}

企业授权回调通知（APP_CORP_AUTHORITY_CONFIRM）
{
  "appId": "99", 		                       ## 应用id
  "openCorpId": "1666651398177427456", 		       ## 开放平台企业用户id
  "openPsnId":"1668084920452780032",                   ## 授权人开放平台个人用户id
  "staffId": "18896586351",  		               ## 员工id
  "staffName": "张三", 				       ## 员工姓名
  "corpName": "张三的公司", 			       ## 企业名
  "ts": "1686285906628",			       ## 时间戳
  "authorityScopeList":[
        "get_psn_ident_info",
        "get_psn_signature_info",
        "get_corp_ident_info",
        "get_corp_seal_info"
    ]                                                  ## 授权范围
  "accountId":"888888"                                ##集成方唯一标识
}

取消应用授权通知(APP_AUTHORITY_CANCEL)
{
    "ts":"1701602120516",                            ##时间戳
    "appId":"93",                                    ##应用ID
    "openCorpId":"1713763658506833920",              ##开放平台企业用户id
    "openPsnId":"1713763658506833920",               ##开放平台个人用户id
    "accountId":"888888",                            ##集成方唯一标识
    "openPsnName":"王二",                            ##个人姓名
    "openCorpName":"XXX公司",                        ##企业名称
}
* 将根据类型返回 openPsnId&openPsnName / openCorpId&openCorpName

签署结果回调通知（CONTRACT_SIGNED）
{
  "contractId": "1537", 	                         ## 合同id
  "statusCode": "rejected", 	                         ## 签署结果(rejected:已拒签;  finished: 已完成)
  "contractCode": "CM_20230522183728tGPwInDPjSZCDdQ",    ## 合同编码
  "contractName": "API-TEST0522", 	                 ## 合同名称
  "appId": "99",					 ## 应用id
  "statusDescription": "已拒签",	                       ## 合同状态码描述
  "ts":"1685448086106"	                                 ## 时间戳
  "corpInfo":{                                           ## 签署企业信息-个人签署此字段返回null
      "openCorpId":"180123123123",                       ## 企业ID-企业未授权此字段返回null
      "corpName":"浙江签盾科技有限公司"                     ## 企业名
  },
  "operator":{                                           ## 签署操作人个人信息-静默签此字段返回null
      "openPsnId":"1801231231234",                       ## 签署操作人个人ID-个人未授权此字段返回null
      "psnAccount":"18011112222"                         ## 签署操作人个人登录账号
  }
  "operatorName":"张三",                                  ## 操作人姓名（已废弃）
  "operatorSubjectName": "张三的公司"                      ## 操作人主体名（已废弃）
}

合同发起成功回调通知（CONTRACT_STARTED）
{
  "contractId": "1537", 	                        ## 合同id
  "contractCode": "CM_20230522183728tGPwInDPjSZCDdQ",   ## 合同编码
  "contractName": "API-TEST0522", 	                ## 合同名称
  "appId": "99",					## 应用id
  "operatorName":	"张三",                         ## 操作人姓名
  "operatorSubjectName": "张三的公司",                   ## 操作人主体名
  "ts":"1685448086106"	                                ## 时间戳
}

签署方转交签署任务回调通知（CONTRACT_SIGNATORY_TRANSFERRED）
{
  "contractId": "1537", 	                        ## 合同id
  "contractCode": "CM_20230522183728tGPwInDPjSZCDdQ",   ## 合同编码
  "contractName": "API-TEST0522", 	                ## 合同名称
  "appId": "99",					## 应用id
  "operatorName":	"张三",                         ## 操作人姓名
  "operatorSubjectName": "张三的公司",                   ## 操作人主体名
  "originalSignatory": "王五",			        ## 原签署人
  "transfereeName": "李四",			        ## 承让人姓名
  "ts":"1685448086106"	                                ## 时间戳
}

用印审批驳回回调通知（CONTRACT_SIGN_TURN_DOWN）
{
  "contractId": "1537", 	                       ## 合同id
  "contractCode": "CM_20230522183728tGPwInDPjSZCDdQ",  ## 合同编码
  "contractName": "API-TEST0522", 	               ## 合同名称
  "appId": "99",				       ## 应用id
  "operatorName":	"张三",                        ## 操作人姓名
  "operatorSubjectName": "张三的公司",                  ## 操作人主体名
  "rejectReason": "李四",	                       ## 驳回原因
  "ts":"1685448086106"	                               ## 时间戳
}

合同审批变更通知（CONTRACT_APPROVAL_CHANGED）
{
  "contractId": "1537", 	                       ## 合同id
  "approvalId": "666",                                 ## 审批id
  "statusCode": "rejected", 	                       ## 审批结果
  "appId": "99",				       ## 应用id
  "statusDescription":	"已拒签",                       ## 审批状态码描述
  "ts":"1685448086106"	                               ## 时间戳
}

申请用印审批变更通知（SEAL_APPROVAL_CHANGED）
{
  "contractId": "1537", 	                       ## 合同id
  "sealId": "1234",                                    ## 印章id
  "approvalId": "666",                                 ## 审批id
  "statusCode": "rejected", 	                       ## 审批结果
  "appId": "99",				       ## 应用id
  "statusDescription":	"已拒签",                       ## 审批状态码描述
  "ts":"1685448086106"	                               ## 时间戳
}

合同静默签印章授权生效通知(CONTRACT_AUTO_SIGN_SEAL_AUTH)
{
    "appId":"93",                                      ## 应用id
    "sealId":"8223",                                   ## 印章id
    "bizCode":"OT20zOZFgtHNUmlD",                      ## 业务码
    "endTime":"2026-01-01 00:00:00",                   ## 授权结束时间
    "beginTime":"2023-01-01 00:00:00",                 ## 授权开始时间
    "openCorpId":"1713763658506833920",                ## 授权企业ID
    "authorizeCode":"OT20231117111220zOZFgtHNUmlD",    ## 静默签授权码
    "ts":"1700444625514"                               ## 时间戳
}
* 授权时间需要beginTime<当前时间<endTime才会收到此通知。
* 企业若在应用未进行过任何授权操作，无法收到此消息

合同静默签印章授权失效通知(CONTRACT_AUTO_SIGN_SEAL_AUTH_DISABLED)
{
    "appId":"93",                                      ## 应用id
    "sealId":"8223",                                   ## 印章id
    "bizCode":"OT20zOZFgtHNUmlD",                      ## 业务码
    "endTime":"2026-01-01 00:00:00",                   ## 授权结束时间
    "beginTime":"2023-01-01 00:00:00",                 ## 授权开始时间
    "openCorpId":"1713763658506833920",                ## 授权企业ID
    "authorizeCode":"OT20231117111220zOZFgtHNUmlD",    ## 静默签授权码
    "ts":"1700444625514"                               ## 时间戳
}
* 以下条件会推送失效通知
*   1.当前时间>endTime时
*   2.用户取消授权
*   3.印章被禁用/印章被删除
* 企业若在应用未进行过任何授权操作，无法收到此消息

企业印章状态变更通知(SEAL_STATUS_CHANGED)
{
    "ts":"1701602120516",                            ##时间戳
    "appId":"93",                                    ##应用ID
    "sealId":"8253",                                 ##印章ID
    "sealNo":"2NRWEMYKCQ-07CQ4GAGDX",                ##印章编号
    "status":"enabled",                              ##印章状态-enabled/disabled/deleted
    "sealName":"新增测试",                             ##印章名
    "createTime":"2023-12-03 18:20:05",              ##印章创建时间
    "openCorpId":"1713763658506833920"               ##企业ID
}
* 此推送需要用户企业授权【get_corp_seal_info】 - 授权允许获取企业的印章相关资源
* 以下条件会推送此通知
*   1.启用/创建印章，status=enabled
*   2.删除印章，status=deleted
*   3.禁用印章，status=disabled

取消应用授权通知(APP_AUTHORITY_CANCEL)
{
    "ts":"1701602120516",                            ##时间戳
    "appId":"93",                                    ##应用ID
    "openPsnId":"1853626362884395008",               ##开放平台个人id
    "openCorpId":"1853626362884395008",              ##开放平台企业id
    "accountId":"18856968745",                       ##印章状态
    "openPsnName":"张三",                            ##印章名
    "openCorpName":"张三的公司"                       ##印章创建时间
}

3.4 回调确认

回调成功确认返回
{
    "code": "200",	                        ## 状态码
    "msg": "",			                ## 状态信息
    "result": null,	                        ## 返回信息，为null
    "success": true                             ## 是否成功
}

回调接入文档

一、确认接入回调类型#

1.1 回调类型#

1.2 回调接入时序图#

二、回调接入#

2.1 环境准备#

2.1.1 接口准备#

2.1.1.1 回调接收接口#

2.1.1.2 回调连通性测试接口#

2.1.2 配置白名单信息#

2.2 接入准备#

2.2.1 配置应用回调接口#

2.2.1 回调接收流程#

三、回调详细内容#

3.1 回调重试间隔#

3.2 回调基础内容#

3.3 回调详细内容#

3.4 回调确认#