TIP

# 业务接口格式规范

# 请求格式说明

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

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

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

验证步骤如下：

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

2)勤策开放接口服务器获得请求参数后，重新根据规则生成数据签名dev_digest，比较digest和dev_digest是否相等，相等则表示验证通过

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

https://{region}/api/{应用编码}/{应用版本}/{接口编码}/{openid}/{timestamp}/{disgest}/{msg_id}

参数说明：

URL参数	格式说明
region	企业所在数据中心OpenAPI域名，如为：openapi.region1.qince.com, 如何获取? (opens new window)
应用编码	需要对接的功能模块，如部门信息为：organization
应用版本	对接应用的版本号，如：v1
接口编码	对接应用的接口，如新增部门：addOrganization
openid	企业接入唯一授权标识，为19位随机字符串，由勤策统一分配
appkey	企业授权数据签名密钥，为18位随机字符串，由勤策统一分配
timestamp	请求消息时间。格式：yyyyMMddHHmmSS。如：20140701142836
digest	数据签名，用于验证数据的真实性
msg_id	消息ID，由第三方随机生成的唯一标识，勤策系统从URL请求参数中获取msg_id后原样返回

注意： openid和appkey须由企业管理员向客户经理申请分配

# 举例说明：接口代码参考示例 (opens new window)

新增部门接口示例：

企业OpenAPI域名REGION: openapi.region1.qince.com

企业OPENID: 5465103569540931532

企业APPKEY: BFCO0PAgIUgd50c0l6

消息体json_data：{"org_id":"ORG001","org_name":"南京掌控网络","org_parent_id":"","org_sequence":100}

获取时间戳为：20150806142836

生成消息ID：ORG00001 (由第三方随机生成的唯一标识，勤策系统从URL请求参数中获取msg_id后原样返回)

1)拼接为一个字符串：

joint_str={"org_id":"ORG001","org_name":"南京掌控网络","org_parent_id":"","org_sequence":001}|BFCO0PAgIUgd50c0l6|20150806142836

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

digest=Md5(joint_str)

生成数据签名(digest)为：74267bf0cae0998a719879ec9b3c7780

3)生成请求URL：

https://openapi.region1.qince.com/api/organization/v1/addOrganization/5465103569540931532/
20150806142836/74267bf0cae0998a719879ec9b3c7780/ORG00001

4)勤策开放接口服务器对比自身生成的数据签名 dev_digest 和从URL得到的数据签名 digest，发现两者一致，数据签名通过，说明没被篡改，是安全的

# 响应格式说明

响应示例：

{
    "return_code": "0",
    "return_msg": null,
    "msg_id": "90b4b267dd3d49aeace879038b1e7291",
    "response_data": "<<DATA>>"
}

数据DATA示例:

[
    {
        "org_name":"掌控网络下级部门",
        "org_id":"zk001",
        "org_sequence":"11",
        "org_code":"zhangkong",
        "org_status":"1",
        "org_parent_id":"zk01"
    }
]

参数说明：

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

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