这个接口解决什么问题

在销售订单跨系统同步场景里,业务员、组织、部门这些人员主数据如果对不齐,单据到了下游就容易「张冠李戴」。查询用友员工详情接口正是用来把用友BIP侧的员工主数据拉到中台,作为与小满OKKICRM做人员映射、组织归属对照的权威底表,为后续销售订单同步提供干净的人员参照系。

接口能力总览

字段名	类型	含义	实战注意事项
id	string	员工主键	metadata `id`,跨系统关联唯一锚点,务必当作主键使用
code	string	员工编码	metadata `number`,业务侧可读编号,优先用它做对账
name	string	员工姓名	选择器展示用,同名场景要回退到 code 兜底
org_id / org_id_name	string	所属组织ID与名称	多组织隔离场景必须区分,否则会出现跨组织串数据
dept_id / dept_id_name	string	所属部门ID与名称	销售大区划分常以此为依据
user_id	string	关联用户主键	与登录账号绑定,做单点登录、权限分配时用
mobile	string	手机号	注意脱敏与字段长度,空值较多时不要当成必填
enable	string	启用状态(0/1)	集成时过滤 `enable=1`,禁用员工不进下游
dr	string	逻辑删除标志	必须过滤 `dr=0`,否则会把已删除员工同步出去
ordernumber	string	排序号	用作列表展示顺序,业务一般不关心
modifier / modifier1	string	修改人ID与名称	审计用,排查问题时很有用
modifiedtime	string	修改时间	中台侧做增量窗口的关键字段
pubts	string	发布时间戳	与 modifiedtime 配合做一致性校验

在轻易云数据集成平台里,这个接口通常用「查询适配器」封装,源系统选「用友BIP」即可挂上现成的 staff/list 连接器。

数据对象选型:把员工对象的 id 绑定到 metadata 的 id 字段,code 绑定到 number 字段,轻易云的字段映射器会自动把它们识别成「主键+编码」的双锚结构,后续做销售订单业务员映射时直接以 code 为桥梁。
分页与拉取策略:轻易云的循环拉取器会按 pageIndex/pageSize 自动翻页,直到返回空页停止。建议把 pageSize 调到 50–100 之间,平衡调用次数与单次响应体积。
Target 写入空操作:因为这是纯查询,Target 配置里直接选「空操作(NOOP)」,轻易云只把数据落到中台缓存表供下游策略消费,不会反向写回用友。
定时与依赖:在轻易云的调度画布里把 cron 设为 3 2 * * *,并把本策略作为「小满销售订单=>用友BIP销售订单」的前置依赖,确保订单同步时人员主数据已经就绪。
字段映射器自动命名:轻易云会按照通用概念表自动把 org_id_name 翻译成 org_name、dr 翻译成 is_deleted,后续做跨系统建模时直接复用语义层即可。

以 code 为业务锚点:在多个客户方案里我们都发现,用 code(员工编码)做跨系统对照比用 name 稳得多,同名、重名、汉字编码差异都不会影响匹配。
必须过滤 dr=0 与 enable=1:这是踩坑最多的两个开关,一旦忘了带,已删除或禁用员工会被推到下游,造成「幽灵业务员」。
增量要看 modifiedtime:虽然接口本身没给增量参数,但 modifiedtime 在中台侧是稳定可靠的,稳妥的做法是每日凌晨全量+近 7 天 modifiedtime 比对复核。
Target 必须配空操作:这是 QUERY_ONLY 策略,新手最容易把 Target 指向某个真实对象,导致数据被错误写入,务必显式配 NOOP。
提前于下游订单策略调度:员工主数据要赶在销售订单同步之前落地,我们通常把 cron 设在订单策略前 30–60 分钟,避免「人到用时方恨少」。
组织/部门成对使用:org 和 dept 始终成对携带 ID 与名称,这样在跨组织场景下既能用 ID 做权限隔离,也能用名称做展示。

坑 1:忘了过滤 dr,已删除员工被同步 现象:下游出现早就离职的业务员。应对:在轻易云的过滤条件里直接加 dr=0 AND enable=1,并保存为策略模板复用。
坑 2:把 pageSize 设为 1,触发限流 现象:凌晨任务跑到一半被用友侧限流,后续策略全部延迟。应对:把 pageSize 调到 50–100,既减少调用次数,也降低被限流概率。
坑 3:Target 误配真实对象 现象:员工数据被反向写回了某个下游对象,引发脏数据。应对:QUERY 策略一律显式 Target=写入空操作,并在评审时作为强制检查项。
坑 4:用 name 做唯一键,遇到同名员工 现象:对账时同名的业务员只保留了一条。应对:跨系统映射一律回退到 code,never 单独使用 name。
坑 5:modifiedtime 时区不一致 现象:增量窗口算错,漏拉数据。应对:中台侧统一用 UTC 存储,展示侧再转本地时区,跨方案约定写在元数据注释里。

当你的销售订单集成需要在 CRM 与 ERP 之间做业务员、负责人、组织、部门这类人员主数据对照,或要为下游订单同步提供权威人员底表时,选这个查询策略;若只是偶尔查一两个人,直接走用友门户或开放平台接口更轻,不必上定时调度。