小满OKKICRM「查询用户列表」接口字段手册权威教程

这个接口解决什么问题

在小满OKKICRM与金蝶云星辰的集成场景里,人员主数据是一切业务单据的根基:销售订单负责人、客户归属、商机跟进、任务分配都离不开「人」。/v1/user/list 接口用于一次性把小满侧的用户/职员主数据拉到集成平台,作为后续业务单据同步时的人员对照底座,典型价值是把分散在CRM里的人员档案统一沉淀,避免下游系统出现「找不到业务员」「挂错部门」等问题。

接口能力总览

• 认证方式:小满OKKICRM采用OAuth2.0标准的AccessToken模式,集成平台需先获取并缓存token,过期前主动刷新。
• 请求方式:HTTP GET,接口路径 /v1/user/list,支持按 department_id、enable_flag、last_modified_time 等条件过滤。
• 响应结构:JSON对象,核心字段放在 data.list 数组,顶层有 code、message、total_count;分页参数通常为 page 与 page_size,单页上限经验值200条。
• 分页/增量:支持按时间戳增量(last_modified_time 游标),定时任务每日凌晨3:20执行一次(20 3 * * *),策略类型为 QUERY_ONLY(纯查询,目标端配置为「写入空操作」)。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口通常通过「小满OKKICRM适配器」封装调用,我们只需配置数据源连接信息(client_id、client_secret、回调地址)与抓取策略。轻易云的字段映射器会自动读取源端元数据,把 user_id、nickname、employee_no 等关键字段列入映射面板,直接拖拽即可生成目标端(金蝶云星辰职员)的对照关系。对于纯查询策略,目标端选「写入空操作」,让数据留在轻易云的中转表里供其他策略(如销售订单同步)按 employee_no 反查引用。

跨方案实战要点

1. 主键与编码分开:多个客户项目里我们都坚持用 user_id 做唯一键、用 employee_no 做业务编码,避免昵称变更导致的主数据漂移。
2. 启用态过滤前置:在轻易云的源端过滤条件里直接加 enable_flag=1,把禁用账号挡在同步链路之外,减少下游清洗成本。
3. 昵称与全名双轨:下游业务单据往往要「显示昵称+存储全名」,建议把 nickname 和 full_name 同时落库,不要只存一个。
4. 联系人分组映射:内部(email/user_mobile/ames_email)与外部(external_*)在金蝶职员卡上是不同字段,别一股脑塞进同一列。
5. 增量用时间戳不用页码:即便接口支持分页,生产环境也建议改用 last_modified_time 游标,断点续传更稳。
6. 凌晨低峰执行:crontab 设在凌晨 3:20 避开业务高峰期,降低对小满API的限流压力。

踩坑复盘

• 坑1:把 nickname 当主键——某项目直接把昵称作为下游关联键,结果员工改名后历史单据全部失联。稳妥的做法是始终以 user_id 为主键,nickname 仅作显示。
• 坑2:启用态用户没过滤——下游金蝶职员表里出现了大量禁用账号,导致分配业务员时选了「空」人。务必在源端过滤 enable_flag=1。
• 坑3:外部联系字段全空落库——external_* 在很多用户身上本来就为空,直接同步会污染目标表。建议非空校验后再落,或干脆不映射。
• 坑4:分页循环漏抓——total_count 大于单页时,只翻了一页就停了。在轻易云里要把分页器翻到底或切到增量模式。
• 坑5:token 过期未刷新——小满token默认2小时过期,某方案跑长任务中途401。轻易云平台一般会自动续签,自研脚本要记得加刷新逻辑。

何时选用

只要业务涉及「把CRM里的人员档案同步到ERP作为业务员/负责人主数据」,就该启用本接口;尤其适合销售订单、客户、商机、任务等多模块共用同一套人员字典的场景。不适合纯展示型集成或单向回写场景——那是写接口的活儿,本接口仅做查询拉取。