滴滴企业版

接口说明

注意

部门、项目数量上限是2000，如贵司需要扩展上限，请联系相应的对接同学添加白名单进行扩展
新增时，请不要并发操作，防止部门或项目添加失败
以下功能需联系滴滴侧对接同学配置白名单后生效：① member_used=2（公司主体可见）；② budget_cycle=2（自然季度）、3（自然年）（仅部门生效）。

说明

新增部门或项目后，可通过【部门或项目查询】接口核验在滴滴企业版管理后台的实际写入及生效状态。
建议在新增部门或项目成功后，留存滴滴平台返回的 ID 作为唯一主键，后续修改、删除操作均通过该 ID 进行匹配判断。

基本信息

HTTP URL	/river/BudgetCenter/add
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	根据规则生成的接口签名，用于校验请求合法性与完整性；生成方式参见【接口认证-授权认证】
type	类型	int	Y	枚举值数字： 1：部门 2：项目
name	部门/项目名称	string	Y	长度限制：≤ 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. parent_id优先级大于 out_parent_id+ out_parent_name
out_parent_id	上级部门/项目外部编码	string	N
out_parent_name	上级部门/项目外部名称	string	N
member_used	项目的可见范围	int	N	仅type=2（项目）时生效枚举值数字： 0 ：全员可见 1：项目成员可见 2：公司主体可见不传该字段，默认设置为全员可见注意：枚举值2需要设置白名单，需联系滴滴侧对接同学设置。如果未设置白名单，错误码为10001。
legal_entity_id	项目所属公司主体ID	string	N	仅member_used=2（公司主体可见）时生效如果有多个，以英文逗号分开如果选择公司主体可见时，不传该字段，则不会生效注意：仅支持关联有效的公司，如果对应的公司主体id已经停用或者不存在，返回错误码10001。
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	Y	与限额预算周期组合使用单位元，存在限额时，需为大于 0 的正整数传0代表不限制
start_date	项目开始日期	string	N	当类型为项目时，此参数有效格式：yyyy-MM-dd
expiry_date	项目结束日期	string	N	当类型为项目时，此参数有效格式：yyyy-MM-dd 项目开始日期不能晚于结束日期不传则默认为空，代表项目无时间限制
budget_extra_info	项目扩展信息的自定义字段	string	N	项目扩展信息的自定义字段长度限制：≤ 500 字符格式要求：必须为json字符串，json解析后不能为空注意：仅后台存储，不在前端页面展示

请求示例

curl -X POST -H "content-type:application/json" \
-d '{
    "client_id":"client_id_test",
    "access_token":"1e79178d3bfeb40be24404a3048f541f34dd6268",
    "timestamp":1583484681,
    "company_id":"12345678980",
    "name":"\u56fd\u5e86\u884c\u52a8",
    "type":2,
    "budget_cycle":1,
    "total_quota":0,
    "budget_extra_info": "{\"test\":\"test1\"}",
    "sign":"b517f48fcbe57a2d66dcefd560452da1"
}' \
https://api.es.xiaojukeji.com/river/BudgetCenter/add

响应参数

字段名	字段说明	字段类型	备注
errno	错误编码	string	数字 0 表示成功，非 0 表示失败
errmsg	错误信息	string	errno=0时为常量"SUCCESS"，errno!=0时为错误信息
data	返回数据	object	成功时包含新增的部门/项目ID
request_id	接口调用唯一标识	string	用于问题排查、日志追踪，每次调用返回唯一值

data数据格式

字段名	字段说明	字段类型	备注
id	部门/项目滴滴侧ID	string

响应示例

{
    "errno":0,
    "errmsg":"success",
    "data":{
        "id":"6415496924215922706"
    }
}

错误码

注意

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

