COP平台开放写入OpenAPI（推荐）

  2 分钟阅读  

1、概述

COP平台开放写入OpenAPI，由三方异构系统定时增量推送，完成消息同步模式。

2、核心字段定义

术语	定义	来源	测试数据
appKey	V8统一认证中心分配给每个接入应用的唯一标识Id，别名应用Id	致远COP	3e4a140e2509477396fa04ddcd70c3d2
AppSecret	V8统一认证中心分配给每个接入应用的加密解密秘钥，别名应用秘钥	致远COP	5bad0b6618934c62bffefe4cc0d8c03d
url前缀	文档中所有接口的请求前缀	致远COP	http://openapi-bpm.CC.com.cn
capabilityId	同步能力编码，针对消息同步场景	致远COP	1457957992996539915

3、应用场景

由业务系统定义消息触发条件，并调用【批量同步消息】接口发送消息，数据呈现在【消息中心】栏目；

4、接口签名

4.1、请求头（Header）

参数名称	是否必填	参数说明
app-key	true	应用的唯一标识，创建接入应用后生成，可在应用基础信息页面获得。 示例：d43b0b442cf34076a2c4af6bb8928afb
sign-type	true	固定值：MD5
sign	true	签名，字符串“AppSecret+请求体的JSON字符串+AppSecret”的MD5值（MD5值忽略大小写） AppSecret，为应用的秘钥，创建接入应用后生成，可在应用基础信息页面获得。 示例：154fa5bc7e294deda68a15559b07c845请求体的JSON字符串， 需要将请求体中的请求参数转换为JSON字符串。
Accept-Language	false	语种：用以设置开放平台OpenAPI运行时上下文的语种参数。 枚举项可选值列表：zh-CN（简体中文）， zh-TW（繁体中文）， en（英文）， 其他枚举项请参照平台语种列表。

4.2、签名示例（sign）

String secret = "154fa5bc7e294deda68a15559b07c845";
String body = "{"name": "张三", "age": 35, "company": {"name": "致远", "address": "北京"}";
String sign = Md5(secret + body + secret); // 结果是 01a8795a7fe6dda23aaec40de3d301b7;

5、集成配置

5.1. 新建集成应用

5.2. 配置单点登录

5.3、新建消息同步,获取消息同步能力编码

5.4、发布应用

5.5、启用API

5.6、新建接入应用

5.7、启用接入应用

5.8、分配APPKey和AppSecret

5.9、应用级别API授权

5.10、按需开启IP白名单

5.11、按需开启限流控制

5.12、API调用日志

6、接口清单

6.1. 【批量】 批量同步消息

6.1.1. 请求地址：

【url前缀】/cip-manager/plugin-affair/create-update

6.1.2. 请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	PluginMessageBatchDto	请求参数数据
capabilityId	data	true	int64	事项所属基础插件能力。复用插件的用户映射，单点登录等配置。
idType	data	false	enum	发起人/处理人标识类型， 不传递默认OUTER_ID（三方系统ID）。 枚举项可选值列表： OUTER_ID（三方系统ID）， V8_ID（V8内部ID）， V8_CODE（V8系统编号）， V8_LOGIN_NAME（V8登录名）， V8_PHONE（V8手机号）
messageList	data	true	array[PluginMessageDetailDto]	消息列表
senderId	messageList	false	string	消息发起人标识
externalMessageId	messageList	true	string	消息外部编号
messageSourceCode	messageList	false	string	消息来源
title	messageList	true	string	消息标题
createTimeStamp	messageList	false	int64	消息创建时间戳
openType	messageList	false	string	详情打开方式： WORKSPACE（工作区）， NEWWINDOW（新窗口，默认值）
todoWebUrl	messageList	false	string	消息WEB端详情地址
todoMobileUrl	messageList	false	string	消息移动端详情地址
receiverDto	messageList	true	MessageReceiverDto	消息接收人对象
userIdList	receiverDto	false	array[string]	消息接收者标识列表（按人员发送消息）。 和unitCodeList至少填一个
unitCodeList	receiverDto	false	array[string]	接收者V8组织编号列表（按组织发送消息）。 和userIdList至少填一个
extendSign	receiverDto	false	boolean	组织是单位时是否包含下级单位（组织是部门时， 固定包含下级部门）

6.1.3. 请求示例

{
  "data": {
    "messageList": [
      {
        "senderId": "MB202306070002",/*致远OA用户Code*/
        "externalMessageId": "11000102",/*业务系统消息Id，唯一*/
        "createTimeStamp": 1688033651186,/*请求时间戳,毫秒级*/
        "todoMobileUrl": "https://www.baidu.com",/*待办事项移动端详情页URL地址*/
        "title": "测试消息头2023年4月19日14:17:06",/*消息标题*/
        "receiverDto": {
          "userIdList": ["MB202306070002"]/*致远OA用户Code*/
        },
        "todoWebUrl": "https://www.baidu.com",/*消息PC端待处理页URL地址*/
         "openType":"NEWWINDOW"/*枚举值，打开方式*/
      }
    ],
    "capabilityId": "1498469601665614061",/*固定值*/
    "idType":"V8_CODE"/*枚举值*/
  },
  "requestId": "1395143136501500012",/*请求流水号，每次请求唯一*/
  "timestamp":1688033651186/*请求时间戳,毫秒级*/
  }

6.1.4. 返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	void	数据对象
status		int32	状态
code		string	错误码
message		string	返回信息

6.1.5. 返回示例

{
    "status": 0,/*成功标识*/
    "code": "BOOT_0000",/*错误码*/
    "message": "SUCCESS",/*返回信息*/
    "data": null
}