小满OKKICRM 用户人员查询接口字段手册权威教程
小满OKKICRM金蝶云星空接口字段手册用户人员金蝶业务员轻易云主数据同步
这个接口解决什么问题
小满OKKICRM的「查询用户人员」接口(/v1/user/list)用于从CRM拉取用户主数据,这是销售订单归属、客户负责人、业绩核算、权限分配等业务场景的基础。该接口典型用途包括:小满用户与金蝶业务员映射、组织架构初始化、跨系统用户身份对照。在多个客户项目里,我们发现这一接口往往是基础资料同步链路的起点,先把人理清楚,后续单据、报表才有可靠的归属人字段。
接口能力总览
- 认证方式:小满OKKICRM标准的AppKey/AppSecret签名认证,请求头携带访问令牌。
- 请求结构:GET方法,路径
/v1/user/list,支持按部门、状态等条件过滤;响应为JSON数组结构,每条记录代表一个用户。 - 分页模式:支持分页参数(常见的page/pageSize或offset/limit组合),在真实场景中需要按页循环拉取直至取完。
- 增量模式:接口本身以全量列表形式返回,增量识别依赖
user_id去重;部分客户通过更新时间字段做增量过滤。 - 策略类型:QUERY_ONLY(纯查询),Target配置为「写入空操作」,仅用于数据拉取与映射。
- 定时任务:典型crontab为
25 3 * * *,每日凌晨执行一次。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| user_id | string | 用户在小满系统中的唯一标识 | 真正的主键,用于去重与跨系统对照 |
| nickname | string | 昵称/登录名 | metadata中id与number均配置为此字段,实际集成时建议作为业务编码而非主键 |
| full_name | string | 用户真实姓名 | 用于单据显示,可与金蝶业务员名称FName映射 |
| string | 电子邮箱 | 可用于身份校验,但注意员工离职后邮箱可能保留 | |
| department_id | string | 部门ID | 用于与金蝶部门编码对照,组织架构同步的关键字段 |
| department_name | string | 部门名称 | 展示用,跨系统对照时优先用department_id |
在轻易云上如何配置
在轻易云数据集成平台里,这个接口的调用通常采用「查询适配器」封装:源系统选择小满OKKICRM,接口选择「用户人员列表」,填入AppKey与AppSecret。轻易云的字段映射器会自动把user_id、nickname、full_name、department_id等字段映射为通用概念(如user_id、user_code、full_name、department_id),无需手动逐个配置。当策略为QUERY_ONLY时,Target端配置为「空操作」即可,拉取的数据会暂存于轻易云中台,供后续与金蝶业务员做对照映射。
跨方案实战要点
- 主键选择要谨慎:多个方案均出现metadata把nickname同时配为id与number的情况,但nickname存在重名风险,真实场景中务必以user_id作为技术主键。
- 组织架构先于人员同步:部门数据应先于人员同步到位,否则department_id找不到对应部门,后续单据归属会失效。
- 与金蝶业务员对照是核心价值:该接口的真正落地场景几乎都是「小满user ↔ 金蝶业务员」双向映射,编码对应nickname ↔ FNumber,名称对应full_name ↔ FName。
- 分页与限流要兼顾:在客户实践中,我们发现该接口单页返回数量有限,务必在轻易云里配置循环拉取逻辑,并加上失败重试。
- 增量识别需自定义字段:接口本身不返回明确的更新时间戳,增量同步需要额外记录已拉取的user_id集合,下次拉取后做差集。
- 定时执行避开业务高峰:凌晨3:25的crontab既能保证天亮前数据就绪,又能避开小满CRM白天的高频调用窗口。
踩坑复盘
- 坑1:nickname被当作主键导致重复。某零售企业直接把nickname当作主键写入下游,结果出现重名用户覆盖。稳妥做法是统一以user_id为技术主键,nickname只作为业务编码。
- 坑2:department_id为空导致下游报错。部分用户未分配部门,字段返回null,在金蝶端做对照时会找不到Fdept编码。建议在轻易云里加一层空值过滤,或先在源端补齐部门归属。
- 坑3:邮箱变更未触发同步。邮箱作为联系方式容易随员工调整而变化,但user_id不变,容易出现邮箱不一致却没被发现的情况。建议在字段映射器里把email标为「可变更字段」并记录变更日志。
- 坑4:全量拉取耗时长。当用户量达到数万级时,单次全量拉取可能超时。稳妥的做法是分批按部门过滤,或首次全量、后续增量。
- 坑5:认证Token过期未重试。小满的访问令牌有效期有限,凌晨任务跑到一半Token失效会导致数据截断。轻易云的适配器默认带有Token自动刷新机制,务必确认已开启。
何时选用
该接口适用于需要把小满CRM用户主数据同步到ERP(如金蝶云星空业务员)、建立组织架构、或为后续销售订单、客户主数据等业务单据提供归属人字段的场景。边界在于:它只解决「人」的同步,不含权限、角色等安全维度;若需实时双向同步用户状态变更,需另配变更捕获机制。
本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-086-ok-d70d