微伴助手OpenAPI
  1. 消息订阅
微伴助手OpenAPI
  • OpenAPI基本介绍
  • 错误码参考表
  • 访问频率和并发限制
  • 消息订阅
    • 订阅消息加解密指南
    • 回调应用配置指南
    • 工单变更消息
      • 工单变更消息回调
      • 创建工单回调
      • 流转工单回调
      • 关闭工单回调
      • 重新打开工单回调
      • 评论工单回调
  • 获取访问凭据
    • 获取访问凭据
      POST
  • 员工管理
    • 获取员工列表
      GET
    • 获取员工详情
      GET
    • 发送员工通知
      POST
  • 自定义订单管理
    • 订单信息删除
      GET
    • 获取订单信息列表
      GET
    • 批量同步店铺信息
      POST
    • 批量同步商品信息
      POST
    • 批量同步订单信息v2
      POST
    • 批量删除商品信息
      POST
    • 删除店铺信息
      GET
    • 批量删除订单信息
      POST
    • 获取店铺信息详情
      POST
    • 获取店铺信息列表
      GET
    • 获取商品信息详情
      POST
    • 获取商品信息列表
      GET
  • 客户管理
    • 获取客户列表
      GET
    • 根据更新时间获取客户列表
      GET
    • 获取客户详情
      GET
    • 获取流失提醒客户列表
      GET
    • 导入客户信息
      POST
    • 添加客户评分
      POST
    • 添加自定义字段
      POST
    • 批量预设客户属性
      POST
    • 批量修改自定义字段的值
      POST
    • 创建批量加好友任务(批量创建添加客户任务)
      POST
    • 批量unionid&openid换external_user_id
      POST
    • external_user_id换unionid
      POST
    • unionid&openid换客户id
      POST
    • 获取客户自定义字段值列表
      GET
    • 批量获取客户详情
      POST
    • 获取批量加好友待添加列表
      GET
  • 客户积分管理
    • 批量增减客户积分
    • 批量获取客户积分
    • 获取单个客户积分明细记录
    • 获取全部客户积分明细记录
  • 客户标签管理
    • 获取标签列表
    • 批量更新客户企业标签
    • 给客户添加企业标签
    • 删除客户的企业标签
    • 给客户添加微伴个人标签
    • 删除客户的微伴个人标签
    • 获取预打标签信息
    • 批量预打企业标签
    • 根据手机号删除预打标签任务
    • 根据unionid删除预打标签任务
    • 获取指定用户预打标签任务详情
    • 获取预打标签任务列表
    • 添加预打标签任务
  • 客户画像管理
    • 获取客户事件列表
    • 创建自定义客户事件
    • 获取自定义客户事件类型列表
    • 获取自定义客户事件类型详情
    • 添加自定义客户事件类型
    • 删除自定义客户事件类型
    • 更新自定义客户事件类型
    • 获取客户阶段状态
  • 标签库管理
    • 获取标签列表V2
    • 获取指定标签信息
    • 新增企业标签组
    • 新增企业标签
    • 删除企业标签
    • 更新企业标签
    • 同步企业微信标签
  • 群聊管理
    • 获取群聊列表
    • 获取群聊成员列表
    • 获取客户所在群聊
    • 查看客户是否在群聊中
    • 获取群聊详情
  • 工单管理
    • 工单模块OpenAPI开发必读
    • 获取工单列表
    • 获取工单详情
    • 获取工单流内处理人
    • 获取工单模板列表
    • 获取工单模板详情
    • 新建工单
    • 修改工单
    • 流转工单
    • 评论工单
    • 关闭工单
  • 销售过程管理
    • 获取商机列表
    • 获取商机详情
    • 修改商机阶段
    • 获取线索公海列表
    • 批量导入线索
    • 修改线索
    • 获取线索列表
    • 员工单条/批量领取线索
    • 获取线索客户列表
  • 聊天记录管理
    • 获取会话消息
    • 获取会话消息2(按照消息时间逆序)
    • 获取员工会话
  • 拉新排行榜
    • 获取拉新排行榜列表
  • 群裂变
    • 获取群裂变活动列表
    • 获取群裂变任务详情
    • 获取群裂变客户详情列表
  • 群打卡
    • 获取群打卡活动列表
    • 获取群打卡任务详情
  • 企微任务宝
    • 获取企微任务宝活动列表
    • 获取企微任务宝任务详情
    • 获取企微任务宝对应的客户数据列表
    • 获取客户对应的企微任务宝数据列表
  • 拉新排行榜
    • 获取拉新排行榜活动列表
  • 自定义表单
    • 获取自定义表单列表
    • 自定义表单用户与表单关系列表
    • 自定义表单提交数据详情列表
    • 获取自定义表单分组列表
  • 客户转化
    • 批量新增手机线索转化
  • 员工个人群发记录管理
    • 获取员工个人群发记录列表
    • 获取员工个人群发记录结果列表
  • 渠道码管理
    • 获取渠道码列表
    • 获取渠道码加人数据
  • 素材库管理
    • 获取素材库列表
    • 获取素材库标签列表
    • 新增素材
    • 更新素材
    • 删除素材
    • 新建素材分组
    • 修改素材分组
    • 添加素材库标签
    • 删除素材库标签
    • 删除素材分组
    • 素材分组列表
  • 互动雷达管理
    • 获取雷达列表
    • 获取雷达详情
    • 添加雷达
    • 修改雷达
    • 删除雷达
    • 上传file
    • 获取雷达分组列表
    • 获取雷达客户访问记录
  • 自定义侧边栏身份校验
    • 侧边栏模块化-自定义卡片功能说明
    • 自定义侧边栏Code校验
  • 有赞订单管理
    • 获取有赞订单
    • 获取有赞订单列表
  • 小鹅通订单管理
    • 获取小鹅通TOKEN
  • 项目管理
    • 项目列表
  • 门店信息
    • 批量导入门店
    • 批量更新门店
    • 门店列表
  • 人群包
    • 人群包列表获取
    • 创建人群包
    • 更新人群包
    • 创建的人群包中添加数据
    • 获取人群包数据详情
  • 客户群发
    • 客户群发创建
    • 群发任务列表
    • 群群发详情获取
    • 员工群发结果
    • 客户群群发创建
    • 员工-群群发结果
    • 获取群发错误unionid/extid
  • 企微朋友圈
    • 企微朋友圈创建
    • 企微朋友圈任务列表
    • 企微朋友圈任务发表详情
  • 个人SOP
    • 个人SOP列表
    • 个人SOP详情-规则列表
    • 个人SOP详情-执行记录
  • 部门管理
    • 获取部门列表
  • 群标签管理
    • 获取群聊标签分组及其子列表
    • 群聊批量打标签
  • 话术库
    • 企业话术分组列表
    • 企业话术列表
  • 企微数据专区
    • 获取会话消息(企微数据专区)
  1. 消息订阅

