小满OKKICRM「查询客户」接口字段手册权威教程:从拉到用,一篇吃透

这个接口解决什么问题

在零售、贸易、制造业的数字化项目里,我们经常要把 CRM 中的客户主数据同步到 ERP,做客户初始化、编码对照、销售阶段同步。「小满OKKICRM 查询客户」接口(/v1/company/list)就是这条链路的起点:它一次返回客户全量档案,包括基本信息、特征信息、联系信息与管理信息,用于与金蝶云星空等下游系统做字段级对照与同步。

接口能力总览

• 认证方式:小满开放平台标准的 Access Token(以请求头方式携带),在轻易云中通常封装在适配器的「鉴权」面板里,只需填入凭证即可。
• 请求方式:GET /v1/company/list,Query 参数驱动。
• 分页模式:基于 start_index(页码,默认 1)与 count(每页条数,默认 20)的传统分页;在轻易云里,平台的分页迭代器会自动翻页直到读完。
• 增量模式:通过 start_time / end_time 按 order_time(最近更新时间)增量拉取,轻易云字段映射器原生支持 {{LAST_SYNC_TIME|datetime}}、{{CURRENT_TIME|datetime}} 变量。
• 筛选能力:removed(是否含已删除)、all(公海+私海 vs 仅私海)、group_id(客户分组)。
• 响应结构:数组型,每条记录扁平返回标识、时间、基本信息、特征信息、联系信息、管理信息六大字段组。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,小满 OKKICRM 已经被封装为开箱即用的适配器。配置过程大致是:新建集成流 → 选择「小满OKKICRM」作为源系统 → 选择「查询客户」动作模板 → 在「请求参数」面板按需勾选 start_index、count、start_time、end_time、group_id、removed、all。平台的分页迭代器会自动处理翻页,字段映射器会把 company_id 识别为主键、把 name 识别为编码字段,直接拖拽到目标端的字段列即可完成映射。增量场景下,只要在时间参数里引用 {{LAST_SYNC_TIME|datetime}} 变量,就能跑出稳定的 5–10 分钟一轮的增量同步。

跨方案实战要点

1. 主键与编码分开用:company_id 是系统主键,跨系统对照用它;serial_id 是业务编码,落地到金蝶客户编码用它,两者别混。
2. 增量一定带 order_time:order_time 是最可靠的增量判断字段,不要用 create_time,否则新建后修改的客户会漏。
3. 公海 vs 私海要看业务:跨企业同步通常用 all=1 拉全量;做销售个人业绩场景时用 all=0 拉私海。
4. 重复字段二选一:name 与「基本信息公司名称」、short_name 与「基本信息简称」建议只取其一,避免目标端出现重复值触发唯一约束。
5. 地址与省分要组合:特征信息省份 + 联系信息详细地址 通常一起映射,否则目标端的省市区会断档。
6. 客户阶段必建映射表:小满的销售阶段字典与金蝶不一致,必须建一张值映射表,否则会出现「成交」变「意向」之类的脏数据。

踩坑复盘

• 坑 1:增量漏数据。直接用 create_time 做增量,导致修改过的客户永远不更新。稳妥做法是固定用 order_time,并把 start_time 设为上一轮同步时间。
• 坑 2:重复字段双写。name 和「基本信息公司名称」都映射到金蝶客户名称,触发名称不一致告警。建议在轻易云字段映射器里加一条去重规则,只保留一个。
• 坑 3:分页越界。没设置 count 上限,一次拉几万条把内存打爆。稳妥做法是显式设置 count=100,配合分页迭代器。
• 坑 4:已删除客户回流。removed 默认 0,某次手抖改成 1,把已删除客户又同步了一遍。稳妥做法是把 removed=0 写死在请求参数里,不要让业务人员改动。
• 坑 5:客户阶段字典错位。没建值映射表,直接把「成交」写进金蝶的「潜在客户」分类。稳妥做法是先在轻易云做一张阶段映射表再落库。

何时选用

只要业务涉及把 CRM 客户主数据同步到 ERP、或需要按更新时间做增量对照,这个接口就是首选;但它只负责「拉」,不负责「写」,若需要把数据落地到金蝶、云星空等下游系统,需配合后续的写入策略一起使用,且对已删除客户的同步需谨慎评估业务必要性。