推送格式约定

推送数据格式

因无法保证各公司推送接收端口使用加密，为防止数据泄漏。推送的消息体将使用完全加密。加密方式为AES加密(AES/CTR/PKCS5Padding)，加密KEY使用 appKey 生成，CTR分组模式初始向量IV由corpid（appid中包含corpid，例如appid=ww51046ddc4f4df510_NjaEnW，corpid=ww51046ddc4f4df510）生成。

为保证消息可以正常解密，消息头中将包含appId信息。接收方可以通过appId确认是否自己持有对应appKey

为方便后续推送功能调整升级，数据格式将进行版本化。消息头中将添加version头。当前版本为第1版，version: 1

与平台接口类似，消息头中同样包含timestamp信息和sign值，但与平台接口不同的是，sign值的计算由 appId+version+timestamp+appKey计算得到，消息体不参与sign计算。接收方可以通过这个sign值确定是否由我平台推送的消息，而不必花费算力进行消息体解密。

消息体解密后为 JSON格式。该JSON具有统一的外层构架结构

{
  "noise": 123,
  "msgId": 999,
  "type": "verify",
  "content": {}
}

字段	类型	可空	说明
noise	数字	否	随机数。接收方成功接收处理消息后需要在响应中回复此值。
msgId	数字	否	消息id。
type	字符串	否	消息推送类型
content	不定	由具体推送内容确定	消息内容。各推送接口分别说明

推送消息使用UTF-8编码

以 appId: zc_test 、appKey: zc_test 、corpid: zc_test为例。假设加密前消息体为:

{"type":"register","noise":4970601478527096155,"msgId":999,"content":"hello"}

以下分别说明加解密流程

AES 密钥生成流程

取appKey按UTF-8编码字节数据

使用SHA256方式对第1步得到数据计算摘要值（字节数据）

取第2步结果字节数据前16字节作为AES key的字节数据恢复出AES密钥

CTR分组模式初始向量IV生成流程

取corpid按UTF-8编码字节数据

使用SHA256方式对第1步得到数据计算摘要值（字节数据）

取第2步结果字节数据前16字节作为IV字节数据恢复出IV

消息加密和推送消息组装流程

取当前系统时间戳 timestamp。本示例假设时间戳为1596681164807

联接appId、version、timestamp、appKey，并对结果做SHA256计算摘要值，以16进制编码表示，作为sign值。本例结果为317672b4685d9b8bafe1794390e31209aed5cef912683292fed94a69085919d3

按照AES密钥生成流程恢复出AES密钥

按照CTR分组模式IV生成流程恢复出IV

取消息体（结尾无换行）按UTF-8编码字节数据

使用第3步得到的密钥和第4步得到的IV对第5步中得到的字节数据做AES/CTR/PKCS5Padding加密，得到加密后字节数据

将第6步得到的字节数据按Base64编码，得到Base64编码字符串，即加密后用于传输的数据。本示例结果为：

5TMVT8H4yTSSoING+afhRlGcCZAIxTs8Z7o3vGpid6tF2aF7C73uZ44qMopuNPCFmwOLOJ8xViCTHUfe/xYZSb71/VRSEDeIqqwN4eg=

组装消息。

消息头：appId、timestamp、sign，version

字符编码 UTF-8

消息体。使用plain text消息体，内容为第6步计算结果
本例结果：

POST http://{{crm-address}}/recieve
appId: zc_test
timestamp: 1596681164807
version: 1
sign: 317672b4685d9b8bafe1794390e31209aed5cef912683292fed94a69085919d3
Content-Type: text/plain;charset=UTF-8
Content-Length: 104

5TMVT8H4yTSSoING+afhRlGcCZAIxTs8Z7o3vGpid6tF2aF7C73uZ44qMopuNPCFmwOLOJ8xViCTHUfe/xYZSb71/VRSEDeIqqwN4eg=

消息解密流程

从消息头中读取appId，判断是否持有对应的appKey，如果没有，则放弃操作。
a. 可选操作：检验sign值，以认证消息是否是由平台发出

按照AES密钥生成流程恢复出AES密钥

按照CTR分组模式IV生成流程恢复出IV

将收到的消息体按Base64进行解码，得到加密字节数据

使用第2步得到的密钥和第3步得到的IV对第4步得到的字节数据做AES/CTR/PKCS5Padding解密，得到加密前字节数据

使用第5步得到的数据使用UTF-8编码恢复字符串数据。恢复的结果为JSON字符串

处理JSON消息，并根据处理结果响应是否成功。

接收接口响应约定

为保证消息到达或成功接收处理，对接推送的公司CRM应给予正确的响应。
同时满足以下条件的响应被认为成功接收：

响应HTTP状态为OK 200

响应体不限

其他响应状态均被视为消息推送地址不可用, 不予推送消息。

注意

请保证提供的推送接口可用且稳定, 以下情况会认为不可用, 并将推送地址下线, 待推送地址恢复正常后, 在重新上线推送地址。

接口未响应HTTP状态200,认为接口不可用

接口超5秒未响应,认为接口不可用

建议: 推送消息体量大, 接收消息方异步处理消息, 及时响应, 保证推送接口的吞吐量

推送地址被识别不可用，下线后，如何恢复？

订阅方可重新调用推送注册接口恢复接口即可。

消息推送数据格式

推送格式约定#

推送数据格式#

AES 密钥生成流程#

CTR分组模式初始向量IV生成流程#

消息加密和推送消息组装流程#

消息解密流程#

接收接口响应约定#

推送地址被识别不可用，下线后，如何恢复？#