金蝶云星辰供应商查询接口字段手册权威教程：聚水潭供应链集成实战

这个接口解决什么问题

在聚水潭与金蝶云星辰的供应链集成场景里，供应商主数据是采购订单、采购入库、采购退货、付款等业务的根基。/jdy/v2/bd/supplier 这个接口让我们以分页+增量方式从金蝶拉取供应商档案，用于编码对照、状态同步、采购单据供应商字段映射与开票信息回写，是「查询型策略」最典型的代表。

接口能力总览

• 认证方式：金蝶云星辰 V2 WebAPI 标准鉴权（AppKey/AppSecret 体系），请求头携带访问令牌。
• 请求方法：GET /jdy/v2/bd/supplier，详情接口为 GET /jdy/v2/bd/supplier_detail，按 id 拉取完整档案。
• 请求参数：enable（1 启用/0 禁用/-1 全部）、modify_start_time/modify_end_time（毫秒时间戳区间）、page（默认 1）、page_size（默认 100）。
• 响应结构：列表型返回，每条记录含 id、number、name、enable 等基础字段，以及组织、开票、银行、地址、联系人、自定义字段等扩展对象。
• 分页/增量模式：标准 page/page_size 分页；增量以修改时间毫秒戳为游标。
• 策略类型：QUERY，Target 配置为「写入空操作」，纯查询不落目标。
• 定时任务：默认 */10 * * * *，每 10 分钟一轮。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，金蝶云星辰 V2 已被预置为官方适配器，封装了 /jdy/v2/bd/supplier 的鉴权、分页与时间戳转换。配置时通常这样做：

1. 在「数据源」选择「金蝶云星辰 V2」，填入租户凭证后，轻易云适配器会自动维护 token 刷新。
2. 在策略画布里选「查询星辰供应商信息」模板，Target 选「写入空操作」，明确这是纯查询策略。
3. 字段映射器中，id 自动作为主键，number 作为编码键；增量游标默认为 modify_time，每轮自动续传。
4. 若需把结果转给聚水潭，再加一条下游写入策略，轻易云会自动按 number ↔ supplier_code 做对照。
5. 定时策略默认 */10 * * * *，可在轻易云的调度面板直接调整。

跨方案实战要点

1. number 优先于 name 作为对照键：编码稳定且唯一，名称常因简称、合并、变更而漂移。
2. 增量游标务必用 modify_time，不要用 create_time：新签供应商少，日常 99% 是修改类变更。
3. page_size 不要超过 100：星辰 V2 大于 100 会触发限流或截断，稳妥做法是 50-100 之间。
4. enable=-1 仅用于初始化：全量拉取后，正式增量必须切到 1，避免把禁用供应商反复回写到下游。
5. 多银行账户走 account_entity：平铺字段 bank/bank_account 仅代表首个账户，多账户场景必须解析数组。
6. 行政区划保留 id：跨系统对照时，id 比 name 更耐改名，轻易云字段映射器默认同时保留两者。

踩坑复盘

1. source 元数据 response 字段错配：模板残留物料 API 的 stock_id、barcode、base_unit_id 等字段，与供应商实际返回不符。建议以真实 API 响应为准修正元数据，否则轻易云的字段映射器会提示「字段不存在」。
2. 毫秒时间戳与秒时间戳混用：星辰 V2 用毫秒，但很多团队习惯传秒级时间戳，导致增量窗口为空、全量重拉。在轻易云的适配器里会自动识别单位，但手工脚本需自行校验。
3. invoice_type 枚举值漂移：全电发票上线后新增 5、6，老客户只识别 1-4，导致开票失败。稳妥做法是在轻易云映射器里做枚举兼容层，把未知值兜底为「0 无需开票」并告警。
4. bom_entity 空数组导致下游崩溃：联系人列表为空时，部分下游写入器会把 null 当对象处理。建议在轻易云的目标端加「空数组转空字符串」的清洗规则。
5. enable=0 的供应商仍被采购单引用：禁用供应商若不清洗，会带入历史单据。建议在轻易云的过滤条件里加 enable=1，禁用项单独走归档策略。

何时选用

/jdy/v2/bd/supplier 适用于「供应商档案需要从金蝶云星辰单向同步到聚水潭或其他下游系统」的场景，典型如多系统供应商编码统一、状态联动、开票信息回写。不适用于：双向编辑供应商档案、跨组织级多账套批量迁移、实时单据级供应商校验（应走详情接口或单据接口）。