管理API对接文档

最近更新时间：

接口说明

注意
  • 接口用途：员工单个新增接口，用于单条员工数据创建。
  • 频率限制：连续添加员工时，请求间隔必须≥150 毫秒。
  • 如果需要批量新增/修改员工，请使用 员工批量处理接口 ，以提升效率并避免触发限流。
说明
  • **AES Key 生成规则：**AES Key 采用固定前缀拼接公司 ID 后进行 MD5 加密生成，公式：MD5(sprintf("es_traveler_%s", companyId))即： es_traveler_ + 滴滴企业版租户唯一 ID，拼接后进行 MD5 加密，结果即为 AES Key。

基本信息

HTTP URL

/river/Member/single

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

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

send_message

是否发短信配置

int

N

员工添加到新企业后是否发送短信
枚举值数字：
0：不发送（默认值）
1：发送
注意：
1. 包括未退出上家企业的员工，被添加至新企业后，手动退出原企业的确认短信
2. 如果滴滴侧配置了自动发送短信，API传参可能不生效，请与对接人确认

has_card_info

是否添加证件信息

int

N

使用商旅功能时，需要证件信息，可提前维护，或是预订时维护
枚举值数字：
0：不添加（默认值）
1：添加

data

员工信息

string

Y

详见 data


data

字段名

字段说明

字段类型

必填

备注

member_type

员工唯一主键类型

int

N

枚举值数字：
0：手机号（默认值）
1：工号
2：邮箱

phone

员工手机号

string

N

member_type=0时必填支持大陆、港澳台与海外手机号

格式限制：1. 大陆手机号：可直接传输 11 位号码，或是按照海外手机号格式加区号2. 港澳台与海外手机号：按照 「区号 + 空格 + 号码」 格式传递。示例：+86 12345678910

realname

员工姓名

string

Y

长度限制：≤ 50 字符
格式限制：只支持汉字、字母、数字、下划线、斜杠、空格、点

employee_number

员工工号

string

N

member_type=1时必填
长度限制：≤ 50 字符

email

邮箱

string

N

member_type=2时必填
长度限制：≤ 48 字符

use_company_money

企业支付状态

int

N

设置是否为员工开启企业支付
枚举值数字：
0：否（默认值）
1：是，即 员工预订符合管控规则，可由企业直接支付

regulation_id

员工制度ID数组

string

N

通过 制度列表、制度详情接口 查询
如果无法通过滴滴企业版后台通过部门/职级/全员/人群包方式分配，则可通过接口传人员制度；如果可通过上述方式分配，则不需要传值

注意：
仅当员工企业支付状态为 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


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

所属项目信息

[]object

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 的正整数
不传代表不限

代表含义：
未升级限额管理模块，此处为【月限额】
已升级限额规则模块，限额所对应的周期为【员工限额管理】中【员工个人限额（默认）】规则的周期

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/single' \
--header 'Content-Type: application/json' \
--data '{
    "access_token": "63e41b716358166c453ed0a812594658c2c9a8f0",
    "company_id": "1125910319468282",
    "data": "{\"phone\":\"11100001798\",\"realname\":\"bob\",\"residentsname\":\"Shanghai\",\"residents_ids\":\"13_14\",\"employee_number\":\"\",\"email\":\"caozhengbobo999@qq.com\",\"department\":\"QA\",\"system_role\":0,\"use_company_money\":1,\"total_quota\":10000,\"is_remark\":0,\"regulation_id\":\"\",\"english_surname\":\"cao_zheng_bo\",\"english_name\":\"cao_zheng_bo112222222222\",\"nickname\":\"Didiha\",\"sex\":\"2\",\"project_codes_detail\":[{\"project_code\":\"2390009XXXX\",\"project_name\":\"XXXXXX铆接车间\"}]}",
    "sign": "9d2b49a4e3c9dd96bd5e9dc7266bbdd0",
    "client_id": "1238f2427b47bf27ee6791c6b02ce486",
    "sign_key": "1a3947C3e83429A3eacd",
    "timestamp": "1690270271"
}'

响应参数

字段名

字段说明

字段类型

