滴滴企业版

接口说明

注意

接口用途：员工修改新增接口，用于单条员工数据修改。
频率限制：连续添加员工时，请求间隔必须≥200 毫秒。
如果需要批量新增/修改员工，请使用员工批量处理接口，以提升效率并避免触发限流。

说明

**AES Key 生成规则：**AES Key 采用固定前缀拼接公司 ID 后进行 MD5 加密生成，公式：MD5(sprintf("es_traveler_%s", companyId))即： es_traveler_ + 滴滴企业版租户唯一 ID，拼接后进行 MD5 加密，结果即为 AES Key。

基本信息

HTTP URL	/river/Member/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	根据规则生成的接口签名，用于校验请求合法性与完整性；生成方式参见【接口认证-授权认证】
member_id	员工滴滴侧ID	bigint	N	员工新增接口的响应中返回，用于定位要修改的员工使用时，与employee_number（员工工号）字段二者选一即可，不可都为空优先级member_id（滴滴侧ID）高于employee_number（员工工号）
employee_number	员工工号	string	N	使用时，与member_id字段二者选一即可需要与滴滴管理后台的员工工号一致
has_card_info	是否添加证件信息	int	N	使用商旅功能时，需要证件信息，可提前维护，或是预订时维护枚举值数字： 0：不添加（默认值） 1：添加
data	员工信息	string	Y	详见 data

data

