管理API对接文档（2024版）

最近更新时间：

接口说明

注意

  1. 计算签名时候，需要对travel_detail或者business_trip_detail值做 json_encode 处理成字符串格式，再参与签名；

  2. approval_type=1时，用过车的城市之后的城市可以修改，之前的无法修改；

  3. 修改时，凡是涉及到有日期规定的，规定的最晚时间必须大于修改时的时间。

  4. 如果有跨城用车订单，那么这些城市还支持修改吗?

    跨城用车订单，出发城市不支持修改，目的城市支持修改

  5. 差旅单制度被修改了，限额等是读取最新的吗?

    以原申请单落地时制度设置的为准，如需要使用最新的制度信息，需要重新创建申请单。

  6. 出发城市不允许修改问题

    出发城市支持修改(未生成机酒火和用车订单)

  7. start_city_rule end_city_rule 是否允许修改，如果第一段城市已有订单，不支持修改；

  8. 修改只针对正常可使用的申请单。

说明

  1. 修改申请单开始时间
    仅当申请单内行程未开始时（开始时间>当前时间，且审批单下未产生有效订单），审批单开始时间允许修改，可以修改到的时间为当天之后，审批单结束时间之前； 存在有效用车行程，开始时间不允许修改(有效用车行程: 订单状态为正常、待支付、退款、已支付、部分退款、取消行程,但是有费用需要支付)

  2. 修改申请单结束时间
    结束时间可以修改为当天及以后，即 newEndTime ≥ 当前日期 ，时间修改后，所有已用车城市的规则有效时间会被更新，未用车城市规则被删除然后重新创建; 但是不能存在出发时间大于新的结束时间的用车订单

  3. 修改差旅行程
    a. 当差旅制度-出差城市配置为“需填写城市，无需填写具体出行时间”（中度管控）或“需填写城市，需填写具体出行时间”（严格管控）时或”需要填写城市，无需填写顺序和具体出行时间“（轻度管控），未发生用车/机酒火订单时：删除旧的差旅行程信息和规则，生成新的行程和规则； 已发生用车/机酒火订单时：已预订城市行程不允许修改，未预订城市行程可以修改。比如差旅行程为：北京-上海，上海-北京。如果上海发生了预订，那么北京-上海的行程是不允许修改的，上海-北京允许修改。
    b. 当差旅制度-出差城市配置为无需员工填写时出发地、目的地城市传空

  4. 修改机票酒店火车票总次数
    修改后的次数需大于等于已用次数

  5. 修改行程起点终点城市是否包含市内用车和酒店

  6. 申请单被驳回、取消、申请单过期未审批(当前时间>出行结束时间)、申请单行程已结束(当前时间>出行结束时间) 均不支持修改

  7. 轻度管控不支持修改，原来管控类型为轻度管控修改为其他管控类型或者打算将其他类型修改为轻度管控均不支持

  8. 已经用车城市不能修改, 某一城市的城市行程顺序和用车时间都不能修改，只能修改之后的行程城市和用车时间

  9. category_control

    不支持修改，传了不生效

  10. trip_type

    支持修改

  11. 修改用车总次数
    增加总次数无校验；减少总次数时，校验已使用次数，若小于已使用次数，无法修改

  12. 修改用车总限额
    总限额需大于0，修改后的总限额需大于等于已用额度

  13. 修改每单限额
    a. 每单限额需大于0
    b. 修改后的限额需大于等于已用额度
    c. 每单限额是否生效取决于制度内配置是否启用每单限额

  14. 行前审批-按日期，产生用车订单，则不支持用车城市的修改

  15. budget_center_id，name，out_budget_id，extend_field_list四个字段与budget_center_list不可以同时使用。传空视为使用。

  16. 修改时，budget_center_id，name，out_budget_id，extend_field_list四个字段与budget_center_list可以传空，传空时为清除原值。不传字段不处理。传空为清除原值。

  17. 只使用budget_center_id，name，out_budget_id，extend_field_list，修改为最近的数据。开启甲子开关时，全量更新成本中心1到4 。后续5到9清空。

  18. 由于只能存在一种维度的成本中心，budget_center_list例如外层有值，人员维度有值时，只处理外层。budget_center_list例如外层为空或不传，人员维度有值时，处理成人维度的budget_center_list。

  19. budget_center_list全量更新，以修改时传递的信息落地。

  20. 联系客户经理或客服开通强制修改。可以去掉行程相关的修改限制。

修改逻辑：





有订单后修改行程

管控模式

修改字段

机酒火

用车

轻度管控

to_citys

