创建

优质
小牛编辑
145浏览
2023-12-01

请求地址

https://api.es.xiaojukeji.com/river/Approval/create

返回数据格式

JSON

请求类型

POST

请求参数

参数名称数据类型必选说明
member_typeintno唯一标识类型(0-手机号,1-工号,2-邮箱,默认为0)
client_idstringyes申请应用时分配的AppKey
access_tokenstringyes授权后的access token
timestampstringyes当前时间戳
company_idstringyes企业ID
phonestringyes申请人手机号。默认必传,当member_type=1或2时不用传
employee_numberstringno员工工号。当member_type=1时,必传,通过工号创建审批单(反查员工信息)
emailstringno邮箱。当member_type=2时,必传,通过邮箱创建审批单(反查员工信息)
regulation_idstringyes制度ID
out_approval_idstringno企业主内部审批单ID(滴滴存储冗余字段),非必填时该字段不传
approval_typeintyes审批单类型(1-差旅 travel、2-行前审批 business trip按次数、3-行前审批 business trip按日期)只能选择其一
typeintno费用归属的成本中心类型(1部门 2项目)
budget_center_idstringno费用归属部门/项目的id,通过成本中心查询api获取id
reasonstringno申请原因
extra_infojsonno扩展信息,自定义字段(必须为json字符串)
travel_detailobjectnoapproval_type=1必传,其余不传
business_trip_detailobjectnoapproval_type=2或approval_type=3必传,其余不传
signstringyes签名

  1. 创建审批单规则:计算签名时候,需要对travel_detail或者business_trip_detail值做 json_encode 处理成字符串格式,再参与签名
  2. 创建审批单时:若传递的城市ID为县级市,自动替换为对应的地级市,当传递的城市ID与城市名称不一致时,以城市ID为准,替换为城市ID对应的正确城市名称

travel_detail

参数名称数据类型必选说明
start_datedateyes行程开始日期,如2017-01-10
end_datedateyes行程结束日期,如2017-02-01
tripsarrayno行程路线,行程使用的制度(regulation_id)中,出差城市配置为无需填写时,trips可为空。否则必传,需按照行程顺序填写
start_city_ruleintno行程起点城市是否包含市内用车权限(0-不包含,1-包含),trips第一行视为起点城市
end_city_ruleintyes行程终点城市是否包含市内用车权限(0-不包含,1-包含),trips最后一行视为终点城市

trips

参数名称数据类型必选说明
departure_citystringyes出发地城市名称,如北京市
departure_city_idintyes出发地城市id(地级市id)
destination_citystringyes目的地城市名称,如上海市
destination_city_idintyes目的地城市id(地级市id)
start_datedateyes行程开始日期,如2017-01-10
end_datedateyes行程结束日期,如2017-01-20

  1. 为出发地城市创建【送机】和【市内用车】的用车规则。第一个行程的出发地城市无【市内用车】
  2. 为目的地城市创建【接机】和【市内用车】的用车规则。最后一个行程的目的地城市的【市内用车】依赖于end_city_rule
  3. 目前每个行程的开始日期、结束日期,依赖于travel_detail中的start_date、end_date
  4. 当所有的城市id都为空时,系统会根据城市名称匹配对应id,存在id匹配失败的情况;当城市id至少有一个非空,以传入的城市id为准,系统不会进行匹配。建议根据城市查询API传入对应的城市id
  5. 所有用车出发地城市和目的地城市参数都应传入城市级别id(当用车出发地城市和目的地城市级别为区县时,应该传入对应所属地级市城市id、区县名称)
  6. 当差旅制度中,出差城市配置为无需员工填写时,出发地、目的地城市传空

business_trip_detail(按次数)

参数名称数据类型必选说明
start_timedatetimeyes开始时间,需要大于等于接口调用当前时间。时间格式为:2015-06-16 12:00:09
end_timedatetimeyes结束时间,需大于等于开始时间。时间格式为:2015-06-16 12:00:09
departure_city_idintno出发地城市id(指定出发地时必填)
departure_citystringno出发地城市名称(指定出发地时必填)
destination_city_idintno目的地城市id(指定目的地时必填)
destination_citystringno目的地城市名称(指定目的地时必填)
start_namestringno出发地名称(最多50个字)(指定出发地时必填)
start_addressstringno出发地详细地址(最多100个字)(指定出发地时必填)
flatfloatno出发地纬度 (指定出发地时必填)
flngfloatno出发地经度 (指定出发地时必填)
end_namestringno目的地名称(最多50个字)(指定目的地时必填)
end_addressstringno目的地详细地址(最多100个字)(指定目的地时必填)
tlatfloatno目的地纬度(指定目的地时必填)
tlngfloatno目的地经度(指定目的地时必填)
is_returnintno是否往返,0-不往返,1-往返,默认为0
trip_timesintyes用车次数,当is_return为1时,用车次数必须为偶数(去程一次+回程一次
perorder_money_quotaintno每单限额,单位:分,需大于0生效

business_trip_detail(按日期)

参数名称数据类型必选说明
start_timedatetimeyes开始时间,需要大于等于接口调用当前时间。时间格式为:2018-06-16 12:00:09
end_timedatetimeyes用车结束时间,需大于等于start_time,如2018-06-19 12:00:09
tripsarrayno(创建规则时如果选择了“由员工填写”则必填)用车城市列表: [{ "city_id": "1", "city": "北京" },{ "city_id": "2", "city": "上海" }]
trip_amountintno用车金额 (不传默认不限制金额) 单位 分

差旅请求参数示例:

{   
    "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_idstring审批单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=测试&regulation_id=1125901881811042&sign_key=sign_key_test&timestamp=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"
    }

}

接口错误解决方案

通用错误解决文档

  1. 4xx 错误
  2. 1xxx 错误

10003(参数错误(xxxxxx))

xxxxxx有以下几种可能:

  1. travel_detail格式错误
    1. travel_detail必须为数组
    2. 每一个开始日期必须小于等于结束日期
  2. business_trip_detail格式错误
    1. 开始时间、结束时间不能为空
    2. 开始时间必须小于等于结束时间
  3. 往返用车时, trip_times必须是偶数
    1. 当approval_type=2且business_trip_detail的is_return=1时,trip_times必须为偶数(因为这是往返行程)

50503(请求失败(xxxxxx))

xxxxxx有以下几种可能:

  1. 员工不在该企业中,请添加后重试
    1. 传参中的phone和company_id没有一一对应
  2. 用户未配置任何审批用车制度
    1. 传参中的regulation_id必须是差旅或者审批用车(按日期、次数的商务审批)的id
    2. 通过用车制度列表接口查询企业所有用车制度(返回值scene_type=2或96的才能用于创建审批单)
    3. 从第2步返回的结果中找到创建审批单传的regulation_id那条记录,然后去查看该员工是否绑定了该审批id:登录es后台 ——> 员工 ——> (根据姓名、工号、手机号)找到这个员工 ——> 编辑 ——> 管理用车制度
  3. 用户身上未配置用车制度
    1. 用户配置了差旅或者审批制度,但是创建审批单传入的regulation_id不在该员工身上

50506(外部审批单号已被使用(对应的滴滴审批单ID为xxxxxx),请更换外部审批单号或调用审批单修改API)

  1. 滴滴要求每次创建审批单的out_approval_id唯一,报该错时表明你此次传参中的out_approval_id与之前创建审批单(返回的approval_id为xxxxxx)的out_approval_id是一样的