这个接口解决什么问题

在 CRM 与 ERP 之间打通销售订单链路时,产品主数据始终是第一步。小满 OKKICRM 的「产品查询」接口负责把 CRM 一侧的产品档案同步出来,供下游金蝶云星空的物料基础资料、销售订单行项目做字段级映射与对照。它是销售订单集成的「前置字典」,缺了这步,后续订单同步极易出现编码不一致、金额字段缺失等问题。

接口能力总览

接口路径:/v1/product/list,请求方法 GET,策略类型为 QUERY_ONLY(只读查询,不写目标)。
认证方式:OAuth 风格的 access_token 接入,与小满 CRM 其他接口一致;在轻易云里通常由适配器统一托管刷新。
响应结构:返回产品列表,每条记录包含基础信息、分类信息、成本与价格信息、订货量信息;product_id 为主键,product_no 为编码键。
分页模式:start_index(页码,默认 1)+ count(每页条数,默认 20)的经典页码分页,适合中小规模产品库。
增量模式:通过 start_time / end_time 按更新时间窗口拉取,支持 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS 两种格式;典型调度为每 20 分钟执行,8:00–22:00 区间。
筛选能力:product_type(1=无规格/2=多规格/3=组合)、removed(默认 0,置 1 可查询已删除产品)便于回溯与对账。
详情补全:列表不含完整字段时,可调用 /v1/product/info,以 product_no 作为 info_key 获取单条详情。

典型字段映射

字段名	类型	含义	实战注意事项
product_id	int	产品主键	metadata.id 配置此字段;源系统内唯一,跨系统对照请用 product_no
product_no	string	产品编码	metadata.number 配置此字段;是与金蝶云星空物料编码(MaterialCode)对照的唯一稳定键
name	string	产品名称	直接映射销售订单行项目的产品名称字段即可
group_id	string	产品分类ID	用于和金蝶物料分类体系映射;一个产品只属于一个分组
group_name	string	产品分类名称	冗余字段,直接展示,可避免频繁跨表关联
image	string	产品图片地址	注意 URL 域名,部分企业环境需要走 CDN 代理
cost_with_tax	object	含税成本	元数据定义为 object,实际可能是数值或包含 amount/currency 的复合结构,集成时务必按真实响应解析
fob	object	离岸价	同样为 object 结构,贸易型企业尤为关注,需与目标系统币种字段匹配
minimum_order_quantity	object	最小订货量	object 结构,部分方案里实际为数值;映射到金蝶销售订单的「最小起订量」字段

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的调用通常采用内置的「小满 OKKICRM 适配器」:在数据源处选择对应适配器后,平台会自动识别 /v1/product/list 的请求参数与分页结构,无需手写翻页逻辑。

元数据映射:在轻易云字段映射器里,product_id 自动绑定为 id 主键,product_no 绑定为 number 编码键,与下游金蝶云星空的物料编码建立对照关系。
增量调度:平台支持以 start_time / end_time 维护游标,典型策略为 20 分钟一轮,8:00–22:00 生效;非营业时段自动跳过以节省配额。
复杂字段处理:对 cost_with_tax、fob、minimum_order_quantity 这类 object 字段,平台会按 JSONPath 自动展平,常见路径如 $.amount、$.currency,可在映射器里直接选取子节点。
详情补全:若列表字段不全,可在轻易云里配置「按需调用 info_api」,以 product_no 作为 info_key 调用 /v1/product/info,实现列表+详情的两段式拉取。

跨方案实战要点

稳定编码优先于主键:跨系统对照一律使用 product_no,不要把 product_id 直接搬到金蝶——不同环境的主键可能复用或漂移。
object 字段先采样再映射:cost_with_tax 这类字段未真正解析前,不要急于落到目标表;在多个客户项目里,我们通常先抽样 3–5 条真实响应再确定展平路径。
增量窗口保留重叠:按更新时间增量拉取时,务必让 start_time 比上次结束时间提前 2–3 分钟,避免边界数据漏单。
分页上限实测:count 不要直接拉满,真实场景里某些租户在 count=100 时会出现字段截断,稳妥的做法是先按 20–50 测试稳定后再放大。
已删除产品的双面性:removed=1 用于对账非常方便,但生产同步链路里要明确剔除,否则下游会出现「幽灵物料」。
分类体系要二次映射:小满的 group_id 与金蝶物料分类并非一一对应,需要在轻易云里加一层映射表,否则会出现孤立分类。

踩坑复盘

object 字段当数值用:某客户直接把 cost_with_tax 当 float 写入金蝶,结果下游金额全为 null。这里的教训是:object 必须先展平并校验子字段存在性,稳妥的做法是写一段解析脚本,在轻易云里挂到字段映射器的「前置脚本」位置。
增量起点错位导致漏单:仅按 end_time 推进游标,没有把 start_time 回退几分钟,导致边界附近的更新丢失。修复方法是引入「重叠窗口」概念。
多规格类型筛选反了:product_type=2(多规格)与 product_type=1(无规格)混淆,导致下游物料档案类型错配。建议在映射器里加注释或枚举映射表。
info_api 误用列表主键:用 product_id 去调 /v1/product/info,部分租户会返回空。这里的稳妥做法是严格按官方约定,以 product_no 作为 info_key。
图片 URL 跨域/防盗链:同步到下游后图片无法展示,常见原因是 CDN 域名或防盗链 referer 没配。集成时务必确认目标端是否需要中转存储。

何时选用

适用于 CRM→ERP 的产品主数据同步、销售订单行项目字段映射、物料对照与价格/成本信息获取。边界在于:本接口为只读查询,不负责把产品写入金蝶;若需落库,需另行配置金蝶物料写入策略,二者通过 product_no 串联。

小满OKKICRM 产品查询接口字段手册权威教程