字段名	字段说明	字段类型	必填	备注
phone	员工手机号	string	N	员工手机号支持修改，修改后，员工在滴滴侧的ID不会变化格式限制：1. 大陆手机号：可直接传输 11 位号码，或是按照海外手机号格式加区号2. 港澳台与海外手机号：按照「区号 + 空格 + 号码」格式传递。示例：+86 12345678910
realname	员工姓名	string	Y	传空或者不传不做任何处理，保持原有值不变长度限制：≤ 50 字符格式限制：只支持汉字、字母、数字、下划线、斜杠、空格、点
employee_number	员工工号	string	N	不传则不做任何处理，保持原有值不变传空视为清空该字段长度限制：≤ 50 字符
email	邮箱	string	N	不传则不做任何处理，保持原有值不变传空视为清空该字段长度限制：≤ 48 字符
use_company_money	企业支付状态	int	N	不传则不做任何处理，保持原有值不变设置是否为员工开启企业支付枚举值数字： 0：否（默认值） 1：是，即员工预订符合管控规则，可由企业直接支付
regulation_id	员工制度ID数组			传0，清空员工绑定的制度信息通过制度列表、制度详情接口查询如果无法通过滴滴企业版后台通过部门/职级/全员/人群包方式分配，则可通过接口传人员制度；如果可通过上述方式分配，则不需要传值注意：仅当员工企业支付状态为 1（开启）且已配置用车制度（后台分配 / 接口分配均可），方可启用企业支付功能。
is_remark	用车备注信息	string	N	不传则不做任何处理，保持原有值不变设置员工在发单前是否需要填写说明枚举值数字： 0：无需填写（默认值） 1：需填写 2：按制度填写（建议传该值）
system_role	系统角色	int	N	枚举值数字： 1 员工 2 超级管理员
role_ids	角色	string	N	不传则不做任何处理，保持原有值不变传空将其置为员工角色需要在滴滴侧管理后台提前维护好角色，通过角色查询接口获取对应的ID 如果有多个，以_分隔注意：初始管理员、主管不支持新增；主管需在对应部门中维护主管人员信息后自动生成
immediate_superior_phone	直属上级手机号	string	N	传空或者不传不做任何处理，保持原有值不变前置要求：直属上级需为滴滴侧已创建的员工；需要与滴滴管理后台维护的手机号一致使用场景：直属上级可在审批流中担任审批人格式限制： 1. 大陆手机号：可直接传输 11 位号码，或是按照海外手机号格式加区号 2. 港澳台与海外手机号：按照「区号 + 空格 + 号码」格式传递。示例：+86 12345678910 如果均传值，直属上级手机号的优先级高于员工编号
immediate_superior_email	直属上级邮箱	string	N
immediate_superior_employee_number	直属上级员工编号	string	N
immediate_superior_memberID	直属上级滴滴侧ID	int	N
clear_immediate_superior	清空上级	int	N	传数字1代表清空上级
budget_center_id	主部门滴滴侧ID	bigint	N	传空或者不传不做任何处理，保持原有值不变员工归属的主部门，可用于拆账、审批等场景；可通过部门或项目查询接口获取，类型为1 前置要求：需为滴滴侧已创建的部门传值要求： budget_center_id（主部门滴滴侧ID）和 out_budget_id（主部门编号）选择一组参数传值即可，同时传值时，以 budget_center_id 为准
out_budget_id	主部门编号	string	N	合作方侧自定义的唯一标识，需要与滴滴管理后台维护的部门编号一致注意：如果主部门滴滴侧ID和编号均未传入，默认将员工创建到企业根部门
con_department_ids	兼岗部门滴滴侧ID	string	N	员工的兼岗部门如果有多个，以_分隔 con_department_ids与 con_department_codes二选一传参即可；同时传值时，以 con_department_ids 为准
con_department_codes	兼岗部门编号	string	N	合作方侧自定义的唯一标识，需要与滴滴管理后台维护的部门编号一致如果有多个，以_分隔
project_ids	所属项目滴滴侧ID	string	N	不传不做任何处理，保持原有值不变传空视为清空该字段如果有多个，以_分隔数量限制：≤ 500 可通过部门或项目查询接口获取，类型为2 project_ids（所属项目滴滴侧ID）与project_code_detail二选一传值。同时有值时，以project_ids为准。
project_codes_detail	所属项目信息	string	N	数量限制：≤ 500 格式要求：json 示例： "project_codes_detail":"[{"project_name":"出差巡视","project_code":"001},{"project_name":”KA客户","project_code":"002" }] " 其中，project_name为项目名称；project_code为项目编号，需与滴滴管理后台维护的一致
legal_entity_id	所属公司滴滴侧ID	string	N	传空或者不传不做任何处理，保持原有值不变前置要求：需为滴滴侧已创建的公司，可通过公司主体查询接口获取 legal_entity_id（所属公司滴滴侧ID）与out_legal_entity_id（外部编号）二选一传值
out_legal_entity_id	所属公司外部编号	string	N	传空或者不传不做任何处理，保持原有值不变前置要求：需为滴滴侧已创建的公司，需要与滴滴管理后台维护的公司编号一致
rank_id	职级滴滴侧ID	string	N	传空或者不传不做任何处理，保持原有值不变前置要求：需为滴滴侧已创建的职级，可通过职级查询接口获取 rank_id（职级滴滴侧 ID）与 out_rank_id（职级外部编号）二选一传值
out_rank_id	职级外部编号	string	N	前置要求：需为滴滴侧已创建的职级，需要与滴滴管理后台维护的职级编号一致
residentsname	常驻地名称	string	N	不传则不做任何处理，保持原有值不变不传不更新支持地级市、区县维度如果传区县，格式为城市-区县
residents_ids	常驻地滴滴侧ID	string	N	不传则不做任何处理，保持原有值不变传“”视为清空常驻地的唯一标识，滴滴侧ID与行政区划代码二者选一必填。滴滴侧ID可使用全量开城城市接口返回的ID，ID不在可识别范围不会报错，落地处理为不生效格式限制：支持地级市、区县维度支持传多个常驻地，如果有多个，以_分隔
residents_adcode	常驻地行政区划代码	string	N	常驻地的唯一标识，滴滴侧ID与行政区划代码二者选一必填。格式限制：支持地级市、区县维度支持传多个常驻地，以逗号分隔仅支持国内行政区划代码，请参考民政部官网
total_quota	限额	string	N	不传则不做任何处理，保持原有值不变传0、传空更新为不限格式限制：单位元，需为大于 0 的正整数不传代表不限代表含义：未升级限额管理模块，此处为【月限额】已升级限额规则模块，限额所对应的周期为【员工限额管理】中【员工个人限额（默认）】规则的周期
set_dismiss_time	设置的员工离职日期	string	N	不传则不做任何处理，保持原有值不变传空则清除离职时间支持格式：（1）日期：YYYY-MM-DD；（2）日期时间：YYYY-MM-DD HH:MM:SS 时间必须晚于当前时间（请务必考虑接口传输延时）。传入日期，将在隔天凌晨处理离职状态；传入具体时间，将在下一个定时任务时处理离职状态（延时不超过15分钟）。
english_surname	英文姓	string	N	不传不做任何处理，保持原有值不变传空视为清空该字段仅限开通商旅的企业员工英文姓氏（护照姓氏）对应 lastname
english_name	英文名	string	N	不传不做任何处理，保持原有值不变传空视为清空该字段员工英文名（护照名）对应firstname 含中间名时按「firstname middlename」拼接
nickname	昵称	string	N	不传不做任何处理，保持原有值不变传空视为清空该字段
sex	性别	int	N	不传不做任何处理，保持原有值不变仅限开通商旅的企业枚举值数字： 0：未知 1：男 2：女
birth_date	出生日期	string	N	仅限开通商旅的企业使用，格式为 yyyy-MM-dd 加密传输规则： 1. 采用 AES256 整体加密时，此字段明文传输，无需单独加密； 2. 不做整体加密时，此字段仅支持 AES128 单独加密； 3. 采用 AES128 整体加密时，此字段仍需单独做 AES128 加密（历史客户兼容需求）
card_list	证件信息	[]object	N	仅限开通商旅的企业使用
cert_realname	证件中文姓名	string	N	仅限开通商旅的企业使用证件上的真实中文姓名长度限制：≤ 50 字符
cert_english_surname	证件英文姓	string	N	仅限开通商旅的企业使用证件上的真实英文姓长度限制：≤ 50 字符
cert_english_name	证件英文名	string	N	仅限开通商旅的企业使用证件上的真实英文名长度限制：≤ 50 字符

证件信息

字段名	字段说明	字段类型	备注
card_type	证件类型	int	枚举值数字： 1：身份证 2：护照 3：港澳台居民居住证 4：台胞证 5：军官证 6：回乡证 7：外国人永久居留身份证
card_no	证件号码	string	加密传输规则： 1. 采用 AES256 整体加密时，此字段明文传输，无需单独加密； 2. 不做整体加密时，此字段仅支持 AES128 单独加密； 3. 采用 AES128 整体加密时，此字段仍需单独做 AES128 加密（历史客户兼容需求）
expire_date	证件过期日期	string	格式为 yyyy-MM-dd 1. 采用 AES256 整体加密时，此字段明文传输，无需单独加密； 2. 不做整体加密时，此字段仅支持 AES128 单独加密； 3. 采用 AES128 整体加密时，此字段仍需单独做 AES128 加密（历史客户兼容需求）

请求示例

curl --location 'https://api.es.xiaojukeji.com/river/Member/edit' \
--header 'Content-Type: application/json' \
--data '{
    "access_token": "1dd12f470485ba78b2c24fab3736e30c3c5ee9cc",
    "client_id": "87fca1dc60c9de0a96c20fccf2ccaa40_test",
    "client_secret": "481a0cd23c6d90dff1993982dc151601",
    "company_id": "1125915646167936",
    "data": "{\"role_ids\":\"\", \"employee_number\":\"123\",\"is_remark\":1,\"rank_id\":\"197213t912y3\"}",
    "member_id": 1125921312180375,
    "sign": "2e857c91066de9626a4fd5a039b45e46",
    "timestamp": 1690277479
}'

