管理API对接文档

最近更新时间：

接口说明

说明
  • 修改部门或项目后，可通过【部门或项目查询】接口核验在滴滴企业版管理后台的实际写入及生效状态。
  • 接口暂不支持并发操作。
  • 以下功能需联系滴滴侧对接同学配置白名单后生效：① member_used=2（部分公司主体+部门可见）；② budget_cycle=2（自然季度）、3（自然年）（仅部门生效）。
注意
  • 非必填字段不传则不做任何处理，保持原有值不变；
  • 字段传空字符串视为清空该字段（例如，parent_id 字段传 0 为清空上级关联）；
  • 修改时传值为覆盖逻辑，传入的字段值将直接覆盖原有值。

基本信息

HTTP URL

/river/BudgetCenter/edit

HTTP Method

POST

权限要求


请求头

参数名称

参数值

Content-Type

application/json

请求参数

字段名

字段说明

字段类型

必填

备注

client_id

应用唯一标识

string

Y

滴滴开放平台创建应用时，由平台分配的唯一标识，用于识别调用方身份

access_token

接口调用授权凭证

string

Y

授权认证后获取的访问令牌，用于校验接口调用权限；授权认证方式参见【接口认证-授权认证】

company_id

租户唯一标识

string

Y

滴滴企业版租户唯一 ID，代表当前操作的企业主体

timestamp

当前时间戳

int

Y

当前时间戳，精确到秒级

sign

签名

string

Y

根据规则生成的接口签名，用于校验请求合法性与完整性；生成方式参见【接口认证-授权认证】

id

滴滴侧部门/项目ID

string

N

部门修改时，id或out_budget_id，至少需传入其中一组参数，作为唯一标识进行匹配
项目修改时，id或out_budget_id+name至少需传入其中一组参数，作为唯一标识进行匹配
id的优先级最高

type

类型

int

N

枚举值数字：
1：部门
2：项目

注意：如果使用out_budget_id（外部编号）、name（项目/部门名称）作为更新标识，而非使用滴滴侧ID时，type字段必传

name

部门/项目名称

string

N

长度限制：≤ 200 字符

out_budget_id

部门/项目外部编号

string

N

合作方侧自定义的唯一标识，同一租户下不可重复
type = 1 （部门）时必填，type = 2（项目）非必填
长度限制：≤ 64 字符

parent_id

上级部门/项目滴滴侧ID

string

N

字段用途：
用于关联部门 / 项目层级关系，该字段需匹配滴滴侧部门 / 项目 ID，仅支持传入已在滴滴侧创建的部门 / 项目主体 ID

传值规则：
1. type=1（部门）：parent_id 非必填，传入 0 则代表根部门。关联层级关系时，parent_id（滴滴侧ID）与out_parent_id（外部编码）至少需传入其中一个参数
2.type=2（项目）：parent_id 不传默认为空，关联层级关系时，parent_id（滴滴侧ID）或out_parent_id（外部编码）+out_parent_name（外部名称），至少需传入其中一组参数
3.如需保留原有上级关系则不传该字段

out_parent_id

上级部门/项目外部编码

string

N


out_parent_name

上级部门/项目外部名称

string

N


leader_id

主管ID

string

N

部门主管或项目主管
需要传入滴滴侧员工ID，如果有多个，以英文逗号分开
第一个为主负责人，后续为其他负责人

个数限制：最多30个

leader_id（主管ID）和leader_employee_id（主管员工编号）选择一组参数传值即可，同时传值时，以leader_id为准

leader_employee_id

主管员工编号

string

N

部门主管或项目主管工号
需要与滴滴侧管理后台维护的员工工号一致
如果有多个，以英文逗号分开
第一个为主负责人，后续为其他负责人

