道一云·七巧客户信息查询接口字段手册权威教程

这个接口解决什么问题

在 CRM 与低代码平台集成的真实场景里，客户主数据往往散落在多个系统。我们经常需要从道一云·七巧表单应用里把客户档案「读出来」，给小满 OKKICRM 等上游系统做去重判断，或为下游同步策略提供「目标侧是否已存在」的事实依据。这个接口就是一个典型的「纯查询」数据源策略：它不写入任何目标，只负责稳定地把客户主数据拉回平台，供后续写入策略按业务编码比对与定位。

接口能力总览

• 接口形态：表单数据查询接口，路径为 /plus/cgi-bin/open/applications/{applicationId}/forms/{formModelId}。
• 认证方式：在轻易云适配器中以平台封装后的鉴权头调用，业务方无需手动管理 token，但需在连接器中维护应用与表单模型 id。
• 请求参数：applicationId、formModelId（必填），startTime、endTime（时间范围增量），orderField（默认 createDate）、isAsc（默认 false）、page、pageSize（默认 1/50）。
• 响应结构：data.list 为实际列表数据，平台通过 autoFillResponse: true 自动解析响应，otherResponse.statusKey 指向 data.list。
• 增量与分页模式：以 createDate 降序分页拉取，调度上常见 1-59/4 8-23 * * * 的高频小窗口增量。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，这个接口通常以「查询型数据源策略」接入。配置上有几个关键动作：

1. 连接器选型：使用平台内置的道一云·七巧适配器，填入应用 id（applicationId）与客户表单模型 id（formModelId），由适配器统一封装鉴权。
2. 响应映射：由于平台启用了 autoFillResponse: true，轻易云的字段映射器会自动以 data.list 为基准展开列表，无需再手写 JS 解析。
3. 字段映射器：把 公司 映射到通用概念 customer_name，把 用于外键关联 映射到 customer_code，把 extend.id 映射到 form_instance_id，方便后续策略复用。
4. 目标侧配置：Target 显式配置为「写入空操作」，意味着该策略只读不写；查询结果会落到平台中间表，供下游「小满客户=>道一云客户ok」等同步策略通过 _mongoQuery 按 用于外键关联 反查。
5. 调度策略：通常采用 1-59/4 8-23 * * * 这种「高频小窗」模式，配合 {{LAST_SYNC_TIME}} 增量游标，保证白天业务时段的数据新鲜度。

跨方案实战要点

1. 业务编码是去重的灵魂：用于外键关联 字段必须稳定且唯一，所有跨系统客户比对都应优先走它，而不是模糊匹配公司名。
2. extend.id 务必走深路径：更新接口要的是 32 位表单实例 id，开发中很容易漏写 .extend.id，导致更新 404。
3. 增量游标用毫秒：道一云的时间范围参数单位是毫秒，模板里的 000 不能漏，否则会拉到全量历史。
4. 降序分页更稳：默认 isAsc=false，按 createDate 倒序拉取，能更好地应对并发写入，避免边界漏单。
5. Target 配置为空操作要明示：纯查询策略要把 Target 明确配成「写入空操作」，既能让调度系统正确识别策略类型，也能避免误触发写入动作。
6. 响应解析交给平台：开启 autoFillResponse，把 data.list 的展开逻辑交给轻易云字段映射器，能省掉大量定制化脚本。

踩坑复盘

1. 时间戳单位搞错：直接把秒级时间戳塞进 startTime/endTime，导致查询窗口为空或拉全量。稳妥的做法是统一在模板里追加 000 转毫秒。
2. 主键路径取错：误把 content.id 当成表单实例主键，而真正的 id 藏在 content.extend.id。更新调用时直接报「记录不存在」。
3. 同名公司覆盖风险：仅按「公司」名称做去重，结果把同名不同主体的客户覆盖。务必先用 用于外键关联 锁定唯一记录，再决定新增还是更新。
4. 增量与全量混跑：没启用 {{LAST_SYNC_TIME}} 模板，第一次跑全量、第二次又跑全量，触发 API 限流。建议先回填历史游标再切增量。
5. Target 误配写入：纯查询策略错配了写入目标，触发不必要的下游调用。Target 应显式设为「写入空操作」。

何时选用

当业务需要「先查后写」、用业务编码判断目标侧是否已存在某条客户记录，并据此决定新增或更新时，这个查询接口是最合适的数据源策略。如果你的链路是单向拉取、不需要比对，或者目标系统本身已经提供 upsert 语义，则不必额外增加一层纯查询策略，直接同步即可。