小满OKKICRM客户分组查询接口字段手册权威教程

这个接口解决什么问题

在 CRM 与 ERP 的基础资料同步链路里,客户分组是高频被引用的「维度字段」——下游单据筛选、客户主数据写入、统计归集都依赖它。小满 OKKICRM 把客户分组以「字段选择器」形式开放,我们要做的就是把这个下拉选项稳定地拉出来,落到金蝶云星空的客户分组(基础资料)上,形成对照表,供后续客户主数据同步使用。

接口能力总览

• 接口路径:/v1/company/fields/selector
• 请求方法:GET
• 认证方式:Bearer Token(请求头携带,私有化部署场景下由网关统一签发)
• 核心请求参数:field=group_id(固定值,表示请求客户实体的 group_id 字段选项)
• 响应结构:典型的 id-name 选项数组,每条记录含 id(主键)与 name(名称),无显式分页字段,按源系统一次性返回。
• 同步策略:纯查询(QUERY_ONLY),Target 端配置为「写入空操作」,不向目标系统落库,仅作为下游映射的数据源。
• 调度方式:常以每日凌晨定时任务(如 crontab 3 2 * * *)触发,与下游客户主数据同步错峰执行。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这类「字段选择器」接口通常采用查询策略适配器封装:Source 端配置 HTTP 请求模板,填入 field=group_id,响应解析器自动按 id-name 数组结构展开。Target 端配置为「空操作」,平台仅将结果缓存到映射器上下文,不写目标库。

字段映射方面,轻易云的字段映射器会根据 metadata 自动识别 id(主键)与 name(编码),并生成与金蝶云星空 FGroup_FNumber / FGroup_FName 的对照节点,工程师只需在映射画布里确认方向与清洗规则即可。跨系统对照场景下,可启用平台内置的「按名称模糊匹配 + 按 ID 精确匹配」双策略,避免单纯依赖名称造成的误匹配。

跨方案实战要点

1. 永远把字段选择器当作主数据源来对待:不要直接在业务接口里硬编码 group_id,先跑一遍 selector 把全量选项缓存下来,再提供给下游接口引用。
2. 固定 field 参数是惯例,但要警惕多版本:同一个实体在不同小满版本里,group_id 字段名偶有调整,适配器要支持配置化,而不是写死。
3. id 与 name 必须同时落对照表:仅靠名称做映射容易出现同名分组,后续客户同步写入时会落错账套。
4. 调度时点与下游解耦:selector 跑在凌晨,客户主数据同步跑在上午,中间留出对照表刷新窗口,避免读到陈旧分组。
5. 响应为空时不要默认成功:若源系统返回空数组,极可能是 token 过期或租户隔离配置错误,要在监控里显式告警。
6. 私有化部署的域名隔离:不同环境的网关域名不同,适配器里的 baseUrl 必须按环境变量注入,不要打包进镜像。

踩坑复盘

• 坑 1:把 selector 当成客户列表接口。该接口只返回字段选项,不返回客户明细,有人误用它做客户拉取,结果只拿到十几条分组数据。
• 坑 2:忽略 metadata 的 number 标注。name 字段在源系统是 number 类型,如果在映射器里当成普通字符串处理,可能导致前后空格、全角字符未清洗。
• 坑 3:对照表只存 id 不存 name。后续运维排查时,只能看到一串 ID 不知道含义,定位问题极慢。稳妥的做法是 id、name、源系统标识、更新时间一起落库。
• 坑 4:调度写错时区。私有化服务器时区若与 UTC 不一致,crontab 触发时间会漂移,导致下游读到「昨天的分组」。
• 坑 5:Token 过期未做自动续签。selector 接口对 token 敏感,过期后返回的并非明确错误码,而是空数组,极易被误判为「无分组」。

何时选用

该接口适用于需要把 CRM 端的客户分组维度同步到 ERP 端基础资料的场景,尤其是客户主数据写入前需要先建立分组对照表、或者下游业务单据需要按 CRM 分组筛选回传的场景;不适用于拉取客户明细、订单或自定义业务数据,也不建议在高频实时链路中调用,因其一次性返回全量选项,体量较大。