格式要求：json字符串，例如，[\"0012\",\"1234\"]

个数限制：最多30个

部门/项目限额





budget_cycle

限额预算周期

int

N

枚举值数字：
0：不限额
1：自然月
2：自然季度
3：自然年
4：一次性

注意：枚举值2（自然季度）、3（自然年）只对部门生效，需要设置白名单，需联系滴滴侧对接同学设置。

如果默认规则已经不是【使用原部门的周期】，新增、修改部门只有限额生效，周期不生效。

total_quota

限额金额

string

N

与限额预算周期组合使用，传限额预算周期后，该字段必传
单位元，存在限额时，需为大于 0 的正整数
传0代表不限制

项目的数据权限





member_used

项目的可见范围

int

N

仅type=2（项目）时生效
枚举值数字：
0 ：全员可见
1：项目成员可见
2：部分公司主体+部门可见
不传该字段，默认设置为全员可见

注意：枚举值2需要设置白名单，需联系滴滴侧对接同学设置。如果未设置白名单，错误码为10001。

legal_entity_id

项目所属公司主体ID

string

N

仅member_used=2时生效
如果有多个，以英文逗号分开
如果选择公司主体可见时，不传该字段，则不会生效

注意：仅支持关联有效的公司，如果对应的公司主体id已经停用或者不存在，返回错误码10001。

department_id

项目所属滴滴侧部门 ID

string

N

仅member_used=2时生效
滴滴侧部门 ID，多个部门用英文逗号分隔，最多300个
字段不传代表不修改；传新值，进行覆盖；传空代表清空。

out_department_id

项目所属部门编码

string

N

仅member_used=2时生效
多个部门用英文逗号分隔，最多300个
字段不传代表不修改；传新值，进行覆盖；传空代表清空。

scope

项目所属部门范围

string

N

仅member_used=2时生效
枚举值英文：
current_only：仅当前部门（默认值）
include_sub：含下级部门
举例：如果out_department_id=001，cope=include_sub，则001所有下级部门的员工都能使用此项目

项目的其他信息





start_date

项目开始日期

string

N

当类型为项目时，此参数有效
格式：yyyy-MM-dd

expiry_date

项目结束日期

string

N

当类型为项目时，此参数有效
格式：yyyy-MM-dd
项目开始日期不能晚于结束日期
不传则默认为空，代表项目无时间限制

budget_extra_info

项目扩展信息的自定义字段

string

N

项目扩展信息的自定义字段
长度限制：≤ 500 字符
格式要求：必须为json字符串，json解析后不能为空
注意：仅后台存储，不在前端页面展示

extend_field

扩展字段

string

N

仅 type=2（项目）时有效，JSON 数组，结构见下表

poi_list

POI 地点列表

string

N

仅 type=2（项目）时有效，最多 20 个，结构见下表

out_travelers

外部出行人列表

array

N

仅 type=2（项目）时有效，最多 200 人
注意：
（1）需联系滴滴侧对接人，配置好【项目支持维护外部出行人】开关；
（2）需要先使用【外部出行人新增】接口创建外部出行人后进行关联

operate_type

外部出行人修改操作类型

string

N

枚举值：cover：覆盖式操作append：追加式操作remove：移除式操作单次操作最多支持传200个外部出行人
覆盖式操作：不传 / 空 / cover为覆盖式操作，以本次传入的 out_travelers 完全覆盖历史数据追加式操作：传append代表追加操作，向现有列表新增外部出行人，或新增外部出行人与员工的关联关系。移除式操作：传remove代表移除操作，从现有列表删除指定的外部出行人。

extend_field 扩展字段

字段

类型

必填

说明

code

string

Y

扩展字段编码

value

string

Y

扩展字段值

poi_list POI地点列表

字段

类型

必填

说明

flat

float

Y

纬度，范围 -90 ~ 90

flng

float

Y

经度，范围 -180 ~ 180

poi_range

int

Y

POI 范围（米），100 ~ 5000

label

string

N

POI 标签名称

out_travelers 外部出行人列表

字段

类型

必填

说明

out_traveler_id

string

N（有条件必填）

外部出行人编码
与 id 至少填一个

id

int

N（有条件必填）

外部出行人滴滴侧ID
与 out_traveler_id 至少填一个

related_employees

array

N

关联员工列表，最多 20 个

·related_employee_id

string

N

关联员工滴滴侧ID

·employee_number

string

N

员工工号

·phone

string

N

员工手机号

·email

string

N

员工邮箱
说明

如果采用集团账户方案，并且配置了由【上级公司统一对接】（具体配置请咨询滴滴侧对接人），请求参数有如下变化：

新增参数：

字段名

字段名称

类型

是否必填

备注

belong_enterprise_name

归属企业名称

string

N

company_id传集团公司ID时，可通过该字段确定处理哪个子公司的数据
company_id传子公司ID时，该字段可以不传
该字段与taxpayer_no、out_legal_entity_id任选一个传值
该字段需要与企业开户时认证名称一致

taxpayer_no

纳税人识别号

string

N

company_id传集团公司ID时，可通过该字段确定处理哪个子公司的数据
company_id传子公司ID时，该字段可以不传
该字段与belong_enterprise_name、out_legal_entity_id任选一个传值
需要与集团公司的公司档案里的纳税人识别号一致

out_legal_entity_id

公司主体编码

boolean

N

对于部门上已经传了【所属公司】的客户，可以通过该字段所携带的信息，确定处理哪个租户的数据**
**需要与集团公司的公司档案里的公司主体编码一致

请求示例

curl -X POST -H "content-type:application/json" \
-d '{
    "client_id":"client_id_test",
    "access_token":"1e79178d3bfeb40be24404a3048f541f34dd6268",
    "timestamp":1583484681,
    "company_id":"12345678980",
    "id":"1001",
    "name":"更新",
    "extend_field":"[{\"code\":\"custom_field_01\",\"value\":\"新扩展值\"}]",
    "poi_list":"[{\"flat\":39.908823,\"flng\":116.397470,\"poi_range\":800,\"label\":\"北京总部新址\"}]",
    "out_travelers":"[{\"out_traveler_id\":\"ext_003\",\"related_employees\":[{\"employee_number\":\"EMP003\"}]}]",
    "operate_type":"append",
    "sign":"b517f48fcbe57a2d66dcefd560452da1"
}' \
https://api.es.xiaojukeji.com/river/BudgetCenter/edit

