管理API对接文档（2024版）

最近更新时间：

接口说明

注意
  • 常驻地目前只支持如“北京”、“北京市”、“北京市海淀区”格式，不支持“海淀区”此类格式，如果传参中带了区县则必须把“市”、“区“、”县”字段都带上。
  • 同一公司。连续添加员工，需要间隔 150ms
  • 人员唯一值可以在手机号，员工编号，邮箱中指定一个，如果多个一起传递时，会一起校验企业级内是否有存在重复的信息并报错返回。


基本信息

HTTP URL

/river/Member/single

HTTP Method

POST

权限要求


请求头

参数名称

参数值

Content-Type

application/json

请求参数

字段名

字段说明

字段类型

必填

备注

client_id

申请应用时分配的AppKey

string

Y


access_token

授权后的access token

string

Y


company_id

企业ID

string

Y


timestamp

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

int

Y


sign

签名

string

Y


send_message

是否发短信配置

int

N

枚举值数字 0 不发送，1 发送， 员工添加成功后发短信（包含双向确认短信） 默认值为0

has_card_info

是否含有证件信息

int

N

是否含有证件信息，当传证件信息时，此字符传1，其他情况不传或传0

data

员工信息

string

Y

详见 data


data

字段名

字段说明

字段类型

必填

备注

member_type

员工信息类型

int

N

枚举值数字 0：手机号，1：工号。2：邮箱；默认为0

phone

员工手机号

string

N

member_type 为0时必传

realname

员工姓名

string

Y


employee_number

员工工号

string

N

member_type 为1时必传 员工在公司的员工号

email

邮箱

string

N

member_type 为2时必传

system_role

系统角色

int

N

枚举值数字 0 车辆预定人员，1 普通管理员，2 超级管理员

role_ids

角色

string

N

可以通过角色API获取对应的ID

immediate_superior_phone

员工直属上级的手机号码

string

N

直属上级可在审批流中担任审批人 immediate_superior_phone与immediate_superior_eid以手机号优先

immediate_superior_email

直属上级邮箱

string

N

直属上级邮箱

immediate_superior_employee_number

员工直属上级的员工编号

string

N

直属上级可在审批流中担任审批人

immediate_superior_memberID

直属上级 ID

int

N


residentsname

常驻地中文

string

N


use_company_money

是否企业支付余额

int

N

枚举值数字 0 否，1 是

total_quota

每月配额

string

N

单位元 0 不限

is_remark

叫车时备注信息是否必填

string

N

枚举值数字 0 选填，1 必填，2 按制度填写

budget_center_id

所在部门ID

bigint

N

budget_center_id与out_budget_id同时存在时，以budget_center_id为准。

out_budget_id

客户部门CODE

string

N


con_department_ids

所在兼岗部门ID

string

N

con_department_ids与con_department_codes都存在时，以con_department_ids为准 多个使用“_”连接

con_department_codes

所在兼岗部门CODE（同部门新增修改的out_budget_id）

string

N

con_department_ids与con_department_codes都存在时，以con_department_ids为准 多个使用“_”连接

regulation_id

用车制度ID数组

string

N

制度ID；通过制度列表接口查询；多个用 _ 连接；默认为空
若该员工的所有制度都是在es后台通过部门/职级/全员方式分配，则员工身上的制度字段不用传；同时注意检查use_company_money字段是否传输，制度和企业支付权限都有才能企业支付。

project_ids

所在项目ID

string

N

可以填多个，以_分隔。通过成本中心查询api获取id（类型为2）

project_codes_detail

项目信息

string

N

人员上绑定的项目信息
将project_codes_detail的值转为 json 字符
"project_codes_detail":"[{"project_name":"出差巡视","project_code":"travelcode" },{"project_name":"出差巡视","project_code":"travelcode" }] "
project_ids与project_code_detail同时有值时，以project_ids为准。元素上限100个

legal_entity_id

所在公司主体id

string

N


out_legal_entity_id

外部所在公司主体id

string

N


rank_id

职级id

string

N


out_rank_id

外部职级 ID

string

N


english_surname

英文姓

string

N

同lastname

english_name

英文名

string

N

同firstname 有middlename时 english_name=firstname middlename

