TIP

# 业务接口格式规范

# 1.请求格式说明

开放接口服务器通过检验digest对请求进行校验（下面有校验方式）。若确认此次POST请求为正常请求，则接入生效，否则接入失败。

目前勤策已提供了Java、Go、Python、C#、NodeJS、php版本的接入代码示例 (opens new window)，如果开发者需要进行别的语言的开发，需要自行根据加解密原理实现算法。

为了确认接口调用来自勤策的授权企业，企业在调用勤策接口时必须带上消息签名，以参数digest标识，勤策需要验证此参数的正确性后再进入具体业务流程。

验证步骤如下：

勤策开放接口服务器获得请求参数后，重新根据签名算法规则生成数据签名server_digest，比较digest和server_digest是否一致，一致则表示验证通过。

# 请求格式V2（推荐）

勤策开放接口URL格式如下：

https://openapi.qince.com/api/{应用编码}/{应用版本}/{接口编码}/{openid}/{timestamp}/{nonce}/{msg_id}
Content-Type: application/json
encrypt-version: v2
digest: ****************************

json格式请求消息体

请求头说明：

请求头	格式说明
encrypt-version	数据摘要算法版本，传固定值:v2 (指定sha256算法)
digest	数据签名信息，用于校验数据传输信息是否为真实请求信息，encrypt-version=v2时，签名用SHA256加密用64位小写表示，示例：6adaf9445dbf6a945b6c5ed15f9062eb6a82329e78228c2f0e5a5fb4321cf5f3。生成算法详见下面一节`生成签名算法说明V2`

参数说明：

URL参数	格式说明
应用编码	需要对接的功能模块，每个接口URL的第一个路径参数，标准模块示例：organization 带子模块的路径示例：cuxiao/close
应用版本	对接应用的版本号，每个接口URL的第二个路径参数，示例：v1
接口编码	对接应用的接口方法名，每个接口URL的第三个路径参数，示例：新增部门：queryOrganization
openid	企业接入唯一授权标识，为19位字符串，由勤策统一分配，示例：8519670967275282420
appkey	非请求参数，请求信息加密秘钥，企业授权数据签名密钥，为18位字符串，由勤策统一分配，示例：ipA1CBM7RoXJb6jyhu
timestamp	请求消息时间戳，表示从1970年1月1日00:00:00（UTC）开始，到某个具体时刻为止，总共经过的毫秒数，如：1617206400000。当OpenAPI开启安全校验时会对时间戳做校验。
nonce	随机字符串（由数字、字母以及下划线组合生成的随机字符串），用于数据传输的安全性校验，示例：INj7vO。
msg_id	消息ID，由第三方随机生成的唯一标识,一般为32位随机字符串或uuid，勤策系统从URL请求参数中获取msg_id后原样返回，用于跟踪和排查问题，示例：365e6859a23849d1bf0ab5166fb6543d

生成签名算法说明V2：

计算签名digest工具：签名工具 (opens new window)
digest=sha256(joint(data=${json格式请求消息体}&appkey=${APPKEY}&nonce=${6位随机字符串}&timestamp=${UTC时间戳(毫秒)}))
joint 的含义是将参数值按照格式拼接成一个字符串，$｛xx｝为占位符。再进行sha256编码，即获得数据签名digest。下文有举例说明。
注意： 生成签名时的json格式请求消息体要和请求体中内容完全一致(包括空格回车等)。

# 请求格式V1

勤策开放接口URL格式如下：

https://openapi.qince.com/api/{应用编码}/{应用版本}/{接口编码}/{openid}/{timestamp}/{disgest}/{msg_id}

json格式请求消息体

参数说明：

URL参数	格式说明
应用编码	需要对接的功能模块，每个接口URL的第一个路径参数，标准模块示例：organization 带子模块的路径示例：cuxiao/close
应用版本	对接应用的版本号，每个接口URL的第二个路径参数，示例：v1
接口编码	对接应用的接口方法名，每个接口URL的第三个路径参数，示例：新增部门：queryOrganization
openid	企业接入唯一授权标识，为19位字符串，在勤策系统中电脑端申请，示例：8519670967275282420
appkey	非请求参数，请求信息加密秘钥，企业授权数据签名密钥，为18位字符串，在勤策系统中电脑端申请，示例：ipA1CBM7RoXJb6jyhu
timestamp	请求消息时间戳，表示从1970年1月1日00:00:00（UTC）开始，到某个具体时刻为止，总共经过的毫秒数，如：1617206400000。当OpenAPI开启安全校验时会对时间戳做校验。
msg_id	消息ID，由第三方随机生成的唯一标识,一般为32位随机字符串或uuid，勤策系统从URL请求参数中获取msg_id后原样返回，用于跟踪和排查问题，示例：365e6859a23849d1bf0ab5166fb6543d
digest	数据签名信息，用于校验数据传输信息是否为真实请求信息。签名用Md5加密，用32位小写表示，示例：b7b7d9810bbb0786e9560751dc2b6597。生成算法详见下面一节`生成签名算法说明V1`

