小满OKKICRM产品查询接口字段手册与跨系统集成实战教程

这个接口解决什么问题

在供应链集成场景里,产品主数据是订单、库存、发货的根基。我们经常需要把 CRM 系统里的产品档案同步到 WMS,保证两边编码、价格、最小起订量一致。「查询小满产品」接口正是承担这一职责:支持按更新时间增量拉取、按类型筛选、分页获取,是产品主数据对账与下游同步策略(例如订单同步、库存同步)的源数据入口。

接口能力总览

• 认证方式:小满 OKKI CRM 标准 API 认证(基于租户凭证的 Header 鉴权),请求头中携带访问令牌。
• 接口地址:/v1/product/list,返回产品列表;如需单条详情,调用 /v1/product/info,以 product_no 作为查询键。
• 请求结构:JSON 风格的请求体或 Query 参数,核心参数为 start_index(页码)、count(每页条数)、start_time/end_time(增量时间窗)、removed(0 正常/1 已删除)、product_type(1 无规格/2 多规格/3 组合)。
• 响应结构:列表形式返回,每条记录包含 product_id、product_no、名称、分类、含税成本、FOB、最小起订量、产品类型等字段;金额与数量字段多为 object 结构,内部含金额与币种。
• 分页与增量模式:分页采用 start_index + count,默认每页 20 条;增量模式按更新时间窗口拉取,定时任务在多个客户方案里普遍配置为每 3 分钟一轮,日间 6–23 点持续运行。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常被封装为「小满 OKKI CRM 产品查询」适配器,挂载在源系统连接下。配置路径一般包括三步:第一,在适配器面板填入小满侧凭证并测试连通;第二,在策略编排里启用「分页拉取」与「按更新时间增量」,把 start_time 映射到轻易云内置的「上次同步时间」游标字段,把 count 控制在 20–100 之间;第三,字段映射器会自动把响应的 object 类型字段(金额、数量)展开成扁平结构,工程师只需在映射画布里把 product_no 对齐到下游 WMS 的 goods_no 即可。对于组合产品,可以在轻易云的「数据处理」节点里加一段 JS 展开子规格,再写入下游。

跨方案实战要点

1. 增量游标一定要持久化:start_time 存到轻易云的「同步状态」里,不能用内存变量,否则重启后会重复拉或漏拉。
2. product_no 是跨系统主键:不要用 product_id 做对账,小满主键在跨系统语义里不稳定,业务编码才是稳定锚点。
3. 金额对象必须二次解析:cost_with_tax、fob、minimum_order_quantity 都是 object,直接当字符串用会丢失币种和单位。
4. product_type 决定下游路由:1 和 2 类型通常直接同步,3 类型组合产品必须先展开,否则下游会按单 SKU 处理导致库存错乱。
5. deleted 数据单独处理:removed=1 的数据建议走另一条清理链路,不要混入正常增量流,避免下游误以为数据抖动。
6. 定时频率与时间窗匹配:3 分钟一轮是常见配置,但要确保 end_time 与 start_time 之间留足覆盖(至少 2 个周期),否则边界数据容易丢失。

踩坑复盘

• 金额字段取不到值:把 cost_with_tax 直接当字符串读取,结果只拿到对象引用。稳妥的做法是在轻易云字段映射器里勾选「展开 object」,或者加一段表达式取值。
• 组合产品漏展开:product_type=3 的产品有父 SKU 和多个子 SKU,直接当单条同步会导致下游库存成倍虚增。这里容易翻车,稳妥的做法是在数据处理节点按规格明细展开后再写入。
• 增量边界丢数据:end_time 设置成当前时间,下一轮 start_time 紧接上一轮 end_time,边界恰好被两条记录横跨时就丢了。稳妥做法是 start_time 向前回拨 1–2 分钟。
• 多规格产品名称重复:多 SKU 共用同一个 product_no 但 name 相同,下游做去重时会把它们当成同一条。建议在 WMS 侧以 product_no + 规格编码作为唯一键。
• 凭证过期静默失败:小满令牌过期后接口仍返回数据但内容为空,排查时容易被误导。稳妥做法是在轻易云里开启「响应体非空校验」与告警。

何时选用

当业务需要把 CRM 里的产品主数据同步到 WMS 或电商后台,且希望按更新时间做增量拉取、按产品类型做差异化处理时,优先选用该接口;若下游只需要一次性全量快照,直接调用列表接口即可,不必上增量。如果涉及复杂的价格策略、阶梯报价,应另选报价类接口,本接口不承载此类能力。