API开放平台

TIP

# 附录七 常见问题 - FAQ

1.调用API接口时返回错误码“101”
2.调用API接口时返回错误码“102”
3.调用API是返回错误码“104”
4.调用API时返回HTTP状态码“405”
5.调用API时请求数据体中非必填参数如何传值
6.调用API时报域名解析失败错误(java.net.UnKnownHostException)
7.调用API时，ID和编码的区别
8.调用API时，勤策ID和第三方ID的区别
9.调用API时返回的json的字段为何会比参数说明标注的多
10.调用API时请求示例里面的示例参数为何会比参数说明标注的少
11.调用API时如果获取分页数据
12.调用API息时请求消体和返回消息体采用何种数据格式
13.地图地址无法解析
14.调用api修改和删除接口传值注意事项
15.接口字段优先级排序
16.怎样找到公司账号对应的数据中心REGION区域

1.调用API接口时返回错误码“101”
企业唯一授权标识校验失败，首先排查openID和Appkey录入是否有误，如果录入无误，再向客户经理确认openApi接口访问能力是否已经开通
2.调用API接口时返回错误码“102”
错误码102是签名错误，请参考“业务接口格式规范”按照说明生成签名信息。注意：生成签名时的数据要和请求体中数据保持一致，包括空格回车等。
3.调用API是返回错误码“104”
错误码104表示实际请求接口的IP地址不在企业授权访问接口的IP地址列表中
4.调用API时返回HTTP状态码“405”
API接口仅支持POST请求，如果请求方式为GET，服务器会返回405状态码
5.调用API时请求数据体中非必填参数如何传值
API接口如果参数非必填且业务中不需要对该数据信息做操作，请求数据时就不要带该参数信息。系统不允许传递值为NULL的参数。
6.调用API时报域名解析失败错误(java.net.UnKnownHostException)
如果请求时出现域名解析失败时可以在本地请求服务器hosts文件中增加本地域名解析，如下：
118.31.179.45 openapi.waiqin365.com
7.调用API时，ID和编码的区别
ID是业务数据中不可变更，不可见的唯一标识，值为Long型的UUID，如7053012386494123505；编码是业务数据中可见的唯一标识，在数据中是不唯一的，如：正常状态和删除状态下都有一个emp_code=‘张强’的员工。
8.调用API时，勤策ID和第三方ID的区别
API接口中有勤策ID和第三方ID两类唯一标识符，勤策ID是勤策系统的唯一标识符，值为Long型的UUID，如7053012386494123505。第三方ID是来源于第三方系统的唯一标识，通过API新增接口产生的业务数据中此字段必填。
通过WEB页面新增产生的业务数据中是无此字段的。API修改接口中，根据勤策ID或者第三方ID进行修改操作，二者不能同时为空，如果同时存在优先取勤策ID；API删除接口中，根据第三方ID进行删除操作。
9.调用API时返回的json的字段为何会比参数说明标注的多
为了对旧接口做兼容，会将过时字段保留一段时间，但是API文档中不再做描述，所以使用接口过程中请严格按照参数说明取值，已过时字段请勿使用。
10.调用API时请求示例里面的示例参数为何会比参数说明标注的少
请求示例里面的示例仅起到一个抛砖引玉的作用，第三方系统需要根据自己系统的实际情况调整请求示例中的参数，所以使用接口过程中请严格按照参数说明取值。
11.调用API时如果获取分页数据
page_number是分页页码，默认为1；如无特别说明，每页默认返回1000条数据且不可变更；第一次获取到小于1000条的数据表示当前页是最后一页。
12.调用API时请求消息体和返回消息体采用何种数据格式
请求消息体和返回消息体都采用JSON格式数据，json格式是可以动态扩展的。接口中如无特殊说明，一律使用双括号{}表示空对象。
根据JSON官网最新规范规定，如果是字符串，那不管是键或值最好都用双引号引起来，如{"name": "Michael"} 。
13.地图地址无法解析
首先到网址https://lbs.amap.com/tools/picker看一下这个经纬度是否可以正常解析。一般勤策解析不了的经纬度都在大洋或者湖泊里。请规范同步到勤策的数据。
14.调用api修改和删除接口传值注意事项
勤策中的数据删除采用的是逻辑删除，即把status=1修改成status=0。每一个更新操作都会修改更新时间modify_time，因此通过modify_time可以同时获取到修改和删除数据。
勤策的修改接口中，都是以勤策的id或者第三方的id作为关键字来更新整条记录的。
15.接口字段优先级排序
勤策的id、code、name和第三方id同时存在时，优先级从高到低排序：勤策的id > 第三方id > code > name
16.怎样找到公司账号对应的数据中心REGION区域
以管理员账号登录勤策WEB端，在菜单中搜API授权，打开二维码后手机APP登录管理员账号，通过手机APP扫码后，WEB端将打开API授权列表，在列表页标题中
显示OpenAPI地址，如：https://openapi.region2.qince.com

# 联系我们

如果您在开发过程中遇到问题，可以发送邮件到apisupport@waiqin365.com咨询。 邮件格式如下：

标题：企业API接入问题咨询 内容示例：

参数 说明
企业名称 XXXX
问题描述 具体问题描述信息
请求接口URL https://openapi.waiqin365.com/api/XXX/XXX/XXX/{ openid }/{ timestamp }/{ digest }/{ msg_id }
请求体 {"emp_id": "ORG00001" }
响应信息 { "return_code": "0", "return_msg": "响应信息", "msg_id": "{ msg_id }", "response_data": "XXXX" }

←