创建
优质
小牛编辑
145浏览
2023-12-01
请求地址
https://api.es.xiaojukeji.com/river/Approval/create
返回数据格式
JSON
请求类型
POST
请求参数
参数名称 | 数据类型 | 必选 | 说明 |
member_type | int | no | 唯一标识类型(0-手机号,1-工号,2-邮箱,默认为0) |
client_id | string | yes | 申请应用时分配的AppKey |
access_token | string | yes | 授权后的access token |
timestamp | string | yes | 当前时间戳 |
company_id | string | yes | 企业ID |
phone | string | yes | 申请人手机号。默认必传,当member_type=1或2时不用传 |
employee_number | string | no | 员工工号。当member_type=1时,必传,通过工号创建审批单(反查员工信息) |
string | no | 邮箱。当member_type=2时,必传,通过邮箱创建审批单(反查员工信息) | |
regulation_id | string | yes | 制度ID |
out_approval_id | string | no | 企业主内部审批单ID(滴滴存储冗余字段),非必填时该字段不传 |
approval_type | int | yes | 审批单类型(1-差旅 travel、2-行前审批 business trip按次数、3-行前审批 business trip按日期)只能选择其一 |
type | int | no | 费用归属的成本中心类型(1部门 2项目) |
budget_center_id | string | no | 费用归属部门/项目的id,通过成本中心查询api获取id |
reason | string | no | 申请原因 |
extra_info | json | no | 扩展信息,自定义字段(必须为json字符串) |
travel_detail | object | no | approval_type=1必传,其余不传 |
business_trip_detail | object | no | approval_type=2或approval_type=3必传,其余不传 |
sign | string | yes | 签名 |
注
- 创建审批单规则:计算签名时候,需要对travel_detail或者business_trip_detail值做 json_encode 处理成字符串格式,再参与签名
- 创建审批单时:若传递的城市ID为县级市,自动替换为对应的地级市,当传递的城市ID与城市名称不一致时,以城市ID为准,替换为城市ID对应的正确城市名称
travel_detail
参数名称 | 数据类型 | 必选 | 说明 |
start_date | date | yes | 行程开始日期,如2017-01-10 |
end_date | date | yes | 行程结束日期,如2017-02-01 |
trips | array | no | 行程路线,行程使用的制度(regulation_id)中,出差城市配置为无需填写时,trips可为空。否则必传,需按照行程顺序填写 |
start_city_rule | int | no | 行程起点城市是否包含市内用车权限(0-不包含,1-包含),trips第一行视为起点城市 |
end_city_rule | int | yes | 行程终点城市是否包含市内用车权限(0-不包含,1-包含),trips最后一行视为终点城市 |
trips
参数名称 | 数据类型 | 必选 | 说明 |
departure_city | string | yes | 出发地城市名称,如北京市 |
departure_city_id | int | yes | 出发地城市id(地级市id) |
destination_city | string | yes | 目的地城市名称,如上海市 |
destination_city_id | int | yes | 目的地城市id(地级市id) |
start_date | date | yes | 行程开始日期,如2017-01-10 |
end_date | date | yes | 行程结束日期,如2017-01-20 |
注
- 为出发地城市创建【送机】和【市内用车】的用车规则。第一个行程的出发地城市无【市内用车】
- 为目的地城市创建【接机】和【市内用车】的用车规则。最后一个行程的目的地城市的【市内用车】依赖于end_city_rule
- 目前每个行程的开始日期、结束日期,依赖于travel_detail中的start_date、end_date
- 当所有的城市id都为空时,系统会根据城市名称匹配对应id,存在id匹配失败的情况;当城市id至少有一个非空,以传入的城市id为准,系统不会进行匹配。建议根据城市查询API传入对应的城市id
- 所有用车出发地城市和目的地城市参数都应传入城市级别id(当用车出发地城市和目的地城市级别为区县时,应该传入对应所属地级市城市id、区县名称)
- 当差旅制度中,出差城市配置为无需员工填写时,出发地、目的地城市传空
business_trip_detail(按次数)
参数名称 | 数据类型 | 必选 | 说明 |
start_time | datetime | yes | 开始时间,需要大于等于接口调用当前时间。时间格式为:2015-06-16 12:00:09 |
end_time | datetime | yes | 结束时间,需大于等于开始时间。时间格式为:2015-06-16 12:00:09 |
departure_city_id | int | no | 出发地城市id(指定出发地时必填) |
departure_city | string | no | 出发地城市名称(指定出发地时必填) |
destination_city_id | int | no | 目的地城市id(指定目的地时必填) |
destination_city | string | no | 目的地城市名称(指定目的地时必填) |
start_name | string | no | 出发地名称(最多50个字)(指定出发地时必填) |
start_address | string | no | 出发地详细地址(最多100个字)(指定出发地时必填) |
flat | float | no | 出发地纬度 (指定出发地时必填) |
flng | float | no | 出发地经度 (指定出发地时必填) |
end_name | string | no | 目的地名称(最多50个字)(指定目的地时必填) |
end_address | string | no | 目的地详细地址(最多100个字)(指定目的地时必填) |
tlat | float | no | 目的地纬度(指定目的地时必填) |
tlng | float | no | 目的地经度(指定目的地时必填) |
is_return | int | no | 是否往返,0-不往返,1-往返,默认为0 |
trip_times | int | yes | 用车次数,当is_return为1时,用车次数必须为偶数(去程一次+回程一次 |
perorder_money_quota | int | no | 每单限额,单位:分,需大于0生效 |
business_trip_detail(按日期)
参数名称 | 数据类型 | 必选 | 说明 |
start_time | datetime | yes | 开始时间,需要大于等于接口调用当前时间。时间格式为:2018-06-16 12:00:09 |
end_time | datetime | yes | 用车结束时间,需大于等于start_time,如2018-06-19 12:00:09 |
trips | array | no | (创建规则时如果选择了“由员工填写”则必填)用车城市列表: [{ "city_id": "1", "city": "北京" },{ "city_id": "2", "city": "上海" }] |
trip_amount | int | no | 用车金额 (不传默认不限制金额) 单位 分 |
差旅请求参数示例:
{
"client_id": "xxxxxx",
"access_token": "xxxxx",
"timestamp": "xxxxxx",
"company_id": "xxxxxx",
"phone": "xxxxxx",
"regulation_id": "xxxxxx",
"out_approval_id": "xxxxxx",
"approval_type": "1",
"travel_detail": {
"start_date": "xxxxxx",
"end_date": "xxxxxx",
"end_city_rule": "xxx",
"trips": [
{
"departure_city_id": "110000",
"departure_city": "北京",
"destination_city_id": "310000",
"destination_city": "上海",
"start_date": "2017-03-01",
"end_date": "2017-03-03"
},
{
"departure_city_id": "310000",
"departure_city": "上海",
"destination_city_id": "410000",
"destination_city": "深圳",
"start_date": "2017-03-03",
"end_date": "2017-03-05"
},
{
"departure_city_id": "410000",
"departure_city": "深圳",
"destination_city_id": "110000",
"destination_city": "北京",
"start_date": "2017-03-05",
"end_date": "2017-03-08"
}
]
},
"sign": "xxxxxxxx"
}
行前审批按次数请求参数示例:
{
"client_id": "xxxxxx",
"access_token": "xxxxx",
"timestamp": "xxxxxx",
"company_id": "xxxxxx",
"phone": "xxxxxx",
"regulation_id": "xxxxxx",
"out_approval_id": "xxxxxx",
"approval_type": "2",
"business_trip_detail": {
"start_time": "xxxxxx",
"end_time": "xxxxxx",
"departure_city_id": "110000",
"departure_city": "北京",
"destination_city_id": "110000",
"destination_city": "北京",
"start_name":"尚东数字山谷",
"start_address":"北京市海淀区XXXXXXX东北旺",
"flat":"40.044648",
"flng":"116.321149",
"end_name":"当代商城",
"end_address":"北京市海淀区安宁庄西路18号",
"tlat":"40.044648",
"tlng":"116.321149",
"is_return":"1",
"trip_times":"4",
},
"sign": "xxxxxxxx"
}
行前审批按日期请求参数示例:
{
"client_id": "xxxxxx",
"access_token": "xxxxx",
"timestamp": "xxxxxx",
"company_id": "xxxxxx",
"phone": "xxxxxx",
"regulation_id": "xxxxxx",
"out_approval_id": "xxxxxx",
"approval_type": 3,
"business_trip_detail": {
"start_time": "xxxxxx",
"end_time": "xxxxxx",
"trips": [
{
"city_id": 1,
"city": "北京"
},
{
"city_id": 2,
"city": "上海"
}
]
"trip_amount": 10000,
},
"sign": "xxxxxxxx"
}
请求示例
curl -X POST -H "content-type:application/json" \
-d '{"client_id":"client_id_test","access_token":"access_token_test","timestamp":1583485957,"company_id":"12345678980","phone":"11000001234","regulation_id":"1125901881811042","approval_type":2,"business_trip_detail":{"start_time":"2019-08-25 00:00:00","end_time":"2019-08-29 00:00:00","departure_city_id":"1","departure_city":"\u5317\u4eac","start_name":"\u5317\u4eac\u5357\u7ad9","start_address":"\u5317\u4eac\u5e02\u6d77\u6dc0\u533a\u4e1c\u5317\u65fa","flat":"40.044648","flng":"116.321149","trip_times":1},"sign":"019057df472a3224a1408a3043c5e0a6"}' \
https://api.es.xiaojukeji.com/river/Approval/create
返回参数说明
参数名称 | 数据类型 | 说明 |
approval_id | string | 审批单ID |
返回示例
{
"errno": 0,
"errmsg": "SUCCESS",
"data": {
"approval_id": "9668294457792204005"
}
}
按日期申请的请求示例
1. 请求参数
client_id = "client_id_test", access_token = "access_token_test", timestamp = 1566907865, company_id = 12345678980, phone = 11000001234,
regulation_id = 1125901881811042, out_approval_id = "abc12345678", "reason" = "测试", approval_type = 3
business_trip_detail对象为:
{
"start_time": "2019-08-28 10:00:00",
"end_time": "2019-08-30 23:59:59",
"trips": [
{
"city_id": "1",
"city": "北京"
},
{
"city_id": "4",
"city": "上海"
}
]
}
---------------------------------------------
sign_key = "sign_key_test"
2. 计算签名
2.1 首先将business_trip_detail转换为json字符串:business_trip_detail = {"start_time":"2019-08-28 10:00:00","end_time":"2019-08-30 23:59:59","trips":[{"city_id":"1","city":"\u5317\u4eac"},{"city_id":"4","city":"\u4e0a\u6d77"}]}
2.2 拼接加密前的字符串:str = access_token=access_token_test&approval_type=3&business_trip_detail={"start_time":"2019-08-28 10:00:00","end_time":"2019-08-30 23:59:59","trips":[{"city_id":"1","city":"\u5317\u4eac"},{"city_id":"4","city":"\u4e0a\u6d77"}]}&client_id=client_id_test&company_id=12345678980&out_approval_id=abc12345678&phone=11000001234&reason=测试®ulation_id=1125901881811042&sign_key=sign_key_test×tamp=1566907865
2.3 计算签名: sign = md5(str) = "1c5167f94d57b5db0e9f3cfdf4887db6"
特别注意
步骤2.1中的business_trip_detail为json字符串,且这个json字符串中的中文字进行了unicode编码; 但是步骤2.2中计算签名,可以发现reason字段的中文字并没有进行unicode编码,这是因为php在将对象进行json序列化时,会自动对中文字进行编码; 如果您使用其它编程语言开发,请注意在计算签名时,一定要对business_trip_detail字段中的中文字进行unicode编码,business_trip_detail外的其他字段如果包含中文字请不要进行任何编码
3. 请求示例
curl -X POST -H "content-type:application/json" \
-d '{"client_id":"client_id_test","access_token":"access_token_test","timestamp":"1566907865","company_id":"12345678980","phone":"11000001234","regulation_id":"1125901881811042","out_approval_id":"abc12345678","reason":"\u6d4b\u8bd5","approval_type":"3","business_trip_detail":{"start_time":"2019-08-28 10:00:00","end_time":"2019-08-30 23:59:59","trips":[{"city_id":"1","city":"\u5317\u4eac"},{"city_id":"4","city":"\u4e0a\u6d77"}]},"sign":"1c5167f94d57b5db0e9f3cfdf4887db6"}' \
https://api.es.xiaojukeji.com/river/Approval/create
特别注意
计算签名时,需要将business_trip_detail转换为json字符串,但是在发送请求时,请使用对象类型进行传参,不要传json字符串
4. 返回示例
{
"errno": 0,
"errmsg": "SUCCESS",
"data": {
"approval_id": "781948394919012"
}
}
接口错误解决方案
通用错误解决文档
- 4xx 错误
- 1xxx 错误
10003(参数错误(xxxxxx))
xxxxxx有以下几种可能:
- travel_detail格式错误
- travel_detail必须为数组
- 每一个开始日期必须小于等于结束日期
- business_trip_detail格式错误
- 开始时间、结束时间不能为空
- 开始时间必须小于等于结束时间
- 往返用车时, trip_times必须是偶数
- 当approval_type=2且business_trip_detail的is_return=1时,trip_times必须为偶数(因为这是往返行程)
50503(请求失败(xxxxxx))
xxxxxx有以下几种可能:
- 员工不在该企业中,请添加后重试
- 传参中的phone和company_id没有一一对应
- 用户未配置任何审批用车制度
- 用户身上未配置用车制度
- 用户配置了差旅或者审批制度,但是创建审批单传入的regulation_id不在该员工身上
50506(外部审批单号已被使用(对应的滴滴审批单ID为xxxxxx),请更换外部审批单号或调用审批单修改API)
- 滴滴要求每次创建审批单的out_approval_id唯一,报该错时表明你此次传参中的out_approval_id与之前创建审批单(返回的approval_id为xxxxxx)的out_approval_id是一样的