- 搭贝学院
- 对接协议
- 开放对接协议
概述
本openapi目前处于内测阶段，本文档仅临时对特定用户开放。 注：正式文档发布前，可能会有变动，为减少可能存在返回工，请在实际开发启动前，联系客服人员确认以是否存在更新版本
简介
开放接口服务(open api)是搭贝能力开放平台的核心服务之一，为搭贝用户提供统一、安全的双向数据传输服务，赋予用户终端应用个性化需求的多维支撑能力。 开放接口openapi及webhook均以本协议实现数据传输。
术语说明
- 平台：特指搭贝能力开放平台，为用户提供各类功能，为用户提供更多自定义开发能力，功能包括但不限于开放接口、数据推送、自定义组件/页面、oa接入等。
- 用户：特指搭贝用户，接入平台的用户即为接入方。
- 第三方服务：用户服务可能涉及除搭贝及自身独立的其他服务，如银行类接口，统一称第三方服务。
协议说明
接口采用https协议做为基本载体，结合签名、加密等机制以达到数据准确、安全传输的目的。
开发须知
在对接开放接口之前，需要先了解如下数据。
- 获取/配置，使用管理员进入应用工厂，获取开放接口的配置数据
 |
|---|
注：内测阶段， 平台暂不提供图形配置，请联系客服由开发提供
| 数据项 | 参数说明 | 备注 |
|---|---|---|
| api_key | string，用户身份的标记 | 由平台为用户分配，需要接入侧保存。注：内测阶段仅一个租户开放一个apiKey |
| signing_key | string，参与HmacSHA256摘要数据 | 由平台分配或用户自定义生成，用于数据传输中签名/摘要使用 |
| secret_key | string，aes数据加密密钥 | 由平台分配或用户自定义生成，用于body报文的加解密使 |
请求地址
钉钉 api地址：https://ding.idabei.com/open_api
微信 api地址：https://wechat.idabei.com/open_api
公共参数
| 参数名 | 参数类型 | 必填 | 说明 |
|---|---|---|---|
| Authorization | string，header，认证格式 | 是 | 参考格式Authorization: Bearer api_key，注意首字母A大写，将参与签名 |
| api_version | string，header中，版本号 | 是 | 目前可固定: v1.0 |
| random_str | string，32位随机数 | 是 | 用于签名校验。注意区分大小写 |
| timestamp | number，时间戳 | 是 | 用于签名校验，请使用发起请求时的时间，注意为ms |
| signature | string，摘要/签名 | 是 | 防止数据篡改 |
规则要求
- 遵循统一的REST的设计风格
- 请求都统一为HTTPS
- 数据传输编码为 UTF-8
- 请求体中数据密文传输
- 响应体中数据密文传输
- 时效性为1小时，请求不再处理
- 同一用户请求限制5次/秒
错误码
| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 400 | 失败 |
| 错误码 | 说明 |
|---|---|
| 4001 | 用户认证失败 |
| 4002 | 不合法的版本 |
| 4002 | 不合法的参数 |
| 4003 | 校验签名失败 |
| 4004 | 业务参数无效 |
| 9999 | 其它错误 |
开发指南
签名生成
- 签名串格式
- 签名串至多4行(对于get请求为3行)，每一行为一个参数，如果有下一行，行尾以 \n（换行符，ASCII编码值为0x0A）结束，不包括最后一行。
URI\n
请求头apiKey\n
请求参数字符串\n
请求报文主体
- 构造签名串
以创建表单数据为例：
获取请求的uri
获取请求的绝对URL，并去除域名部分得到参与签名的URI，注意不包括查询参数
/open_api/apps/app00001/forms/form00001/record_create
获取请求头Authorization中的api_key，注意需要去掉Bearer
d8e0001634bd48b4bf9d999eb3d103e2
获取参数字符串，需要对请求参数数据key按自然顺序排序，把请求要素按照“参数=参数值”的模式用“&”字符拼接成字符串。
random_str=X3oZ21AmdXTuYMl8IJY0hCJLoamryaLd×tamp=1643008040000
- 获取请求报文主体
将请求报文进行json字符串转换，没有请求体，则不参与。
- 参与签名的请求体必须明文，不能是加密后密文
- 计算签名值
采用HmacSHA256算法对字符串进行摘要算法，这里我们假定signing_key的值为123，然后对其进行base64编码得到signature
对“1792783e37457f468fa296436d79cf89af6e28e920a357f5ae778f3fc48dcd58”进行base64编码得到signature为：
MTc5Mjc4M2UzNzQ1N2Y0NjhmYTI5NjQzNmQ3OWNmODlhZjZlMjhlOTIwYTM1N2Y1YWU3NzhmM2ZjNDhkY2Q1OA==
目前平台只针对请求的body和响应的body中data参数加密，加密方式为aes对称加密。 ecb/128/base64输出
- 注意：使用openssl，需要将secretKey指定为ascii码的16进制格式，如下方，secretKey原文为：1234567890123456，其16进制为31323334353637383930313233343536
- 响应体的只有data为密文，整体的errcode和errmsg等协议数据，参考如下
{
"errcode": 0,
"errmsg": "success",
"data": "cRCw/5b+TfUPMY0d5AU8RaTUj27aa8R6xiyctUDXFHQA8LYhT6LwESLSWXR00YzQ"
}
加密演示
echo -n '{"param1":"value1","param2":"value2"}'
| openssl enc -aes-128-ecb -e -K 31323334353637383930313233343536 -nosalt -a
//得到aes加密结果
cRCw/5b+TfUPMY0d5AU8RaTUj27aa8R6xiyctUDXFHQA8LYhT6LwESLSWXR00YzQ
- 解密演示
echo 'cRCw/5b+TfUPMY0d5AU8RaTUj27aa8R6xiyctUDXFHQA8LYhT6LwESLSWXR00YzQ'
| openssl enc -aes-128-ecb -a -d -K 31323334353637383930313233343536 -nosalt
//得到aes解密结果
{"param1":"value1","param2":"value2"}
签名验签
签名验证用于双向校验，对于用户即接入方校验平台的数据推送签名，而平台侧校验接入方的数据同步
- 身份认证
header中请获取Authorization， 得到对应的api_key，并判断该api_key是否和平台分配给自己的值相同，如果不相同，则认为请求无效
Authorization: Bearer d8e0001634bd48b4bf9d999eb3d103e2
- 签名校验
对于接入方而言，需要按上方签名生成的步骤，走一遍摘要算法，得到值后同参数中的signature对比，如果相同则验证通过。
- 签名前需要对body解密