这个接口解决什么问题

「查询小满产品」是小满OKKICRM对外开放的产品主数据查询接口,典型用途是把CRM端的产品档案同步到下游ERP(鼎捷T100、金蝶云星空/星辰等),实现产品编码、分类、成本、价格、订货量等主数据的统一。我们在做CRM与ERP集成时,这一接口几乎是必走的第一步,稳不稳直接决定后续订单、报价链路能不能跑通。

接口能力总览

接口路径:/v1/product/list,GET方法;详情接口/v1/product/info。
认证方式:走小满OKKICRM标准的AccessToken授权,header中携带即可。
请求结构:支持分页(start_index默认1、count默认20)、增量时间窗口(start_time、end_time,格式yyyy-MM-dd或yyyy-MM-dd HH:mm:ss)、产品类型过滤(product_type:1无规格/2多规格/3组合)、是否包含已删除数据(removed:0否/1是)。
响应结构:JSON数组,每条记录对应一个产品,内嵌成本、价格、订货量等结构化字段。
增量模式:严格按更新时间窗口拉取,生产环境常用{{LAST_SYNC_TIME}}到{{CURRENT_TIME}}的滑动窗口。
策略类型:QUERY_ONLY,纯查询,Target端配「写入空操作」,数据落到轻易云中转区供下游策略消费。

典型字段映射

字段名	类型	含义	实战注意事项
product_id	string	小满内部产品唯一ID	系统主键,API内部引用、做详情查询时用
product_no	string	产品业务编号	真正的业务主键,metadata中作为`id`,跨系统映射认这个
name	string	产品名称	metadata中作为`number`,单据显示用
group_id	string	产品分类ID	与ERP物料分组/分类做映射时用
group_name	string	产品分类名称	冗余展示,方便人工核对
image	string	产品图片URL	一般不参与集成,展示场景用
cost_with_tax	object	含税成本	object结构,实际取值要按子字段(`value`/`currency`)拆
cost / cost_currency / cost_unit	string	成本金额/币种/单位	三个一起读,别只取cost
fob	object	离岸价	object结构,国际贸易才用得上
price_min / price_max / price_currency / price_unit	string	价格区间/币种/单位	报价场景必用,注意区间值
minimum_order_quantity	object	最小订货量	object结构,含数值+单位
quantity / quantity_unit	string	货量/单位	库存场景用,跟ERP库存单位对齐

在轻易云上如何配置

在轻易云数据集成平台里,「查询小满产品」已经被封装成开箱即用的适配器。具体做法是:

新建策略时选择「小满OKKICRM-查询小满产品」源系统模板,Target选「写入空操作」。
在轻易云的字段映射器里,product_no会自动作为主键(id),name作为编码(number),无需手动改metadata。
增量参数绑定系统变量{{LAST_SYNC_TIME}}和{{CURRENT_TIME}},平台会自动维护时间游标。
如果需要调详情接口补字段,在「otherRequest」里配info_api=/v1/product/info、info_key=product_no,平台会按主键批量回查。
下游消费方(金蝶/鼎捷的写入策略)直接引用本策略的输出数据集即可,不用重复对接小满API。

跨方案实战要点

主键认product_no,不认product_id:product_id是小满系统内ID,跨系统对不上;product_no才是业务编码,跟ERP物料编码做映射必须用它。
object类型字段一定要拆:成本、价格、订货量这几个字段API返回是object,直接当string用会拿不到值。轻易云字段映射器里可以用表达式取value子字段。
增量窗口别设太宽:生产环境建议单次窗口不超过24小时,避免超时或漏数;每天凌晨定时拉一次比实时轮询更稳。
已删除数据要单独处理:removed=1查的是软删记录,主数据同步通常忽略,但要监控数量,异常暴涨说明上游误操作。
多规格/组合产品注意product_type:无规格(1)、多规格(2)、组合(3)三种产品结构差异大,跟ERP物料结构对的时候要分别处理,不能一刀切。
自定义字段按字段ID读取:像「所属公司」这种自定义字段,字段名就是一段数字ID(如41371572553362),映射时直接按字段ID取,不要尝试找中文名。

踩坑复盘

踩坑一:把product_id当主键做跨系统映射。后果是同一产品在不同系统对不上,数据全乱。稳妥做法是统一用product_no,在轻易云里直接绑定为id。
踩坑二:cost字段取值拿到null。原因是它返回的是object不是纯数值。稳妥做法是在字段映射器里写表达式取cost.value或cost_with_tax.value。
踩坑三:增量拉取漏数。原因是start_time用了本地时区但小满返回的是UTC,边界值正好错位。稳妥做法是轻易云里统一用UTC时间变量,或者在端上补一个小时的冗余窗口。
踩坑四:多规格产品同步到ERP后变成多条物料。原因是没区分product_type,把所有产品当无规格处理。稳妥做法是先按product_type分流,多规格产品在下游ERP展开。
踩坑五:详情接口调用次数爆炸。原因是在列表接口没拿全字段,又对每条记录调详情。稳妥做法是先确认列表接口字段是否够用,不够再走/v1/product/info,并在轻易云里配并发限流。

何时选用

「查询小满产品」适合需要把小满CRM的产品主数据同步到下游ERP(鼎捷、金蝶等)、或搭建统一产品中心数据中台的场景。它是纯查询策略,不直接写目标系统,通常作为整条产品主数据同步链路的「第一步拉取」。如果你的场景是从ERP往CRM写产品,那应该走鼎捷/金蝶端的写入接口,而不是这一支。

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