轻易云
注册体验

金蝶云星空供应商列表查询接口字段手册权威教程(ExecuteBillQuery / BD_Supplier)

· 工程最佳实践· 9 次浏览· 约 6 分钟读完
金蝶云星空钉钉executeBillQuery供应商主数据数据集成轻易云增量同步

这个接口解决什么问题

在金蝶云星空与钉钉、SRM、费控等下游系统集成的真实场景中,「供应商主数据」是所有采购、付款、对账流程的源头。我们需要在金蝶侧把 BD_Supplier 表里的供应商主数据(编码、名称、组织、结算、税务、分类等)按增量方式稳定拉出来,作为下游系统的主数据源或映射基准。该接口采用金蝶 WebAPI 的 executeBillQuery,按审核日期(FAuditDate)增量同步,落地为可被任意下游复用的数据对象。

接口能力总览

  • 认证方式:金蝶云星空 WebAPI 标准签名(API Key / Secret + 账套 + 用户),通过第三方应用注册获取。
  • 请求方式:POST,表单 ID 为 BD_Supplier(供应商主数据表)。
  • 请求体关键字段:FormId、FieldKeys(字段选择)、FilterString(过滤条件,如 FAuditDate>='{{LAST_SYNC_TIME|dateTime}}')、Limit、StartRow、OrderString。
  • 响应结构:标准 JSON,包含多条记录,每条记录以字段名为键、值为字符串(注意:即便数值/日期字段也以字符串返回)。
  • 分页模式:基于 StartRow + Limit 偏移分页,推荐 Limit ≤ 2000,需要循环直到返回行数 < Limit。
  • 增量模式:以审核日期(FAuditDate)为增量游标,LAST_SYNC_TIME 取上次最大审核时间,定时每日 3:34 触发(34 3 * * *)。
  • 策略类型:纯 QUERY,只读金蝶,不下写。

典型字段映射

字段名类型含义实战注意事项
FSupplierIdstring供应商主键metadata.id 必须配置此字段,跨系统匹配的唯一锚点
FNumberstring供应商编码业务编码,推荐作为与下游系统(钉钉/SRM)匹配键
FNamestring供应商名称显示名,注意可能含全角/半角差异,清洗时统一 trim
FCreateOrgId_FNumberstring创建组织编码多组织场景必带,否则归属组织丢失
FUseOrgId_FNumberstring使用组织编码多组织供应商可见范围,跨组织集成时强校验
FCorrespondOrgId_FNumberstring对应组织编码用于多组织间映射,常被忽略
FAddressstring通讯地址多行文本,需保留换行
FRegisterAddressstring注册地址与通讯地址分开存,合规审计使用
FZipstring邮政编码字符串格式,避免被强转为整数丢失前导零
FPayCurrencyId_FNumberstring结算币别编码跨币种集成必带
FSettleTypeId_FNumberstring结算方式编码电汇/承兑/信用证等
FPayCondition_FNumberstring付款条件编码月结/货到付款等
FChargeId_FNumberstring收款方编码实际收款的法人主体
FTaxType_FNumberstring税分类编码一般纳税人/小规模
FTaxRegisterCodestring税务登记号老税号,可能为空
FSOCIALCRECODEstring统一社会信用代码18 位,作为最权威的主数据标识,跨系统优先生效
FRegisterCodestring工商登记号营业执照号
FRegisterFundstring注册资金(万元)小数,字符串传输,使用时 toDecimal
FFoundDatestring创立日期日期字符串,格式 yyyy-MM-dd
FLegalPersonstring法人代表姓名,合规导出时需脱敏
FTendPermitstring生产经营许可证号特殊行业必备
FSupplierClassify_FNumberstring供应商分类编码分层管理
FSupplyClassifystring供应类别物料/服务
FSupplierGrade_FNumberstring供应商等级(A/B/C)采购策略依据
FGroupstring供应商分组自定义分组
FCompanyNature_FNumberstring公司性质国企/民企等
FCompanyScale_FNumberstring公司规模大/中/小
FTrade_FNumberstring所属行业编码行业分类
FTendType_FNumberstring经营类型生产/贸易/服务
FInvoiceTypestring发票类型增值税专用/普通
FTaxRateId_FNumberstring默认税率编码采购默认税率
FPRICELISTID_FNumberstring默认价目表编码采购价格来源
FDiscountListId_FNumberstring默认折扣表编码默认折扣
FMinPOValuestring最小订单量小数,需 toDecimal
FPayAdvanceAmountstring单次预付额度小数,需 toDecimal
FProviderId_FNumberstring供货方编码实际供货主体
FWipStockId_FNumberstring默认 WIP 仓库在制品仓库
FVmiBusinessstring是否启用 VMI复选框,Y/N
FVmiStockId_FNumberstringVMI 仓库编码VMI 业务专用仓库
FDeptId_FNumberstring负责部门编码业务归属部门
FStaffId_FNumberstring负责人编码业务员
FNeedConfirmstring需要确认复选框,Y/N
FBusinessStatusstring业务状态暂存/已审核等
FFreezeLimitstring冻结范围多选下拉,逗号分隔字符串
FFreezeDatestring冻结日期日期字符串
FStartDate / FEndDatestring生效/失效日期主数据有效期,集成时建议校验
FShortNamestring简称列表展示
FDescriptionstring描述多行文本
FWebSitestring公司网址多行文本,可能多条
FCountry_FNumber / FProvincial_FNumber / FLanguage_FNumberstring国家/地区/语言编码引用辅助资料
FParentSupplierId_FNumberstring汇总公司/上级供应商集团架构
FCustomerId_FNumberstring对应客户编码同一法人对应客户
FSettleId_FNumberstring结算方编码实际结算主体
FFinanceDescstring财务描述多行文本