响应参数

字段名	字段说明	字段类型	备注
errno	错误编码	string	数字 0 表示成功，非0 表示失败
errmsg	错误信息	string	errno=0时为常量"SUCCESS"，errno!=0时为错误信息

data数据格式

字段名	字段说明	字段类型	备注
member_id	员工滴滴侧ID	int64	员工信息更新失败（请检查员工是否已离职或被删除）场景返回
phone	员工手机号	string	员工信息更新失败（请检查员工是否已离职或被删除）场景返回
status	员工状态	int	仅员工信息更新失败（请检查员工是否已离职或被删除）场景返回枚举值数字： 1：正常 4：离职 6：未绑定手机号

响应示例

正常示例

{
    "errno": 0,
    "errmsg": "SUCCESS",
    "data": null,
    "request_id": "rrm1X4Eh8SFDOUKNSaITOIOvnuWH8CbjDB7lTnfa7udVJM0rFYQKmu8IGQ82WSTL"
}

异常示例

{
    "errno": 50223,
    "errmsg": "员工信息更新失败（请检查员工是否已离职或被删除）",
    "data": {
        "member_id": "1125949321799415",
        "phone": "00016259467",
        "status": 4
    },
    "request_id": "rrm1X4Eh8SERQXqOaA0BAERnBtzjt7smdWLiifNWlm/WcJxzKWrhxLkfHDd+m1es"
}

错误码

注意

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