备注

errno

错误编码

string

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

errmsg

错误信息

string

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

data

返回值对象

object



data数据格式

字段名

字段说明

字段类型

备注

id

员工滴滴侧ID

int64

新增员工成功场景返回，员工在滴滴的唯一标识

member_id

员工滴滴侧ID

int64

添加员工失败（员工已存在）场景返回，员工在滴滴的唯一标识

phone

员工手机号

string

新增员工成功、添加员工失败（员工已存在）场景返回

status

员工状态

int

仅添加员工失败（员工已存在）场景返回
枚举值数字：
1：正常
4：离职
6：未绑定手机号


响应示例

正常示例

{
    "errno": 0,
    "errmsg": "SUCCESS",
    "data": {
        "id": 4503601945668155,
        "phone": "00016259447"
    },
    "request_id": "jYBkiaQGmXtnTUntJueM0TQeFGgaoQJlKea3WnGbCKHmQVNOqsNImfqrC6ZK93NQ"
}

异常示例

{
    "errno": 50202,
    "errmsg": "添加员工失败 (员工已存在)",
    "data": {
        "member_id": 1125949321799415,
        "phone": "00016259467",
        "status": 4
    },
    "request_id": "jYBkiaQGmXtUiRg9OguByx2NXGo74N9bbRZL9iljfeMtfZovNAIObGkuaSMmBM6m"
}

错误码

注意

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

错误码

错误码文案

错误原因以及处理方案

10001

timestamp 过期

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

10002

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

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

10003

请求间隔不能小于 150 毫秒

原因：连续发起添加员工请求的时间间隔小于 150 毫秒，违反接口限流规则
处理：调整请求间隔至 150 毫秒以上，稍后重新发起添加员工请求

10003

参数错误

原因：添加员工请求中存在未明确的参数格式、值类型、非空性等基础错误，不符合接口规范
处理：按接口文档全面核对所有传参，修正参数错误后重新发起请求

12001

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

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

12002

该托管关系不存在，无权操作

原因：当前请求的主体与滴滴侧的托管合作关系未建立 / 已失效，无对应操作权限
处理：核实并确认托管关系的有效性后再操作

19998

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

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

19999

签名失败

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

400

非法的 client_id

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

403

无权访问该接口

原因：当前 client_id 未获取该接口的访问权限，接口做了权限管控
处理：联系滴滴侧对接人，为该 client_id 开通当前接口的访问权限

408

参数错误，未正确传输 timestamp

原因：timestamp 参数未传、传空或格式不符合接口要求（如非数字、位数错误）
处理：按文档规范正确传值 timestamp（非空、匹配格式），建议生成当前最新时间戳

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 后重新请求

50202

添加员工失败 (员工已存在)

原因：待添加的员工信息已存在于当前企业系统中
处理：核实员工是否已添加

50202

添加员工失败 (证件信息异常)

原因：证件信息异常
处理：核对员工证件信息有效性，修正后重新请求

50202

添加员工失败 (管理员已注销)

原因：管理员已注销
处理：确认管理员账号状态，恢复正常后再操作

50202

添加员工失败 (直属上级不存在)

原因：直属上级的ID、工号无法匹配到滴滴侧已经存在的员工
处理：传入有效直属上级信息，确保上级存在

50203

添加员工失败 (工号已存在)

原因：待添加员工的工号已存在于系统中，违反唯一性约束
处理：核对并修改员工的工号为系统内未使用的唯一值

50204

添加员工失败 (邮箱已存在)

原因：待添加员工的邮箱已存在于系统中，违反唯一性约束
处理：核对并修改员工的邮箱为系统内未使用的唯一值

50206

员工已存在于其他企业

原因：待添加员工已归属其他企业，无法直接添加
处理：联系员工退出原企业（通过APP或者短信），完成相关操作后再重新添加

50223

员工信息更新失败（项目不存在，project_ids:IRF推送失败： 网络请求结果错误（添加失败 | 10001 | 您输入的项目名称含有敏感词汇，请重）

原因：新增时传入的项目名称包含滴滴侧系统设定的敏感词汇
处理：删除名称中的敏感词汇