生成签名算法说明V1：

计算签名digest工具：签名工具 (opens new window)
digest=md5(joint(json格式消息体|appkey|timestamp))
joint 的含义是将参数值 json格式消息体|appkey|timestamp 按照从左到右的顺序拼接成一个字符串，再进行md5编码，即获得数据签名digest。下文有举例说明。
注意： 生成签名时的json格式请求消息体要和请求体中内容完全一致(包括空格回车等)。

注意：

OpenID和Appkey获取方法
   如果您已经购买了OpenAPI版本，可在“系统管理”-“集成管理”-“API管理”-“OpenAPI授权”中申请。

OpenAPI 接口返回值是 JSON 格式。在即将到来的版本中，接口可能会新增字段。为了确保您的应用程序能够正常运行，请注意以下几点：
 （1）解析时的兼容性：使用灵活的 JSON 解析方法，不要对返回的 JSON 字段进行严格绑定。确保新增字段不会导致解析错误。
 （2）使用默认值：在处理可能缺失的字段时，设置合理的默认值，以防止因字段缺失导致的异常。
 （3）保持接口文档更新：定期查看接口文档，了解新增字段的意义和用途。
 （4）测试覆盖：在测试中包含对新增字段的处理，确保应用程序在不同接口版本下都能正常运行。
 （5）日志记录：在解析 JSON 时记录日志信息，以便在出现问题时能够快速定位和解决。

# 3.请求格式V2示例说明：接口代码参考示例 (opens new window)

查询部门接口示例：

企业OpenAPI域名: openapi.qince.com

企业OpenID: 8519670967275282420

企业Appkey: ipA1CBM7RoXJb6jyhu

消息体json_data：{"org_status":"1"}

随机字符串nonce：INj7vO

获取时间戳为：1779088096641

生成随机消息ID：365e6859a23849d1bf0ab5166fb6543d

1)拼接为一个字符串：

joint_str data={"org_status":"1"}&appkey=ipA1CBM7RoXJb6jyhu&nonce=INj7vO&timestamp=1779088096641

2)对该字符串进行SHA256计算得到签名

digest SHA256(joint_str),对下面字符串进行SHA256加密：

data={"org_status":"1"}&appkey=ipA1CBM7RoXJb6jyhu&nonce=INj7vO&timestamp=1779088096641

生成数据签名(digest)为：6adaf9445dbf6a945b6c5ed15f9062eb6a82329e78228c2f0e5a5fb4321cf5f3

3)生成请求示例：

https://openapi.qince.com/api/organization/v2/queryOrganization/8519670967275282420/
1779088096641/INj7vO/365e6859a23849d1bf0ab5166fb6543d
Content-Type: application/json
encrypt-version: v2
digest: 6adaf9445dbf6a945b6c5ed15f9062eb6a82329e78228c2f0e5a5fb4321cf5f3

{"org_status":"1"}

4)勤策开放接口服务器根据请求头参数encrypt-version,如果是v2, 则根据上面规则和参数信息生成的服务端数据签名 server_digest ，将 server_digest和从请求头 digest 得到的数据签名，进行比对如果两者一致，数据签名通过，说明数据没被篡改，验证通过。

# 4.响应格式说明

响应体整体结构为两层JSON格式消息，外层JSON格式包括，return_code、return_msg、msg_id、response_data几个属性是为基本响应结构，所有API响应结构都一致。其中response_data中内容为字符串，可以转为JSON结构体。response_data中消息结构各个接口都有单独定义，如下面的数据DATA示例内容。

响应示例：

{
    "return_code": "0",
    "return_msg": null,
    "msg_id": "365e6859a23849d1bf0ab5166fb6543d",
    "response_data": "<<DATA>>"
}

数据DATA示例:

[
        {
            "id": "10",
            "org_id": "ORG001",
            "org_name": "南京掌控网络",
            "waiqin365_parent_id": "-1",
            "org_parent_id": "",
            "parent_code": "",
            "parent_name": "",
            "department_type": "1",
            "full_ids": "/10",
            "full_codes": "/DD001",
            "full_names": "/南京掌控网络",
            "org_sequence": "0",
            "org_status": "1",
            "org_code": "DD001",
            "sales_org_id": "C123",
            "waiqin365_org_id": "9984557052567005824",
            "create_time": "2017-09-09 13:14:11",
            "modify_time": "2018-09-09 13:14:11"
        }
]

参数说明：

参数	说明
return_code	响应码。0：成功，1：失败。错误码说明 (opens new window)
return_msg	响应信息，后续可能会有变动，因此不可作为是否调用成功的判据
msg_id	消息ID，由第三方随机生成的唯一标识，勤策系统从URL请求参数中获取msg_id后原样返回
response_data	响应数据: JSON格式的字符串消息体

← 基本概念介绍推送接口格式规范 →