任意一个城市发过单，则不支持修改
机火：出发城市、目的城市
酒： 订酒店城市

有以下订单则不支持修改
1：status:0:正常,发单到结束计费之前
2：status:2；支付完成
3：status:3；全部退款
4：status:5； 待支付
5：status:7； 部分退款

基本信息

HTTP URL

/river/Approval/update

HTTP Method

POST

权限要求


请求头

参数名称

参数值

Content-Type

application/json

请求参数

字段名

字段说明

字段类型

必填

备注

client_id

申请应用时分配的AppKey

string

Y

申请应用时分配的AppKey

access_token

授权后的access token

string

Y

授权后的access token

timestamp

当前时间戳(精确到秒级)

int

Y


company_id

滴滴公司 ID

string

Y


sign

签名

string

Y







approval_type

申批单类型

int

Y

枚举值数字：
1:差旅单
2: 行前审批-按次数
3: 行前审批-按日期






approval_id

申请单ID

string

N

滴滴申请单ID。approval_id与out_approval_id至少需要传一个。

out_approval_id

外部申请单ID

string

N

外部申请单ID approval_id优先级大于out_approval_id

reason

申请原因

string

N

申请原因，限制 200 字符；默认为空字符
eg: 北京出差，行程维度事由。使用卡片事由时，可以为空。

travel_budget

差旅预算总额

string

N

差旅预算控制，一个申请单对应一个总预算纬度，一次只能全部或者选择部分品类。字段不传输，修改不处理，字段传输，空对象时处理为清空。给值为修改。

travel_management

差旅管控

string

N

差旅管控，目前仅支持市内用车每日限额设置（为json字符串类型，具体看请求示例）

extra_info

扩展信息

string

N

扩展信息，自定义字段；最长不大于 500 字符；(必须为json字符串)；默认为空字符

travel_detail

差旅单行程信息

string

N

差旅单行程信息
将travel_detail的值转为 json 字符串
approval_type = 1 时必传。

business_trip_detail

因公用车审批行程数据

string

N

行前行程信息, 将 business_trip_detail转为 json 字符串
approval_type = 2 或 approval_type = 3 必填。详见 [business_trip_detail](#business_trip_detail （按次数）

passenger_list

出行人信息

string

N

出行人信息，不传时默认出行人为申请人，
将passenger_list 转为 json 数组字符串。详见passenger_list

budget_center_list

多成本中心

string

N


extend_field_list

扩展信息list

string

N

自定义字段，最长不大于 500 字符
将extend_field_list转为 json 字符串
三个字段仅作为备注性字段。详见extend_field_list

budget_center_id

滴滴侧成本中心ID

string

N

滴滴侧成本中心ID；
获取方式接口返回的 ID（可为项目/部门ID)
eg : 1125920020961744 关联部门 时， id和out_budget_id 优先处理id关联项目时 id和 out_budget_id与 name 组合唯一值时 优先处理id ，out_budget_id与 name 同时有值时按照项目处理，out_budget_id有值且name为空时，按照部门处理。

name

部门/项目名称

string

N

不大于 200 字符

out_budget_id

编号

string

N

长度限制：≤ 64 字符


travel_budget

字段

类型

是否必传

说明

budget_amount

int

Y

申请单总预算金额 单位 分 修改时，修改的金额需要大于已使用的额度。已使用的额度可以通过申请单查询接口获取

budget_type

int

Y

预算类型
1 申请单维度

budget_share

array

Y

需要申请单使用的制度内开启对应的品类。且最终取两者交集。
预算可使用品类
1 市内用车
2 接送场景
301 国内酒店
401 火车票
601 国内机票
701 国际机票
801 国际酒店


travel_management

字段

类型

是否必传

说明

daily_amount_control

array

Y

每日金额管控内容


daily_amount_control

字段

类型

是否必传

说明

daily_amount

int

Y

每人日金额管控

control_type

int

N

管控方式1 日清

control_product

array

Y

1 市内用车

budget_center_list

字段

类型

是否必传

说明

sequence

int

Y

字段序号 支持从1到9

id

string

N

sequence为1时，生效

value

string

N

对应成本中心的值。sequence为1时与name字段一致，sequence为2时，对应extend_field_01，sequence为3时，对应extend_field_02，sequence为4时，对应extend_field_03

code

string

N

对应成本中心的编码。sequence为1时与out_budget_id字段一致 sequence为2到9时，CODE无效。


extend_field_list

字段

类型

是否必传

说明

extend_field_01

string

N

扩展信息一

extend_field_02

string

N

扩展信息二