错误码	错误码文案	错误原因以及处理方案
10001	member_used 相关错误	原因：调用接口时 member_used （项目可见范围）字段未配置白名单，无访问权限；处理：联系滴滴侧对接人，配置 member_used 相关白名单后重新发起请求
10001	非法的 client_id	原因：传入的 client_id 无效、未注册或与接口分配的 client_id 不匹配处理：核对开放平台管理后台的有效 client_id，替换为正确值后重新请求
10002	无权访问该接口	原因：当前 client_id 未获取该接口的访问权限，接口做了权限管控处理：联系滴滴侧对接人，为该 client_id 开通当前接口的访问权限
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	client_id 不一致	原因：请求中携带的 client_id 与签名、access_token 关联的 client_id 不匹配处理：确保请求的 client_id、签名生成、access_token 使用的是同一个有效 client_id
10019	初始超管不存在	原因：滴滴侧系统内部未查询到初始超管相关数据，属于系统内部异常处理：等待一段时间后重试，如果还有问题，联系滴滴侧对接人排查
12001	client_id 和 access_token 为必填项	原因：请求未传入 client_id 或 access_token，两个均为接口必填参数处理：补充传入有效且匹配的 client_id 和 access_token后重新请求
12002	不支持 http 协议	原因：使用了 HTTP 协议发起请求，接口仅支持 HTTPS 安全协议处理：将请求协议替换为HTTPS，确保请求地址以 https:// 开头
19998	timestamp 过期	原因：请求携带的时间戳超出有效时效，接口拒绝处理处理：生成当前最新的 timestamp重新发起请求，确保时间戳与服务器时间误差在有效范围内
19999	IP 不在白名单中，本次请求 IP：	原因：发起请求的服务器 IP 未配置在滴滴接口白名单内，接口做了 IP 访问限制处理：在开放平台管理后台，将本次请求的实际 IP 添加至接口白名单后再请求
36003	参数错误 (XXX 必须填写)	原因：请求传入的参数存在格式、值类型、必填项缺失等错误处理：核对接口文档的参数规范，检查所有传参的格式、类型、非空要求，修正后重新请求
400	参数错误 (未正确传输 company_id)	原因：核心参数 company_id 未传、传空或格式不符合接口要求处理：确认 company_id 值的正确性，按文档规范正确传值后重新请求
403	该托管关系不存在，无权操作	原因：当前请求的主体与滴滴侧的托管合作关系未建立 / 已失效，无对应操作权限处理：核实并确认托管关系的有效性后再操作
410	系统异常 (未获取到请求参数)	原因：滴滴侧系统内部未成功解析并获取到新增请求的参数，属于系统异常处理：先检查请求参数的传输格式是否正确，如果无误则稍作等待后重试，仍失败联系滴滴侧对接人排查
412	签名失败	原因：请求的 sign 签名值生成规则错误、参数拼接错误或密钥不一致，签名校验未通过处理：严格按照接口文档的签名生成规则重新计算 sign，核对密钥、参数拼接顺序是否正确
415	访问频次太快，请稍后	原因：短时间内发起的新增接口请求次数超出接口限流阈值，被系统限制访问处理：降低请求频次，等待一段时间后再重新发起新增请求
50102	网络请求结果错误（添加失败 \| 10003 \| 请勿重复添加）	原因：新增的部门 / 项目信息已存在于滴滴侧系统处理：核对部门 / 项目的唯一标识参数，确保信息唯一
50102	网络请求结果错误（添加失败 \| 10001 \| 上级部门信息错误）	原因：新增时传入的上级部门相关信息无效、不存在或格式错误处理：核对并修正上级部门的相关参数
50102	网络请求结果错误（添加失败 \| 10001 \| 上级项目信息错误）	原因：新增时传入的上级项目相关信息无效、不存在或格式错误处理：核对并修正上级项目的相关参数
50102	网络请求结果错误（添加失败 \| 10001 \| 开始日期不能大于结束日期!）	原因：项目开始日期大于结束日期，日期逻辑不符合规范处理：调整开始日期和结束日期的数值
50102	网络请求结果错误（添加失败 \| 10001 \| 项目名称+编号唯一，项目名称可以重复）	原因：新增的项目名称 + 编号组合已存在，违反唯一约束规则处理：修改项目名称或编号，确保二者组合系统内唯一
50102	网络请求结果错误（添加失败 \| 10001 \| 部门编号重复,请重新填写）	原因：新增的部门外部编号已存在于滴滴侧系统处理：确保外部编号唯一性
50102	网络请求结果错误（添加失败 \| 10001 \| 公司内部不存在部门主管）	原因：新增项目时传入的部门主管信息在公司内部无匹配数据处理：核对并修正部门主管相关参数，传入公司内部有效主管信息
50102	网络请求结果错误（添加失败 \| 10001 \| 公司内部不存在项目主管）	原因：新增项目时传入的项目主管信息在公司内部无匹配数据处理：核对并修正项目主管相关参数，传入公司内部有效主管信息
50102	网络请求结果错误（添加失败 \| 10001 \| 参数错误）	原因：请求传入的参数存在格式、值类型、必填项缺失等错误处理：核对接口文档的参数规范，检查所有传参的格式、类型、非空要求，修正后重新请求
50102	网络请求结果错误（添加失败 \| 10001 \| 您输入的名称含有敏感词汇，请重新输入！）	原因：新增时传入的部门名称包含滴滴侧系统设定的敏感词汇处理：删除名称中的敏感词汇
50102	网络请求结果错误（添加失败 \| 10001 \| 您输入的项目名称含有敏感词汇，请重新输入！）	原因：新增时传入的项目名称包含滴滴侧系统设定的敏感词汇处理：删除名称中的敏感词汇
50102	网络请求结果错误（添加失败 \| 10003 \| 部门数不能超过2000）	原因：当前主体在滴滴侧的部门数量已达到 2000 的上限，无法新增处理：清理系统内无用的数据，或联系相应的滴滴侧对接人添加白名单进行扩展
50102	网络请求结果错误（添加失败 \| 10003 \| 项目数不能超过2000）	原因：当前主体在滴滴侧的项目数量已达到 2000 的上限，无法新增处理：清理系统内无用的数据，或联系相应的滴滴侧对接人添加白名单进行扩展
50102	网络请求结果错误（添加失败 \| 10001 \| 添加部门失败，数据新增失败）	原因：滴滴侧系统内部处理部门新增数据时出现异常，导致数据插入失败处理：先检查请求参数是否合法，无误则稍作等待后重试，仍失败联系滴滴侧对接人排查
50102	网络请求结果错误（添加失败 \| 10001 \| 添加项目失败，数据新增失败）	原因：滴滴侧系统内部处理项目新增数据时出现异常，导致数据插入失败处理：先检查请求参数是否合法，无误则稍作等待后重试，仍失败联系滴滴侧对接人排查
50102	网络请求结果错误（添加失败）	原因：滴滴侧系统内部处理新增请求时出现未明确的网络或数据异常，导致添加失败处理：检查请求参数和网络连接，无误则稍作等待后重试，仍失败联系滴滴侧对接人排查
50253	员工不存在	原因：新增时传入的主管员工相关信息在滴滴侧系统无匹配数据处理：核对并修正主管员工相关参数，传入系统内有效员工信息后重新发起请求
50402	成本中心不存在	原因：新增部门 / 项目时关联的成本中心在滴滴侧系统无匹配数据处理：核对并修正成本中心相关参数，传入系统内有效成本中心信息后重新请求

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

使用建议

白名单开通：
1. 部门 / 项目数量超 2000 上限，需联系滴滴侧对接人进行白名单开通
2. 部门限额预算周期设为自然季度（2）/ 自然年（3），需联系滴滴侧对接人进行白名单开通
3. 项目可见范围设为公司主体可见（member_used=2），需联系滴滴侧对接人进行白名单开通
4. 发起请求的服务器 IP，需在开放平台添加至接口白名单
类型区分：通过type字段明确操作对象，1 代表部门、2 代表项目
编号唯一性：外部编号为合作方侧自定义的唯一标识，同一租户下不可重复
层级关系：
1. 关联上级需为滴滴侧已创建的部门 / 项目，未创建则无法关联
2. 二选一传值：优先传滴滴侧上级 ID（parent_id）；次优传上级外部编码（out_parent_id），项目需额外传上级外部名称（out_parent_name）
主管配置：
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	谢朱莉	更新文档字段描述