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

这个接口解决什么问题

在 CRM 与 ERP 的双向集成场景中,「产品主数据」往往是订单、库存、价格的共同底座。小满 OKKICRM 的 /v1/product/list 接口用于按更新时间增量拉取产品主数据,为聚水潭侧的商品映射、订单同步、报价计算提供统一的产品字典。典型用途包括产品主数据同步、产品分类关联、成本价与离岸价获取,是销售订单集成链路上游的「数据源开关」。

接口能力总览

• 认证方式:小满 OKKICRM 开放平台 OAuth 风格的 AccessToken,通常由聚水潭侧的连接器统一托管刷新。
• 请求方式:POST /v1/product/list,JSON Body。
• 可传筛选条件:product_type(1=无规格、2=多规格、3=组合)、update_time_start/update_time_end(增量时间窗)、page/page_size(分页)。
• 响应结构:通常为 { code, message, data: { items: [...], total } },列表元素即产品对象。
• 分页模式:经典 page + page_size 组合,推荐在轻易云里把 page_size 设到平台允许的上限以减少请求次数。
• 增量模式:基于 update_time 字段的窗口式增量,稳妥做法是上一次窗口结束时间 -1s ~ 当前时间,避免边界漏单。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,小满「产品查询」通常被封装为一个只读源端适配器:注册应用后,平台托管 Token 刷新与限速;字段映射器把 product_id/product_no/name 等自动对接到聚水潭商品模型;调度器按 crontab: 15 7-22 * * * 每 15 分钟触发,Target 配置为「写入空操作」,即纯查询策略,不回写小满。增量键推荐直接选用平台内置的「按更新时间窗口」模式,平台会自动记忆上一次边界。

跨方案实战要点

1. 产品类型先分流:product_type 决定下游 SKU 写入逻辑,集成时务必先按类型分桶,再决定是否需要展开多规格子项。
2. 分类先于产品:多个真实项目里我们都发现,先同步 /v1/product/groups 再写产品,可以显著降低脏数据率。
3. 金额对象一律按子字段解析:cost_with_tax、fob 是 object,务必明确币种与精度,避免被默认 0 覆盖。
4. product_no 是稳定锚点:product_id 在某些后台重导后会变,真正稳定的是 product_no,建议在下游把 product_no 作为外部编码唯一键。
5. 图片链接做转存而非直连:小满图床常带签名过期,直接落库会被前端展示侧判定为失效。
6. 增量窗口别忘了去重:update_time 同一秒内可能多条,稳妥做法是用 product_id 在下游做幂等 upsert。

踩坑复盘

• 坑 1:把 group_name 当 ID 用。它是冗余展示字段,跨系统后名称会被改写,导致原本挂好的分类链路全断。
• 坑 2:金额对象当成数值直接相加。cost_with_tax 是 object,直接 + 会报错或得到拼接字符串。
• 坑 3:page_size 设太大触发限流。小满侧对单次返回体大小有限制,真实场景中超过平台允许上限会被截断或拒绝。
• 坑 4:增量漏单。增量窗口没有包含 update_time == last_end 这一秒,边界记录会被遗漏。
• 坑 5:Token 过期未自动续期。凌晨任务偶发 401,根因是长任务跨过了 Token 有效期,需要在轻易云里开启自动刷新。

何时选用

适用于「小满 OKKICRM 作为产品主数据源 + 聚水潭作为下游交易系统」的销售订单链路,需要做产品字典同步、订单商品映射、价格成本对齐等场景。不适用于反向把聚水潭商品回写小满、不涉及产品主数据只查订单明细的场景,以及需要实时强一致而非近实时同步的财务对账场景。