extend_field_03

string

N

扩展信息三


passenger_list

字段名

字段说明

字段类型

必填

备注

passenger_type

出行人类型

int

Y

枚举值数字：
0：员工；1：外部出行人

budget_center_list

多成本中心

list

N


passenger_name

出行人姓名

string

Y

出行人姓名/员工姓名

member_type


int

N

出行人类型
0：手机号，passenger_phone
1：工号；employee_number 必填
2：邮箱：email 必填
默认为0
以 member_type 对应的值为准，其他字段传了不生效

passenger_phone

员工手机号

string

N

使用海外手机号时输入格式为 +90 137****0001 ，国内可以不加区号

employee_number

员工工号

string

N


email

员工邮箱

string

N







member_type

出行人 key 标识

int

N

枚举值数字：
0：手机号，passenger_phone
3:：外部出行人ID，traveler_id
以 member_type 对应的值为准，其他字段传了不生效
在passenger_type为1时，member_type可以不传，手机号也可以不传递

passenger_phone

出行人手机号

string

N


traveler_id

外部出行人 ID

string

N



travel_detail

字段名

字段说明

字段类型

必填

备注

start_date

行程开始时间

date

Y

格式： YYYY-MM-DD

end_date

行程结束时间

date

Y

格式： YYYY-MM-DD

trips

行程信息

list<trip>

N

行程信息；行程使用的制度(regulation_id)中，出差城市配置为无需填写时，trips可为空。否则必传，需按照行程顺序填写 详见 trip

start_city_rule

行程起点城市是否包含市内用车权限和酒店

int

N

（0-不包含，1-包含），trips第一行视为起点城市；默认为无市内用车和酒店，不管控和轻度管控不生效
不影响接送机服务

end_city_rule

行程终点城市是否包含市内用车权限和酒店

int

N

（0-不包含，1-包含），trips最后一行视为终点城市，不管控和轻度管控不生效
不影响接送机服务

train_total_count

火车票次数

int

N

火车票次数；火车票次数 ，修改时需要大于已使用次数，且不可传0置为不限制

flight_total_count

机票次数

int

N

机票次数，修改时需要大于已使用次数，且不可传0置为不限制

hotel_total_count

酒店总间夜

int

N

酒店总间夜，修改时需要大于已使用次数，且不可传0置为不限制

pickup_total_count

接送机总次数

int

N

接送机总次数，修改时需要大于已使用次数，且不可传0置为不限制

category_control

品类控制开关

[]int

N

品类控制开关；制度有权限时,控制申请单是否创建品类对应服务
3-市内用车；4-火车票服务；6-机票服务；9-接送服务；10-酒店服务
如果传了机火两个品类。制度上只开了机票品牌。则创建申请单成功，只能使用机票服务
category_control 传空数组会报错 举例：[4,10]，强制修改时，不校验。非强制时，使用的品类不允许修改只能新增。


trips

字段名

字段说明

字段类型

必填

备注

departure_city

出发城市名称

string

N

出发城市名称

departure_city_id

滴滴出发城市ID

int

N

出发城市 ID

destination_city

到达城市名称

string

N

到达城市名称

destination_city_id

滴滴到达城市ID

int

N

到达城市 ID

start_date

行程段开始时间

date

Y

行程段开始时间
轻度管控模式下，必须与 travel_detail 中的 start_date 相同 举例：2023-01-02

end_date

行程段结束时间

date

Y

行程段结束时间
轻度管控模式下，必须与 travel_detail 中的 end_date 相同 举例：2023-01-14

trip_type

出行方式

string

N

出行方式：0-其他；1-火车 ;2-飞机；支持多个，多个用英文逗号分开（用车酒店默认根据制度配置生效）举例：0,1,2

to_citys

目的城市集合

[]object

N

目的城市集合
轻度管控必传，其他模式传了不生效 举例：[{"id":1,"name":"北京"}]

is_return

单程/往返

int

N

控制严格管控模式下，滴滴侧是否识别这个trip为往返行程生成返程行程权限
非必传字段，0-单程， 1-往返；默认为单程；
传1后的拆分逻辑为：去程使用trip的传参生成，返程生成规则为：目的地-出发地，end_date-end_date，使用去程的trip_type；
若对去程和返程的交通方式有分别管控诉求，不推荐使用此字段，建议拆成两个trip传输


business_trip_detail（按日期）

参数

类型

是否必填

示例

备注

start_time

datetime

Y

2018-06-16 12:00:09

开始时间，需要大于等于接口调用当前时间

end_time

datetime

Y

2018-06-19 12:00:09