错误码	错误码文案	错误原因以及处理方案
10001	timestamp 过期	原因：请求携带的时间戳超出接口有效时效，服务器拒绝处理添加员工请求；处理：生成当前最新的 timestamp 重新发起请求，确保与滴滴服务器时间误差在有效范围内
10002	IP 不在白名单中，本次请求 IP：	原因：发起请求的服务器 IP 未配置在滴滴接口白名单内，接口做了 IP 访问限制；处理：在开放平台管理后台，将本次请求的实际 IP 添加至接口白名单后再请求
10003	member_id、employee_number、third_user_id 不能同时为空	原因：现有参数无法匹配到待修改的员工处理：确保member_id、employee_number能够匹配到滴滴侧已存在的员工
10003	参数错误	原因：添加员工请求中存在未明确的参数格式、值类型、非空性等基础错误，不符合接口规范处理：按接口文档全面核对所有传参，修正参数错误后重新发起请求
10018	网络异常，请重新请求	原因：发起员工修改请求时出现网络连接异常，接口未正常接收请求处理：检查网络连接状态，确认网络通畅后重新发起修改请求
12001	参数错误 (未正确传输 company_id)	原因：核心参数 company_id 未传、传空或格式不符合接口要求处理：确认 company_id 值的正确性，按文档规范正确传值后重新请求
12002	该托管关系不存在，无权操作	原因：当前请求的主体与滴滴侧的托管合作关系未建立 / 已失效，无对应操作权限处理：核实并确认托管关系的有效性后再操作
12003	该企业已删除，无权操作	原因：待修改员工所属企业已被删除，无员工修改操作权限处理：核实企业状态，使用未被删除企业的有效 company_id 重新发起请求
19998	系统异常 (未获取到请求参数)/ 系统异常	原因：滴滴侧系统内部未成功解析并获取到新增请求的参数，属于系统异常处理：先检查请求参数的传输格式是否正确，如果无误则稍作等待后重试，仍失败联系滴滴侧对接人排查
19999	签名失败	原因：请求的 sign 签名值生成规则错误、参数拼接错误或密钥不一致，签名校验未通过处理：严格按照接口文档的签名生成规则重新计算 sign，核对密钥、参数拼接顺序是否正确
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:// 开头后重新发起请求
50221	该员工信息不存在	原因： 1. company_id没有对应的管理员 2. 需要编辑的员工为管理员处理： 1. 检查company_id填写正确，或者是否已被解散 2. 管理员无法通过接口编辑，请联系滴滴侧对接人
50222	员工与指定的企业不匹配	原因：员工已被删除，或员工 id 与 company_id 未归属同一企业，归属关系不匹配处理：核实员工为未被删除的正常状态，检查并确保员工 id 与 company_id 属于同一企业，修正参数后重新发起请求
50223	员工信息更新失败（请检查员工是否已离职或被删除）	原因：员工不存在、非正常状态（离职 / 删除）处理： 1. 检查member_id是否填写正确 2. 检查员工是否已被删除，只有正常状态下的员工才可以被编辑 3. 检查更新信息中的手机号是否其他员工手机号
50223	员工信息更新失败（离职时间需晚于今天，请重设）	原因：离职时间传入已过去的时间处理：参照离职日期规则传输
50223	员工信息更新失败（已完成实名认证，初始超管不能修改姓名）	原因：已完成实名认证的企业初始超管，不支持修改姓名处理：管理员无法通过接口编辑，请联系滴滴侧对接人
50223	员工信息更新失败（请求间隔不能小于 200 毫秒，请稍后重试）	原因：连续发起添加员工请求的时间间隔小于 200 毫秒，违反接口限流规则处理：调整请求间隔至 200 毫秒以上，稍后重新发起添加员工请求
50224	员工存在未支付的订单,请先联系其支付	原因：员工修改前手机号下存在未支付订单，不符合修改条件处理：联系员工完成所有未支付订单支付后，重新发起修改请求
50253	资源不存在错误	原因：修改员工时依赖的员工相关资源在滴滴侧系统不存在处理：检查员工信息是否正确，传入系统内有效员工信息后重新发起请求
50402	部门 / 项目不存在	原因：关联的部门或项目在滴滴侧系统无匹配数据处理：核对并修正部门和项目相关参数，传入系统内有效信息后重新请求

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

版本记录

日期	更新人	更新内容	上线时间
2023.11.07	陈继诗	迁移文档
2023.11.10	陈继诗	请求增加employee_number字段，data增加immediate_superior_employee_number字段,out_budget_id，project_codes_detail json串	2024.01.04
2024.02.21	陈继诗	去掉dismiss_time字段	2024.02.21
2024.08.10	陈继诗	新加字段 clear_immediate_superior	2024.08.10
2025.02.13	高洋洋	新增con_department_ids、out_con_department_ids兼岗字段	2025.02.13
2025.02.13	高洋洋	去除out_con_department_ids、修改为con_department_codes兼岗字段	2025.02.18
2025.03.20	唐腾飞	返回新增out_legal_entity_id	2025.03.26
2025.03.24	高洋洋	增加证件、出生日期字段加密逻辑说明	2025.03.31
2025.05.15	杨露佳	返回新增residents_ids	2025.05.15
2025.05.26	高洋洋	入参数增加project_ids、project_codes_detail的元素上限说明	2025.05.27
2025.07.14	杨露佳	增加card_list描述不传或传[]不更新	2025.07.14
2025.11.17	谢朱莉	1.员工已存在情况下，响应参数增加员工状态；调整示例 2.增加证件姓名相关字段	2025.11.10
2026.1.21	谢朱莉	常驻地支持区县	2026.1.21
2026.4.10	谢朱莉	更新文档字段描述