销售易结算币别查询接口权威教程：从字段映射到金蝶集成实战

这个接口解决什么问题

在多币种业务场景里，结算币别主数据是销售订单、合同、收款单等单据金额字段的根基。某零售企业把销售易 CRM 与金蝶云星空打通时，最容易翻车的不是订单本身，而是币别没对齐——人民币写成 CNY、 RMB 或者直接空着，导致金额对账时两边对不上。本接口通过销售易 WebAPI /rest/data/v2/query 把结算币别主数据拉出来，作为跨系统币别对照的权威来源，避免下游单据集成时反复修数据。

接口能力总览

• 认证方式：OAuth2 授权码模式，调用前需在销售易开放平台获取 access_token。
• 请求方法与端点：GET /rest/data/v2/query，queryString 传参。
• 请求参数：table（对象 API 名，默认 customEntity70__c）、select（逗号分隔字段列表）、where（过滤条件，SOQL 风格）、limit（每页条数，默认 10，上限 1000）、offset（分页偏移量）。
• 响应结构：标准 { records: [...], totalSize, done }，单条记录为对象字段集合。
• 分页模式：基于 limit + offset 的传统分页；在轻易云里，适配器会按 totalSize 自动算页数并循环拉取，直到 done=true。
• 增量模式：原 API 不提供 lastModifiedTime 增量字段，因此业内多用全量 + 时间窗口过滤的准增量方案。
• 调度建议：典型策略配 */30 23 * * *（每日 23:00、23:30 跑两次），避开业务高峰期。

典型字段映射

在轻易云上如何配置

1. 适配器选型：源系统选「销售易 WebAPI」，接口路径填 /rest/data/v2/query，Table 填 customEntity70__c。
2. 字段映射器：在轻易云字段映射器里，把 id 映射到目标模型的「币别主键」、customItem8__c 映射到「币别编码」、name 映射到「币别名称」，轻易云会自动处理 null 与空字符串归一化。
3. 目标端配置：Target 选「写入空操作」，表示这是纯查询策略，数据落平台后供下游金蝶币对照、单据同步复用。
4. 调度与分页：轻易云的循环器会自动按 totalSize 分页，建议把单页 limit 调到 500 以减少请求次数。
5. 主键校验：开启 idCheck=true，配合 autoFillResponse，避免重复写入。

跨方案实战要点

1. 以金蝶币别编码为基准建对照表：金蝶云星空的币别编码是稳定主数据，销售易侧用 customItem8__c 对齐，销售订单同步时才不会因两端名称差异报错。
2. 币别主数据先于业务单据同步：结算币别策略务必先跑，跑完再触发销售订单、收款单等下游链路，顺序错了就会出现「币别找不到」类异常。
3. name 字段重定义要留意：Source 配置中 response 出现两处 name 描述时，轻易云只取最后一次声明，定义映射前先在平台预览实际响应。
4. 自定义字段含义按策略名反推：customItem8__c、customItem10__c 等无业务标签字段，必须结合策略名称「结算币别」反推含义，不要照搬其他主数据策略的映射。
5. 增量靠时间窗口，不靠 API 增量字段：原 API 不返回 lastModifiedTime，稳妥的做法是在 where 条件里加 LastModifiedDate >= LAST_N_DAYS:1，每天补跑一次保证新币别及时入库。
6. 调度避开业务高峰期：23:00 和 23:30 跑两次是经验值，能避开白天订单写入高峰，也能在凌晨留出重试窗口。

踩坑复盘

• 坑 1：把 name 当编码用。某零售企业集成时直接拿「人民币」去匹配金蝶，结果金蝶那边存的是「CNY」，导致订单金额币别全部对不上。应对：跨系统映射一律走 customItem8__c（编码），name 只做展示。
• 坑 2：customEntity70__c 当成业务字段。把它误以为是币别编码，结果下游全是父对象引用值，根本匹配不到。应对：先在销售易后端打开该对象，看实际存储内容。
• 坑 3：分页 limit 默认 10 不调整。币别主数据条数多时，请求次数暴增，跑一次要十几分钟。应对：把 limit 调到 500~1000，配合轻易云循环器一次跑完。
• 坑 4：增量误用全删全插。以为「查询策略」就重跑覆盖，结果下游缓存的币别编码被刷新掉，正在传输的订单引用了失效编码。应对：币别主数据用 upsert 语义，只新增和更新，不删除。
• 坑 5：调度时间撞上金蝶结算。把币别同步放在凌晨 1:00，恰好和金蝶日结冲突，触发锁表。应对：调到 23:00 和 23:30，错开金蝶结算窗口。

何时选用

适合金蝶云星空与销售易双向集成、需要对齐结算币别主数据的场景；不适合仅做销售易单点查询、或者币种单一无对照需求的轻量集成。多币种、跨国业务、涉及订单与收款跨系统流转的项目强烈建议先建这套币别查询策略。