用车结束时间，需大于等于start_time，

trips

[]object

N

[{ "city_id": "1", "city": "北京" },{ "city_id": "2", "city": "上海" }]

用车城市列表：(创建规则时如果选择了“由员工填写”则必填)
制度配置为无需填写城市时，传了城市列表也不生效

trip_amount

int

N

100

用车金额 （不传默认不限制金额） 单位 分,大于100生效； 小于 100 为不限
创建时传了。修改的时候此字段不能为空

trip_times

int

N

2

用车次数，非必传只在制度配置为【由员工填写时】生效不传、传空报错，建议传大于0的整数；
修改时，传过来的值需要大于等于已用次数


请求示例

差旅

curl --location 'https://api.es.xiaojukeji.com/river/Approval/update' \
--header 'Content-Type: application/json' \
--data '{
    "access_token":"b6da7c1e90a53f9bd7442534f94e83a8193fc653",
    "reason":"出差测试",
    "travel_detail":"{\"end_date\":\"2023-12-19\",\"start_city_rule\":1,\"end_city_rule\":1,\"trips\":[{\"end_date\":\"2023-08-21\",\"trip_type\":\"1,2\",\"departure_city_id\":\"1\",\"departure_city\":\"Beijing\",\"destination_city\":\"Tianjin\",\"destination_city_id\":\"7\",\"start_date\":\"2023-03-20\"},{\"end_date\":\"2023-08-23\",\"trip_type\":\"1,2\",\"departure_city_id\":\"7\",\"departure_city\":\"Tianjin\",\"destination_city\":\"Hangzhou\",\"destination_city_id\":\"5\",\"start_date\":\"2023-08-21\"}],\"flight_total_count\":1,\"hotel_total_count\":1,\"train_total_count\":1,\"start_date\":\"2023-05-10\",\"category_control\":[4,10]}",
    "company_id":"1125915646167936",
    "phone":"11100011964",
    "approval_type":1,
    "sign":"f3274df0cd86237ebe4ea04fef3a8d1a",
    "client_id":"87fca1dc60c9de0a96c20fccf2ccaa40_test",
    "timestamp":1692082071610
}'

因公用车按日期

curl --location 'https://api.es.xiaojukeji.com/river/Approval/update' \
--header 'Content-Type: application/json' \
--data '{
    "access_token":"71b27640f77bd0f23ba4c302a7b52303b97540c4",
    "reason":"单管额度001",
    "regulation_id":"1125919219487303",
    "company_id":"1125915646167936",
    "phone":"11000009675",
    "approval_type":3,
    "business_trip_detail":"{\"start_time\":\"2023-07-25 10:00:00\",\"trips\":[{\"city\":\"bj\",\"city_id\":\"1\"},{\"city\":\"sh\",\"city_id\":\"2\"}],\"end_time\":\"2023-08-25 18:00:00\"}",
    "sign":"b2afd904a16fb14a3271d25e7200bf50",
    "client_id":"87fca1dc60c9de0a96c20fccf2ccaa40_test",
    "sign_key":"f86b6735313052FD7d0f",
    "approval_id":"1125923187185115",
    "timestamp":1692088117604
}'



响应参数

字段

类型

描述

errno

int

错误码。 0 表示成功

errmsg

string

错误信息描述

响应示例

正常示例

{
    "errno": 0,
    "errmsg": "SUCCESS",
    "data": null,
    "request_id": "b7tL/EnaLhovjUpQp99jQiEeNYcm/nZZmzsmeq1L1ZG3n8tzaVkJb9dBbmqejQaE"
}


错误码

通用错误解决方案

版本记录

日期

更新人

更新内容

上线时间

2023.10.30

陈继诗

增加字段：out_trip_id，out_trip_info

2024.01.10

2024.01.04

陈继诗

删除成本中心ID

2024.01.04

2024.01.18

陈继诗

增加 out_approval_id使用


2024.04.23

陈继诗

外部人员支持无手机号传输


2024.08.28

陈继诗

新增加budget_center_id，name，out_budget_id，extend_field_list四个字段与budget_center_list修改逻辑，category_control支持修改，规则受限于开关。


2024.09.20

陈继诗

新增travel_budget,差旅市内用车和接送场景

2024.09.24

2024.09.27

陈继诗

travel_budget,支持机酒火


2024.10.16

陈继诗

支持 out_approval_id字段

2024.10.17

2024.12.10

陈继诗

修改按照日期内的tripamount字段

2024.12.10

2024.12.27

高洋洋

增加差旅管控字段：travel_management

2024.01.02