响应参数

字段名

字段说明

字段类型

备注

errno

错误编码

string

数字 0 表示成功，非 0 表示失败

errmsg

错误信息

string

errno=0时为常量"SUCCESS"，errno!=0时为错误信息

data

返回数据

object

null
本接口为修改操作，成功后无额外数据返回，data 字段固定为 null


响应示例

{
	"errno":0,
	"errmsg":"success",
	"data":null
}


错误码

注意

错误码对应的文案描述仅为场景化说明，会根据业务优化、场景补充、表述规范等需求进行不定期更新（如细化提示、优化措辞等），不建议将文案内容用于精准匹配逻辑，避免后续文案变更影响系统稳定性

错误码

错误码文案

错误原因以及处理方案

10001

member_used 相关错误

原因：调用接口时 member_used （项目可见范围）字段未配置白名单，无访问权限；
处理：联系滴滴侧对接人，配置 member_used 相关白名单后重新发起请求

10001

timestamp 过期

原因：请求携带的时间戳超出有效时效，接口拒绝处理
处理：生成当前最新的 timestamp重新发起请求，确保时间戳与服务器时间误差在有效范围内

10002

IP 不在白名单中，本次请求 IP：

原因：发起请求的服务器 IP 未配置在滴滴接口白名单内，接口做了 IP 访问限制
处理：在开放平台管理后台，将本次请求的实际 IP 添加至接口白名单后再请求

10003

type 必填

原因：使用外部编码更新部门 / 项目时，未传入 type 参数，存在必填项缺失
处理：按接口文档规范补充传入 type 参数

10003

type 只能为 1 或 2

原因：传入的 type 参数值无效，超出接口规定的 1、2 取值范围
处理：将 type 参数值修正为 1 或 2

10003

out_budget_id 和 third_out_id 不能都为空

原因：部门的外部编码为必填项
处理：补充传入部门的out_budget_id

10003

名称不能设置为空

原因：修改时 name 参数传入了空字符串，不符合接口参数规范
处理：为 name 参数传入非空的有效名称后重新发起请求

10003

id 和 third_out_id 不能都为空

原因：修改操作中未传入滴滴侧ID，缺少定位待修改数据的标识
处理：补充传入滴滴侧ID，或者用外部编码+名称的组合来定位待修改数据

10003

参数错误

原因：请求传入的参数存在格式、值类型、必填项缺失等错误
处理：核对接口文档的参数规范，检查所有传参的格式、类型、非空要求，修正后重新请求

12001

参数错误 (未正确传输 company_id)

原因：核心参数 company_id 未传、传空或格式不符合接口要求
处理：确认 company_id 值的正确性，按文档规范正确传值后重新请求

19998

系统异常网络异常 / 系统异常 (未获取到请求参数)

原因：滴滴侧系统内部未成功解析并获取到修改请求的参数，属于系统异常
处理：先检查请求参数的传输格式是否正确，如果无误则稍作等待后重试，仍失败联系滴滴侧对接人排查

19999

签名失败

原因：请求的 sign 签名值生成规则错误、参数拼接错误或密钥不一致，签名校验未通过
处理：严格按照接口文档的签名生成规则重新计算 sign，核对密钥、参数拼接顺序是否正确

36003

访问频次太快，请稍后