50243

手机号不在资源池中

原因：待添加员工的手机号未在滴滴侧指定资源池中，无法完成添加
处理：先检查手机号是否有异常问题，如果排查无误，联系滴滴侧对接人处理

50402

成本中心不存在

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

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


使用建议

核心调用规则

  1. 单条新增请求间隔≥150 毫秒，批量操作请使用【员工批量处理接口】，避免限流
  2. 仅支持HTTPS 协议，请求头必须配置Content-Type:application/json
  3. 新增后可通过返回参数判断结果，员工已存在会返回错误码 50202 及员工状态


唯一主键规则

主键类型通过member_type指定：0 = 手机号（默认）、1 = 工号、2 = 邮箱，三选一即可

  1. 无手机号时，必须传工号或邮箱作为唯一标识，不可无主键新增

  2. 同时传递多个主键值（如手机号 + 工号），系统会统一校验企业内唯一性，任意一个重复即报错

  3. 工号 / 邮箱作为主键时，需分别传employee_number/email，且对应字段为必填


手机号传输格式

  1. 大陆手机号：直接传 11 位纯数字（如 13800138000）

  2. 港澳台 / 海外手机号：严格按「区号 + 空格 + 号码」格式（如 + 852 12345678、+1 1234567890）

  3. 所有手机号格式错误会导致参数校验失败


直属上级

  1. 需为滴滴侧已创建的员工，支持传手机号 / 邮箱 / 工号 / ID，四选一即可

  2. 手机号 / 邮箱格式需与员工主键的格式要求一致，信息不匹配返回错误码 50202


主部门

  1. 二选一传值：budget_center_id（滴滴侧 ID）/out_budget_id（外部编号），ID 优先级更高

  2. 均不传则默认添加至企业根部门，传无效值返回错误码 50402


项目 / 兼岗部门 / 公司 / 职级

  1. 均支持「滴滴侧 ID」和「外部编号」二选一传值，ID 优先级更高

  2. 多个值用下划线_分隔，项目数量≤500，传无效值返回错误码 50402


常驻地

  1. 二选一传值：residents_ids（滴滴侧 ID）/residents_adcode（行政区划代码）
  2. 名称传residentsname，格式为「城市」或「城市 - 区县」（如北京、上海 - 浦东新区），不可仅传区县
  3. 如果只传名称，residentsname的优先级高于residents_ids（滴滴侧 ID）/residents_adcode（行政区划代码），但是容易出现匹配错误，不建议这么使用


企业支付与制度

  1. 开启企业支付需传use_company_money=1，且需配置用车制度（后台分配或接口传regulation_id）

  2. total_quota（个人限额）传大于 0 的正整数（单位：元），限额周期随系统配置


商旅证件信息（按需配置）

  1. 需先传has_card_info=1，再维护card_list（证件信息）、birth_date（出生日期）等字段

  2. 证件号 / 过期日期 / 出生日期需按规则AES 加密，AES Key 生成规则：MD5 (es_traveler_+company_id)

  3. 证件类型仅支持枚举值，信息异常返回错误码 50202


其他关键配置

  1. send_message：0 = 不发通知短信（默认）、1 = 发送
  2. is_remark：建议传 2（按制度填写用车备注），0 = 无需填写、1 = 必须填写
  3. 英文姓 / 名、昵称、性别仅开通商旅的企业需传，非商旅企业可忽略


版本记录

日期

更新人

更新内容

上线时间

2023.11.07

陈继诗

迁移文档


2023.11.10

陈继诗

增加data增加immediate_superior_employee_number字段，out_budget_id字段，project_codes_detail json串

2024.01.04

2024.02.21

陈继诗

去掉branch_name，department文档显示。

2024.02.21

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.11.17

谢朱莉

1.员工已存在情况下，响应参数增加员工状态；调整示例
2.增加证件姓名相关字段

2025.11.10

2025.12.09

郭相均

修改project_codes_detail字段类型

2025.12.09

2026.1.21

谢朱莉

常驻地支持区县

2026.1.21

2026.4.10

谢朱莉

更新文档字段描述