回调接入指南

一、接入必读

对接前需要在下图所示位置进行配置并提交保存，通过对应接口要求的信息与SCRM系统交互；

当尘锋系统内的联系人、企业、旅程、订单等业务内容发生变更时，支持推送变更事件给您，您需要在“设置-系统对接”页面完成 消息校验token、消息加解密key、消息与事件接受URL、调用数据加解密 四个参数的配置；

【加密解密】密文数据仅用于尘锋SCRM系统联系人管理部分接口主动向第三方系统服务端推送变更事件；

1、调用数据加密不论是否开启，在初次配置消息与事件接受URL时，均需要实现完整的数据解密逻辑，解密逻辑可参考本文《三、URL配置校验（GET请求）-2、三方系统-URL配置校验解密示例》
2、如暂时不确定对SCRM系统发起请求的服务器出口IP或者其他情况，可先设置为0.0.0.0调试,后期根据第三方系统的实际情况进行调整；
3、OpenAPI进行新增和编辑等操作不会触发对应事件变更回调

二、配置回调URL、加密参数

【消息与事件接受URL】：避免使用"searchs"等关键字作为回调地址路径的一部分，回调地址URL需同时支持GET和POST请求；配置或更新回调地址时，尘锋SCRM会对目标回调地址发起一次GET请求，第三方系统需按照《三、URL配置校验（GET请求）》对请求进行正确的解密处理并返回要求内容才可以通过校验；

【调用数据加密】：选择数据加密后，所有的业务数据变更事件推送时，我们将对事件body进行加密并发送POST请求到“消息与事件接受URL”，您可参考 解密SDK对其解密后使用；

【配置提交保存】：点击提交按钮时，我们会向您填写的“消息与事件接受URL”发送GET请求校验URL的可用性，您需要配合解密SDK解密之后原样返回给我们，校验成功后才能配置成功。

1、所配置的回调地址URL需要确保能够在公网被访问；
2、GET请求用于验证秘文解密逻辑是否被正确实现，SCRM系统回调该接口时，第三方系统需要对推送的秘文进行解密并返回解密后的明文，返回示例参考：《三、URL配置校验（GET请求）- 3、三方系统-URL配置校验解密返回示例》；
3、POST请求用于后续验证推送内容时是否正确被接收，接收到请求后返回指定结构体即可。返回示例参考：《四、尘锋系统变更事件推送（POST请求）- 3、三方系统事件接收响应内容示例》；

三、URL配置校验（GET请求）

1、尘锋SCRM-URL配置校验加密请求示例

在尘锋系统配置完毕URL地址之后，尘锋系统会通过GET请求对目标地址发起加密请求；
下列代码仅展示示例，并不能用作调试使用，请使用您公司尘锋账户的相关参数进行调试

2、三方系统-URL配置校验解密示例

三方系统接收到尘锋系统发起的GET加密请求之后，需要使用租户对应的加密信息对加密请求进行解密；

解密所需SDK点击这里跳转

3、三方系统-URL配置校验解密返回示例

对GET请求解密后，您需要将解密后的内容原样返回给尘锋系统，如果与尘锋系统加密前的内容一致，尘锋系统将判定三方系统解密成功并且界面将成功保存，URL地址配置成功。

注意：返回时Header需设置Content-Type:text/plain，另外切勿额外携带 "" 包装返回内容；

4、异常处理

报错原因为返回给尘锋的解密数据有错误，请严格根据文档说明进行解密返回。

四、尘锋系统变更事件推送（POST请求）

URL地址配置完毕之后，当尘锋系统的客户数据有新增/删除/修改时，尘锋会主动向您填写的URL发送POST请求，携带回调数据。

1、尘锋推送加密请求示例

⽬前联系人事件仅会推送变更客户的id，具体事件类型由body解密后的type判断。
type⽀持的值：add(新增客户)/del(删除客户)/update(客户更新)。
三⽅拿到客户id(cus_ids)后调⽤拉取接⼝获取客户的全量信息进⾏数据同步。
event代表事件分类，⽬前仅⽀持customer。

1、加密参数通过贵司的clientId、clientToken、clientKey参与生成，以下示例仅供参考结构，不支持解密！
2、删除客户的情况del_reason包括三种值：ordinaryDel（普通客户删除），userDel（员⼯删除外部联系⼈），externalDel（外部联系⼈删除员⼯）

2、三方系统解密后完整body示例

解密所需SDK点击这里跳转
您可以根据我们传递的type自行规划业务逻辑

3、三方系统事件接收响应内容示例

当您接收到我方推送的变更事件回调请求时，需返回JSON格式的code
数据类型为int
成功返回：1
失败返回：0

{
"code" : 1
}

1、回调服务需在3秒内完成响应，建议收到消息推送后⽴刻返回成功响应示例，避免⼀直占⽤请求连接，被判超时

2、切勿在回调处理逻辑内增加额外业务处理逻辑，避免延长响应时间，当推送事件较频繁时，可能会导致接口请求超时。

3、推送限制：多次响应超时、服务器⽆响应、多次响应失败，10分钟内达到100次，推送接⼝将降低所有推送事件频率为3⼩时⼀次。

五、加密SDK（自测）

尘锋通过BizMsgCrypt.EncryptMsg(String replyMst)将数据加密并推送给您，您也可以通过此函数自行校验；
加密所需参数以您在尘锋系统里获取到的为准。

六、三方系统-接口处理代码示例

Q1：处理GET请求时为什么要将" "全量替换为"+"?

url传输过程中会将"+"替换为空格，导致解密失败，您可以使用此函数进行处理

Q2：java.security.InvalidKeyException: Illegal key size

解决方案JCE无限制权限策略文件

Q3：commons-codec依赖

当解密遇到以下报错时可以尝试添加此版本依赖解决
Exception in thread "main" java.lang.IllegalArgumentException: Last encoded character (before the paddings if any) is a valid base 64 alphabet but not a possible value

<dependency>
       <groupId>commons-codec</groupId>
       <artifactId>commons-codec</artifactId>
       <version>1.15</version>
</dependency>

一、接入必读#

二、配置回调URL、加密参数#

三、URL配置校验（GET请求）#

1、尘锋SCRM-URL配置校验加密请求示例#

2、三方系统-URL配置校验解密示例#

3、三方系统-URL配置校验解密返回示例#

4、异常处理#

四、尘锋系统变更事件推送（POST请求）#

1、尘锋推送加密请求示例#

2、三方系统解密后完整body示例#

3、三方系统事件接收响应内容示例#

五、加密SDK（自测）#

六、三方系统-接口处理代码示例#

Q1：处理GET请求时为什么要将" "全量替换为"+"?#

Q2：java.security.InvalidKeyException: Illegal key size#

Q3：commons-codec依赖#

一、接入必读

二、配置回调URL、加密参数

三、URL配置校验（GET请求）

1、尘锋SCRM-URL配置校验加密请求示例

2、三方系统-URL配置校验解密示例

3、三方系统-URL配置校验解密返回示例

4、异常处理

四、尘锋系统变更事件推送（POST请求）

1、尘锋推送加密请求示例

2、三方系统解密后完整body示例

3、三方系统事件接收响应内容示例

五、加密SDK（自测）

六、三方系统-接口处理代码示例

Q1：处理GET请求时为什么要将" "全量替换为"+"?

Q2：java.security.InvalidKeyException: Illegal key size

Q3：commons-codec依赖