轻易云
注册体验

小满OKKICRM 用户人员查询接口字段手册权威教程

· 陈洁琳· 工程最佳实践· 39 次浏览· 约 4 分钟读完
小满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_idstring用户在小满系统中的唯一标识真正的主键,用于去重与跨系统对照
nicknamestring昵称/登录名metadata中id与number均配置为此字段,实际集成时建议作为业务编码而非主键
full_namestring用户真实姓名用于单据显示,可与金蝶业务员名称FName映射
emailstring电子邮箱可用于身份校验,但注意员工离职后邮箱可能保留
department_idstring部门ID用于与金蝶部门编码对照,组织架构同步的关键字段
department_namestring部门名称展示用,跨系统对照时优先用department_id

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的调用通常采用「查询适配器」封装:源系统选择小满OKKICRM,接口选择「用户人员列表」,填入AppKey与AppSecret。轻易云的字段映射器会自动把user_id、nickname、full_name、department_id等字段映射为通用概念(如user_id、user_code、full_name、department_id),无需手动逐个配置。当策略为QUERY_ONLY时,Target端配置为「空操作」即可,拉取的数据会暂存于轻易云中台,供后续与金蝶业务员做对照映射。

跨方案实战要点

  1. 主键选择要谨慎:多个方案均出现metadata把nickname同时配为id与number的情况,但nickname存在重名风险,真实场景中务必以user_id作为技术主键。
  2. 组织架构先于人员同步:部门数据应先于人员同步到位,否则department_id找不到对应部门,后续单据归属会失效。
  3. 与金蝶业务员对照是核心价值:该接口的真正落地场景几乎都是「小满user ↔ 金蝶业务员」双向映射,编码对应nickname ↔ FNumber,名称对应full_name ↔ FName。
  4. 分页与限流要兼顾:在客户实践中,我们发现该接口单页返回数量有限,务必在轻易云里配置循环拉取逻辑,并加上失败重试。
  5. 增量识别需自定义字段:接口本身不返回明确的更新时间戳,增量同步需要额外记录已拉取的user_id集合,下次拉取后做差集。
  6. 定时执行避开业务高峰:凌晨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

评论