nickname

昵称

string

N


sex

性别

int

N

枚举值数字 0 未知 1 男 2 女

birth_date

出生日期

string

N

格式2000-01-01
注：
1、若采用AES256整体加密，此字段需明文传输，无需单独再加密
2、若不整体加密传输时，此字段只可采用AES128加密传输
3、若采用AES128整体加密，此字段仍需采用AES128单独加密（存在历史客户原因）

card_list

证件信息

[]object

N



证件信息

字段名

字段说明

字段类型

备注

card_type

证件类型

int

枚举值数字 1. 身份证，2. 护照，3. 港澳台居民居住证，4. 台胞证，5. 军官证，6. 回乡证，7. 外国人永久居留身份证

card_no

证件号码

string

证件号码
注：
1、若采用AES256整体加密，此字段需明文传输，无需单独再加密
2、若不整体加密传输时，此字段只可采用AES128加密传输
3、若采用AES128整体加密，此字段仍需采用AES128单独加密（存在历史客户原因）

expire_date

证件过期日期

string

格式：2050-01-01
注：
1、若采用AES256整体加密，此字段需明文传输，无需单独再加密
2、若不整体加密传输时，此字段只可采用AES128加密传输
3、若采用AES128整体加密，此字段仍需采用AES128单独加密（存在历史客户原因）

请求示例

curl --location 'https://api.es.xiaojukeji.com/river/Member/single' \
--header 'Content-Type: application/json' \
--data-raw '{
            "access_token":"63e41b716358166c453ed0a812594658c2c9a8f0",
            "company_id":"1125910319468282",
            "data":"{\"phone\":\"11100001798\",\"realname\":\"bob\",\"residentsname\":\"Shanghai\",\"employee_number\":\"\",\"email\":\"caozhengbobo999@qq.com\",\"department\":\"QA\",\"branch_name\":\"Helper\",\"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


phone

员工手机号

string




响应示例

正常示例

异常示例

{
    "errno": 50202,
    "errmsg": "添加员工失败 (项目不存在，project_ids:111000080_1110999292)",
    "data": null,
    "request_id": "+xvHWIzBGl26+y9UcCcJ8fgYSJmNzJYN9YETDwco0DlPtiN+PTY8IM7svHGEjf5F"
}

错误码

通用错误解决方案

xxxxxx有以下可能：

  1. 请求间隔不能小于150毫秒,请稍后重试
  2. 公司已停
  3. 管理员已注销
  4. 只有超管和初始超管才能添加员工
  5. 一次只能添加一名员工；http://api.es.xiaojukeji.com/river/Member/single 该接口每次只能添加一个员工
  6. 员工已存在
    员工手机号、邮箱、员工工号必须唯一。同时返回该员工对应的滴滴id、手机号
  7. 员工处于待确认状态,请联系员工自行确认加入
    员工已在A企业，现在B企业去添加该员工，此时B企业添加失败，员工进入B企业的待确认列表中，会在企业APP上的卡片提示员工，是否加入B企业; 员工确认链接会通过data.url返回，可以让员工点击链接进行操作
  8. 员工存在于其他公司,已经通知该员工加入企业,请联系员工自行确认加入 与7的区别是，提示这个错误时，会给员工发送短信提示是否加入新企业
    员工确认链接会通过data.url返回，可以让员工点击链接进行操作
  9. 员工已存在于其他企业,请联系员工退出企业
    员工确认链接会通过data.url返回，可以让员工点击链接进行操作
  10. 部门不存在
    调用成本中心查询接口,参数中的type=1获取所有部门的信息,返回值中的id(即部门id)就是员工添加接口的budget_center_id
  11. 项目不存在
    调用成本中心查询接口,参数中的type=2获取所有部门的信息,返回值中的id(即部门id)就是员工添加接口的project_ids
  12. 制度不存在
    调用用车制度列表接口,返回值中的regulation_id就是员工添加接口的regulation_id


版本记录

日期

更新人

更新内容

上线时间

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_codes兼岗字段

2025.02.13

2025.03.20

唐腾飞

新增out_legal_entity_id

2025.03.26

2025.03.24

高洋洋

对于证件、出生日期的加密逻辑说明

2025.03.31