订阅消息加解密指南

订阅消息加解密指南#

概述#

微伴助手在推送消息给企业时,会对消息内容做AES加密,以JSON格式POST到企业应用的URL上。
企业在被动响应时,也需要对数据加密,以JSON返回给微伴助手。
本章节即是对加解密方法的说明。
阅读本章节前,需要了解以下术语:
msg_signature: 消息签名,用于验证请求是否来自为微伴助手(防止攻击者伪造)。
EncodingAESKey:用于消息体的加密,长度固定为43个字符,从a-z, A-Z, 0-9共62个字符中选取,是AESKey的Base64编码。解码后即为32字节长的AESKey
AESKey=Base64_Decode(EncodingAESKey + "=")
AESKey:AES算法的密钥,长度为32字节。AES采用CBC模式,数据采用PKCS#7填充至32字节的倍数;IV初始向量大小为16字节,取AESKey前16字节,详见:http://tools.ietf.org/html/rfc2315
msg:为消息体明文,格式为JSON
msg_encrypt:明文消息msg加密处理后的Base64编码。

使用已有库#

初始化加解密类#

WBMsgCrypt wbcpt(sToken,sEncodingAESKey,sReceiveId);
要求传参数sToken,sEncodingAESKey,sReceiveId。
sToken,sEncodingAESKey即在微伴助手配置的Token、EncodingAESKey;ReceiveId表示CorpId。