原因：短时间内发起的修改接口请求次数超出接口限流阈值，被系统限制访问
处理：降低请求频次，等待一段时间后再重新发起修改请求

400

非法的 client_id

原因：传入的 client_id 无效、未注册或与接口分配的 client_id 不匹配
处理：核对开放平台管理后台的有效 client_id，替换为正确值后重新请求

410

client_id 不一致

原因：请求中携带的 client_id 与签名、access_token 关联的 client_id 不匹配
处理：确保请求的 client_id、签名生成、access_token 使用的是同一个有效 client_id

412

client_id 和 access_token 为必填项

原因：请求未传入 client_id 或 access_token，两个均为接口必填参数
处理：补充传入有效且匹配的 client_id 和 access_token后重新请求

415

不支持 http 协议

原因：使用了 HTTP 协议发起请求，接口仅支持 HTTPS 安全协议
处理：将请求协议替换为HTTPS，确保请求地址以 https:// 开头

50102

要更新的成本中心不存在

原因：修改请求中id或out_budget_id在滴滴侧系统无匹配数据
处理：核对并修正部门/项目的唯一标识

50102

网络请求结果错误（更新成本中心失败 (公司内部不存在项目主管) 10001）

原因：修改时传入的项目主管信息在公司内部无匹配数据
处理：核对并修正项目主管相关参数，传入公司内部有效主管信息

50102

网络请求结果错误（更新成本中心失败 (禁止选择本部门，或下级部门充当上级部门) 10001）

原因：选择了本部门 / 下级部门作为上级部门，违反层级规则
处理：调整上级部门为合规的上级层级部门

50102

网络请求结果错误（更新成本中心失败 (该部门禁止编辑) 10001）

原因：根部门禁止编辑
处理：请勿处理根部门的编辑

50222

该公司下，员工不存在

原因：修改时传入的主管员工相关信息在滴滴侧系统无匹配数据
处理：核对并修正主管员工相关参数，传入系统内有效员工信息后重新发起请求

50253

员工不存在

原因：修改时传入的主管员工相关信息在滴滴侧系统无匹配数据
处理：核对并修正主管员工相关参数，传入系统内有效员工信息后重新发起请求

50401

参数相关错误

原因：请求传入的参数存在格式、值类型、必填项缺失等错误
处理：核对接口文档的参数规范，检查所有传参的格式、类型、非空要求，修正后重新请求

50401

未指定要更新的数据

原因：修改请求中未传入定位待更新数据的标识参数，无法识别目标数据
处理：补充传入id或out_budget_id等有效标识参数，指定待更新数据后重新请求

50402

成本中心不存在

原因：修改部门 / 项目时关联的成本中心在滴滴侧系统无匹配数据
处理：核对并修正成本中心相关参数，传入系统内有效成本中心信息后重新请求

50403

budget_extra_info 必须是 json 格式，json 解析后不为空，长度小于等于 500

原因：传入的 budget_extra_info 扩展字段格式错误
处理：将该字段调整为合法 JSON 格式，确保解析后非空且字符长度≤500 后重新发起修改请求

50404

POI 信息: xxx

原因：传入的 POI 地址 信息校验不通过、不存在或格式异常
处理：核对 POI 参数内容

50405

扩展字段: xxxx

原因：请求携带的扩展字段格式非法、字段值不符合规范
处理：按照接口文档规范调整字段格式与取值后重试

50408

单次操作最多支持 200 个外部出行人

原因：单次操作传入外部出行人总数超过 200 人上限
处理：单次传入外部出行人数量控制在 200 人以内

50409

外部出行人参数错误: % s

原因：外部出行人单个字段参数格式、取值不符合接口规范
处理：根据提示字段校验出行人信息，修正错误参数后重新提交

50410

外部出行人参数错误: % s

原因：外部出行人多字段组合校验失败、必填项缺失
处理：补齐缺失必填参数，修正字段间关联逻辑

50411

移除的外部出行人不存在: %s

原因：执行移除操作时，目标外部出行人编码/滴滴ID在租户下无匹配数据
处理：核对待移除出行人标识，确认出行人已存在后再发起移除请求

50413

更新外部出行人失败: %s

原因：更新外部出行人时触发数据唯一性冲突、存储异常或业务校验拦截
处理：核查更新参数唯一性、关联员工绑定关系，修正冲突数据后重试更新

50412

添加外部出行人失败: % s

原因：新增外部出行人时系统存储异常、数据冲突或关联校验拦截
处理：排查参数唯一性、关联员工信息，修正冲突数据后重新添加

