小满OKKICRM与金蝶云星空基础资料同步接口字段手册
这个接口解决什么问题
在 CRM 与 ERP 的双向集成场景中,小满 OKKI CRM 负责客户线索与销售订单录入,金蝶云星空承担物料主数据与财务结算。我们要把金蝶物料推给小满作为产品档案,把 CRM 中的客户及联系人推给金蝶建立客户主数据,再把金蝶已审核的销售订单回流到 CRM 形成业务闭环。跨系统编码不一致、增量依据难统一、联系人依赖客户档案,是这类集成的典型痛点。
接口能力总览
认证方式:金蝶云星空采用 OAuth2 + 应用密钥换取 access_token;小满 OKKI CRM 使用 API Key + 签名机制,凭证统一放入密钥管理服务,不在方案文档中明文出现。
请求结构:金蝶侧以 form_id 区分单据(BD_MATERIAL、BD_Customer、SAL_SaleOrder 等),支持分页参数 PageIndex/PageSize,字段路径通过点号导航(如 FCustId.FNumber、FMaterialId.FNumber)。小满侧按资源对象划分(/v1/product、/v1/company、/v1/invoices/order 等),列表接口返回分页结构,写入接口按业务编号幂等。
响应结构:金蝶返回 Result 数组含 Status、Message、PK;小满返回标准 JSON 含 code、msg、data。错误码 5xx 触发重试,4xx 业务校验失败直接落失败表。
分页与增量:金蝶增量依据 FModifyDate 或 FApproveDate,小满增量依据 order_time 或 start_time/end_time。全量场景移除时间过滤,目标端按编码幂等写入。
典型字段映射
以金蝶物料推小满产品、金蝶销售订单推小满销售订单为例,核心映射如下:
| 源字段 | 目标字段 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|---|
| FNumber | product_no | String | 物料编码 | 跨系统唯一键,直接传递作为对照 |
| FName | name | String | 物料名称 | 注意去除首尾空格 |
| FBaseUnitId.FName | cost_unit | String | 基本单位 | 多单位场景需区分成本/数量/价格单位 |
| FModifyDate | — | DateTime | 修改日期 | 增量过滤条件 |
| FBillNo | order_no | String | 单据编号 | 订单幂等键 |
| FCustId.FNumber | company | String | 客户编码 | 需联查小满 company_id |
| FDate | account_date | Date | 业务日期 | 格式转为 YYYY-MM-DD |
| FExchangeRate | exchange_rate | Decimal | 汇率 | 小满为万分位,金蝶为小数时需 ×100 |
| FMaterialId.FNumber | product_no | String | 物料编码 | 依赖物料同步完成 |
| FQty | count | Decimal | 数量 | 明细行字段 |
| FPrice | unit_price | Decimal | 单价 | 注意精度 |
在轻易云上如何配置
在轻易云数据集成平台里,这类双向集成通常采用「查询策略 + 同步策略」组合配置:每个查询策略独立配置源端适配器(金蝶表单/小满开放接口),输出到平台数据集市;同步策略在轻易云的字段映射器里直接拖拽字段,编码映射通过「对照表」组件维护,自动按主键执行 upsert。
轻易云内置了金蝶云星空的标准单据适配器(物料、客户、销售订单等),点选 form_id 即可生成数据源;小满侧的 /v1 接口通过自定义适配器接入。增量时间戳由轻易云自动维护 LAST_SYNC_TIME,无需手工记录。失败数据进入死信表,支持按策略或时间窗手动重跑。
跨方案实战要点
- 编码一致是关键前置:物料编码、客户编码必须在两套系统里保持一致,否则后续订单联查全部失败。建议初始化时先做编码规则梳理,再启动同步。
- 联系人依赖客户档案:小满客户→金蝶客户联系人策略必须等待客户主数据同步完成,否则联系人无所属客户。在轻易云里通过「策略依赖」配置强制执行顺序。
- 订单同步只推已审核单:金蝶销售订单未审核时数据不稳定,建议过滤 FDocumentStatus='C' 后再同步,避免推错单。
- 汇率与单位换算:金蝶汇率是小数,小满要求万分位,映射时要 ×100;单位字段需要拆分为多个目标字段时,建议用轻易云的字段映射器一次配置多路输出。
- 增量与全量分开配置:日常走增量(FModifyDate / order_time),初始化或修复时切全量,移除时间过滤;两种模式不要混用,否则容易漏单或重复。
- 失败重试分级:5xx 与 429 走指数退避,4xx 业务校验失败直接落失败表,不浪费重试次数。
踩坑复盘
- 客户编码映射缺失:小满 serial_id 与金蝶 FNumber 规则不一致时,联系人、订单联查全部失败。稳妥的做法是先在两套系统分别建立编码对照表,跑一次离线校验,确认无遗漏后再上线。
- 物料分组映射漏配:金蝶物料同步到小满后,产品分组未映射导致部分产品在小满前端不可见。在轻易云里通过「查询小满产品分组」与「查询金蝶物料分组」联查,生成对照表后再写入。
- 订单重复推送:同一订单在金蝶审核后被多次同步,小满侧没有按 order_no 幂等导致数据翻倍。稳妥的做法是在目标端写入前先按 order_no 查询,存在则走更新分支,不存在再新增。
- 业务员映射断裂:金蝶业务员编码与小满昵称不一致,订单业绩归属人字段为空。这里容易翻车,建议单独跑一次「业务员映射预热」,把对照表灌满后再启动订单同步。
- 限流触发雪崩:金蝶 API 触发 429 后,重试间隔太短导致二次限流。稳妥的做法是把 429 重试间隔固定到 60s,避免指数退避反而压垮源端。
何时选用
适用于 CRM 与 ERP 双向集成、客户主数据由 CRM 维护、物料主数据由 ERP 维护、销售订单需要跨系统对账的场景。若两套系统已有中间数据中台,或编码规则完全不一致且无法在初始化阶段对齐,则建议先做编码治理再集成。