验证URL函数#

本函数实现:
1.
签名校验
2.
解密数据包,得到明文消息内容
int VerifyURL(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sEchoStr, string &sReplyEchoStr);
参数说明
参数必须说明
sMsgSignature是从接收消息的URL中获取的msg_signature参数
sTimeStamp是从接收消息的URL中获取的timestamp参数
sNonce是从接收消息的URL中获取的nonce参数
sEchoStr是从接收消息的URL中获取的echostr参数。注意,此参数必须是urldecode后的值
sReplyEchoStr是解密后的明文消息内容,用于回包。注意,必须原样返回,不要做加引号或其它处理

解密函数#

本函数实现:
1.
签名校验
2.
解密数据包,得到明文消息结构体
int DecryptMsg(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sPostData, string &sMsg);
参数说明
参数必须说明
sMsgSignature是从接收消息的URL中获取的msg_signature参数
sTimeStamp是从接收消息的URL中获取的timestamp参数
sNonce是从接收消息的URL中获取的nonce参数
sPostData是从接收消息的URL中获取的整个post数据
sMsg是用于返回解密后的msg,以json组织

加密函数#

本函数实现:
1.
加密明文消息结构体
2.
生成签名
3.
构造被动响应包
int EncryptMsg(const string &sReplyMsg, const string &sTimeStamp, const string &sNonce, string &sEncryptMsg);
参数说明
参数必须说明
sReplyMsg是返回的消息体原文
sTimeStamp是时间戳,调用方生成
sNonce是随机数,调用方生成
sEncryptMsg是用于返回的密文,以json组织

原理详解#

消息体签名校验#

为了让企业确认调用来自微伴助手,微伴助手在回调给接收消息url时会带上消息签名,以参数msg_signature标识,企业需要验证此参数的正确性后再解密。
验证步骤如下:
1.
计算签名
dev_msg_signature=sha1(sort(token、timestamp、nonce、msg_encrypt))。
sort的含义是将参数值按照字母字典排序,然后从小到大拼接成一个字符串
sha1处理结果要编码为可见字符,编码的方式是把每字节散列值打印为%02x(即16进制,C printf语法)格式,全部小写
2.
比较dev_msg_signature和msg_signature是否相等,相等则表示验证通过
3.
在被动响应消息时,企业同样需要用如上方法生成签名并传给微伴助手

明文msg的加密过程#

1.
拼接明文字符串
rand_msg = random(16B) + msg_len(4B) + msg + corp_id
明文字符串由16个字节的随机字符串、4个字节的msg长度、明文msg和corp_id拼接组成。其中msg_len为msg的字节数,网络字节序;corp_id表示公司id。
2.
对明文字符串加密并Base64编码
msg_encrypt = Base64_Encode(AES_Encrypt(rand_msg))
将明文字符串AESKey加密后,再进行Base64编码,即获得密文msg_encrypt。

密文解密得到msg的过程#

1.
对密文BASE64解码
aes_msg=Base64_Decode(msg_encrypt)
2.
使用AESKey做AES-256-CBC解密
rand_msg=AES_Decrypt(aes_msg)
3.
去掉rand_msg头部的16个随机字节和4个字节的msg_len,截取msg_len长度的部分即为msg,剩下的为尾部的corp_id
4.
验证解密后的corp_id、msg_len。~~~~
修改于 2022-02-23 07:27:25
上一页
访问频率和并发限制
下一页
回调应用配置指南
Built with