50414

解绑外部出行人失败: %s

原因：解绑操作存在关联数据依赖、出行人不存在或权限/数据校验拦截
处理：确认出行人与关联员工绑定关系有效，清理依赖数据后重新执行解绑

50415

当前类型不支持传入外部出行人信息

原因：非项目不允许携带外部出行人参数
处理：检查调用类型是否正确

50416

外部出行人信息不能为空数组

原因：外部出行人请求传了空数组
处理：补充有效的外部出行人数据，不可传空数组

50417

外部出行人数量超出最大限制（最多支持 200 人）

原因：外部出行人总条数超过系统 200 人上限
处理：出行人数量不大于 200

50418

外部出行人编码和滴滴侧 ID 不能同时为空

原因：定位外部出行人的核心标识字段缺失，无法匹配出行人
处理：至少传入外部出行人编码或滴滴侧 ID 其中一个参数

50419

外部出行人不存在，请检查后重试

原因：传入的出行人编码 / 滴滴 ID 在企业租户下未查询到对应数据
处理：确认已完成新增外部出行人后再执行操作

50420

关联员工信息不匹配，请检查后重试

原因：外部出行人绑定的员工工号 / 手机号 / 邮箱与滴滴侧员工数据不一致
处理：核对关联员工身份信息，同步企业员工数据后重新绑定出行人

50421

关联员工数量超出最大限制（最多支持 20 人）

原因：单次操作绑定的关联员工总数超过 20 人上限
处理：拆分绑定请求，单次关联员工控制在 20 人以内，分多次调用

50422

通过工号查询员工失败

原因：传入工号不存在、企业未同步该员工或工号格式错误
处理：校验工号格式，同步企业员工至滴滴平台，传入有效工号重试

50423

通过手机号查询员工失败

原因：手机号未录入企业员工库、格式有误或未完成数据同步
处理：修正手机号格式，同步员工手机号信息后重新查询

50424

通过邮箱查询员工失败

原因：员工邮箱为空、格式非法或平台无该邮箱对应的员工数据
处理：规范邮箱格式，完善企业员工邮箱信息后再次查询

其他参见：通用错误解决方案


使用建议

  1. 修改接口的处理逻辑

    1. 非必填字段不传，保持原有值不变
    2. 字段传空字符串 / 指定值（如 parent_id=0），视为清空对应字段 / 关联关系
    3. 传值为覆盖逻辑，传入字段值直接替换原有值

  2. 待修改的数据如何匹配：

    1. 优先级最高：直接传滴滴侧id，无需传type
    2. 部门修改：无id时，传out_budget_id（外部编号）+type=1
    3. 项目修改：无id时，传out_budget_id+name或其中一个 +type=2

  3. 白名单开通：

    1. 部门 / 项目数量超 2000 上限，需联系滴滴侧对接人进行白名单开通
    2. 部门限额预算周期设为自然季度（2）/ 自然年（3），需联系滴滴侧对接人进行白名单开通
    3. 项目可见范围设为部分公司主体+部门可见（member_used=2），需联系滴滴侧对接人进行白名单开通
    4. 发起请求的服务器 IP，需在开放平台添加至接口白名单

  4. 编号唯一性：外部编号为合作方侧自定义的唯一标识，同一租户下不可重复

  5. 层级关系：

    1. 关联上级需为滴滴侧已创建的部门 / 项目，未创建则无法关联
    2. 二选一传值：优先传滴滴侧上级 ID（parent_id）；次优传上级外部编码（out_parent_id），项目需额外传上级外部名称（out_parent_name）

  6. 主管配置：

    1. 主管信息需关联滴滴侧已创建的有效员工，无匹配数据会添加失败
    2. 二选一传值：优先传滴滴侧员工 ID（leader_id）；或传员工工号（leader_employee_id），工号需与滴滴后台一致
    3. 支持传多个主管（最多 30 个），第一个为主负责人


版本记录

日期

更新内容

上线时间

2023.11.07

迁移文档


2023.11.10

请求增加leader_employee_id字段，增加out_parent_id字段，out_parent_name

2024.01.04

2023.12.08

请求增加budget_extra_info

2024.01.04

2024.07.23

leader_id，leader_employee_id支持传多个

2024.08.22

2026.02.09

限额相关升级

2026.02.09

2026.04.07

更新文档字段描述


2026.06.23

新增拓展字段、POI列表、外部出行人信息


2026.06.30

新增项目关联部门的能力

2026.06.29