在轻易云上如何配置

在轻易云数据集成平台里,我们通常用「金蝶云星空适配器 + 数据查询策略」来封装这个接口:

  1. 数据源配置:在轻易云的「数据源管理」里新建金蝶云星空连接,填入账套标识、应用 ID、API Key/Secret、用户账号;轻易云会内置签名生成逻辑,无需手工算签名。
  2. 接口选择:轻易云的适配器把 executeBillQuery 抽象成可视化的「表单查询」节点,只需选择 FormId = BD_Supplier,从字段列表里勾选需要的 FieldKeys,平台会自动拼接请求体。
  3. 增量配置:在轻易云的策略编辑器里,FilterString 用模板语法 FAuditDate>='{{LAST_SYNC_TIME|dateTime}}',平台内置 LAST_SYNC_TIME 变量持久化,首次全量、之后增量全自动。
  4. 字段映射器:轻易云的字段映射器会自动把 F*_FNumber 这类关联字段展开为「编码 + 名称」两种形态,下游可以直接用编码做匹配、用名称做展示。
  5. 分页与限流:轻易云默认 Limit=2000,自动循环分页;遇到金蝶侧 429/超时,平台会指数退避重试,并把每页写入检查点,中断后可断点续跑。
  6. 写入下游:本策略为 QUERY,结果可直接写入轻易云的「数据集市」,供钉钉、SRM、BI 等多目标订阅;也可以作为后续 SYNC 策略的主数据源。

跨方案实战要点

  1. 优先用 FSOCIALCRECODE 做跨系统唯一键:多个客户方案里,只要下游系统支持,统一社会信用代码比 FNumber 更稳定(编码变更不影响)。
  2. FNumber 与 FSupplierId 不要混用:FSupplierId 是数据库主键(可能跨账套重复),FNumber 是业务编码;下游匹配一律用 FNumber。
  3. 多组织三件套必须全量取:FCreateOrgId_FNumber / FUseOrgId_FNumber / FCorrespondOrgId_FNumber 缺一不可,否则跨组织采购会丢归属。
  4. 财务结算字段单独成组:FPayCurrencyId / FSettleTypeId / FPayCondition / FChargeId / FTaxRateId 这组字段在下游费控、SRM 都要落地,建议作为一个 FieldKeys 子集整体勾选,避免漏字段。
  5. 日期与数值字段以字符串返回:金蝶接口统一把日期、小数以字符串返回,落地时要 toDate / toDecimal,否则下游 Java/JS 强转会出错。
  6. 冻结与有效期字段要做业务校验:FBusinessStatus / FFreezeLimit / FStartDate / FEndDate 在同步给钉钉或下游时必须过滤,否则会把已冻结或失效的供应商推到下游。

踩坑复盘

  1. 踩坑:FilterString 用错了字段导致漏数据。稳妥的做法是审核日期(FAuditDate)而不是创建日期或修改日期,后者在反审核/驳回场景下会丢数据。
  2. 踩坑:Limit 设太大被金蝶服务端截断或超时。轻易云默认 2000 是经过多个客户压测的,稳妥区间在 1000-2000,超过 5000 极易超时。
  3. 踩坑:F*_FNumber 关联字段取不到名称。金蝶只返回编码,名称需要在下游系统单独缓存或反查;轻易云的字段映射器可以一次性拉出「编码 + 名称」组合,但要勾选对应辅助资料的 FieldKey。
  4. 踩坑:复选框 / 多选下拉返回值格式混乱。FNeedConfirm / FVmiBusiness 是 "true"/"false" 或 "Y"/"N",FFreezeLimit 是逗号分隔的编码串,下游必须按字符串解析,不要假定为数组。
  5. 踩坑:增量游标时钟漂移。LAST_SYNC_TIME 必须用金蝶侧返回的最大 FAuditDate + 1 秒,而非本地当前时间;否则同一天内多次审核的数据会漏同步。

何时选用

当集成场景涉及「把金蝶云星空作为供应商主数据唯一可信源,向钉钉、SRM、费控、BI 等下游分发」时,选用此接口;若下游只是偶发查询单家供应商,直接调用金蝶单据接口更轻量。注意:本接口仅供查询,不写入金蝶,主数据创建/修改仍需走供应商保存接口。

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-272-ok-f008

评论