# 业务接口格式规范

# 请求格式说明

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

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

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

验证步骤如下:

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

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

外勤365开放接口URL格式如下:
https://openapi.waiqin365.com/api/{应用编码}/{应用版本}/{接口编码} /{openid}/{timestamp}/{disgest}/{msg_id}

参数说明:

URL参数 格式说明
应用编码 需要对接的功能模块,如部门信息为:organization
应用版本 对接应用的版本号,如:v1
接口编码 对接应用的接口,如新增部门:addOrganization
openid 企业接入唯一授权标识,为19位随机字符串,由外勤365统一分配
appkey 企业授权数据签名密钥,为18位随机字符串,由外勤365统一分配
timestamp 请求消息时间,格式为:yyyyMMddHHmmSS如:20140701142836
digest 数据签名,用于验证数据的真实性
msg_id 消息ID,发送消息的唯一标识,响应时原值返回

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

# 举例说明:

新增部门接口示例:

企业OPENID: 5465103569540931532

企业APPKEY: BFCO0PAgIUgd50c0l6

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

获取时间戳为:20150806142836

生成消息ID:ORG00001 (随机生成)

1)拼接为一个字符串:

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

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

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

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

3)生成请求URL: https://openapi.waiqin365.com/api/organization/v1/addOrganization/5465103569540931532/20150806142836/74267bf0cae0998a719879ec9b3c7780/ORG00001

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

# 响应格式说明

返回结果:

{
    "msg_id": "90b4b267dd3d49aeace879038b1e7291",
    "response_data": "[{\"org_name\":\"掌控网络下级部门\",\"org_id\":\"zk001\",\"org_sequence\":\"11\",\"org_code\":\"zhangkong\",\"org_status\":\"1\",\"org_parent_id\":\"zk01\"}]",
    "return_code": 0,
    "return_msg": ""
}

参数说明:

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